Add Goal Seek feature with time series, alerts, and historical data

- Goal Seek solver (bisection method) to find metal price / cost thresholds for NSR viability
- Save/manage Goal Seek scenarios with configurable alert frequency (hourly/daily/weekly)
- Email alerts via Resend when NSR crosses target threshold (hysteresis-based)
- NSR time series chart (Recharts AreaChart) with hover tooltips showing full price/cost breakdown
- APScheduler background job for periodic NSR computation and snapshot recording
- Historical seed data: 366 daily snapshots (Feb 2025 - Feb 2026) with real market prices
  - Silver: indexmundi, statmuse, bullion-rates (monthly averages)
  - Gold: ycharts end-of-month prices
  - Copper: LME monthly via ycharts ($/MT -> $/lb conversion)
- Alembic migration for goal_seek_scenarios and nsr_snapshots tables
- Frontend: Goal Seek page with i18n (en, pt-BR, es), save dialog, scenario list
- .dockerignore files for faster Docker builds

Author: vtz

backend/.dockerignore

@@ -0,0 +1,13 @@
+__pycache__
+*.pyc
+*.pyo
+.venv
+venv
+.env
+.env.*
+.git
+.pytest_cache
+.mypy_cache
+*.egg-info
+dist
+build

backend/Dockerfile

@@ -29,5 +29,5 @@ USER appuser
 # Expose port (Railway uses dynamic PORT)
 EXPOSE 8000
 
-# Run uvicorn directly - no entrypoint
-CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8080"]
+# Run migrations, seed demo data, and start server
+CMD ["sh", "-c", "alembic upgrade head && python scripts/seed_snapshots.py && uvicorn app.main:app --host 0.0.0.0 --port ${PORT:-8080}"]

backend/alembic/env.py

@@ -9,7 +9,7 @@
 
 # Import models to register them with Base
 from app.db.session import Base
-from app.models import User, Region, Mine, UserMine  # noqa: F401
+from app.models import User, Region, Mine, UserMine, GoalSeekScenario, NsrSnapshot  # noqa: F401
 from app.config import get_settings
 
 # this is the Alembic Config object

backend/alembic/versions/003_add_goal_seek_and_snapshots.py

@@ -0,0 +1,72 @@
+"""Add goal seek scenarios and NSR snapshots tables
+
+Revision ID: 003_goal_seek
+Revises: 002_geo_fields
+Create Date: 2026-02-12
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import UUID
+
+# revision identifiers, used by Alembic.
+revision: str = '003_goal_seek'
+down_revision: Union[str, None] = '002_geo_fields'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # Goal Seek Scenarios table
+    op.create_table(
+        'goal_seek_scenarios',
+        sa.Column('id', UUID(as_uuid=True), primary_key=True),
+        sa.Column('user_id', UUID(as_uuid=True), sa.ForeignKey('users.id', ondelete='CASCADE'), nullable=False),
+        sa.Column('mine_id', UUID(as_uuid=True), sa.ForeignKey('mines.id', ondelete='SET NULL'), nullable=True),
+        sa.Column('name', sa.String(255), nullable=False),
+        sa.Column('base_inputs', sa.JSON(), nullable=False),
+        sa.Column('target_variable', sa.String(50), nullable=False),
+        sa.Column('target_nsr', sa.Float(), nullable=False, server_default='0'),
+        sa.Column('threshold_value', sa.Float(), nullable=False),
+        sa.Column('alert_enabled', sa.Boolean(), server_default='false'),
+        sa.Column('alert_email', sa.String(255), nullable=True),
+        sa.Column('alert_frequency', sa.String(20), nullable=False, server_default='daily'),
+        sa.Column('alert_last_checked_at', sa.DateTime(timezone=True), nullable=True),
+        sa.Column('alert_triggered_at', sa.DateTime(timezone=True), nullable=True),
+        sa.Column('last_nsr_value', sa.Float(), nullable=True),
+        sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.func.now()),
+        sa.Column('updated_at', sa.DateTime(timezone=True), server_default=sa.func.now()),
+    )
+    op.create_index('ix_goal_seek_scenarios_user_id', 'goal_seek_scenarios', ['user_id'])
+
+    # NSR Snapshots table
+    op.create_table(
+        'nsr_snapshots',
+        sa.Column('id', UUID(as_uuid=True), primary_key=True),
+        sa.Column('scenario_id', UUID(as_uuid=True), sa.ForeignKey('goal_seek_scenarios.id', ondelete='CASCADE'), nullable=False),
+        sa.Column('timestamp', sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.Column('nsr_per_tonne', sa.Float(), nullable=False),
+        sa.Column('nsr_cu', sa.Float(), nullable=False),
+        sa.Column('nsr_au', sa.Float(), nullable=False),
+        sa.Column('nsr_ag', sa.Float(), nullable=False),
+        sa.Column('cu_price', sa.Float(), nullable=False),
+        sa.Column('au_price', sa.Float(), nullable=False),
+        sa.Column('ag_price', sa.Float(), nullable=False),
+        sa.Column('cu_tc', sa.Float(), nullable=False),
+        sa.Column('cu_rc', sa.Float(), nullable=False),
+        sa.Column('cu_freight', sa.Float(), nullable=False),
+        sa.Column('is_viable', sa.Boolean(), nullable=False),
+        sa.Column('metadata_extra', sa.JSON(), nullable=True),
+    )
+    op.create_index(
+        'ix_nsr_snapshots_scenario_timestamp',
+        'nsr_snapshots',
+        ['scenario_id', 'timestamp'],
+    )
+
+
+def downgrade() -> None:
+    op.drop_table('nsr_snapshots')
+    op.drop_table('goal_seek_scenarios')

backend/app/api/compute.py

@@ -7,6 +7,12 @@
 
 from app.nsr_engine.calculations import compute_nsr_complete
 from app.nsr_engine.models import NSRInput, NSRResult
+from app.nsr_engine.goal_seek import (
+    goal_seek,
+    GoalSeekResult,
+    GoalSeekError,
+    GOAL_SEEK_VARIABLES,
+)
 from app.services.metal_prices import get_metal_prices
 
 router = APIRouter()
@@ -248,3 +254,163 @@ async def compute_scenarios(
         raise HTTPException(status_code=422, detail=str(e))
     except Exception as e:
         raise HTTPException(status_code=500, detail=f"Computation error: {str(e)}")
+
+
+# ──────────────────────────────────────────────────────────
+# Goal Seek
+# ──────────────────────────────────────────────────────────
+
+
+class GoalSeekRequest(BaseModel):
+    """Request body for Goal Seek computation."""
+
+    # Base NSR parameters (same as ComputeNSRRequest)
+    mine: str = Field(..., description="Mine name")
+    area: str = Field(..., description="Area within mine")
+    cu_grade: float = Field(..., ge=0, le=100, description="Copper grade (%)")
+    au_grade: float = Field(..., ge=0, description="Gold grade (g/t)")
+    ag_grade: float = Field(..., ge=0, description="Silver grade (g/t)")
+    ore_tonnage: float = Field(default=1000, gt=0, description="Ore tonnage (tonnes)")
+    mine_dilution: float = Field(default=0.14, ge=0, le=1, description="Mine dilution")
+    ore_recovery: float = Field(default=0.98, ge=0, le=1, description="Ore recovery")
+    cu_price: Optional[float] = Field(default=None, description="Cu price ($/lb)")
+    au_price: Optional[float] = Field(default=None, description="Au price ($/oz)")
+    ag_price: Optional[float] = Field(default=None, description="Ag price ($/oz)")
+    cu_payability: Optional[float] = Field(default=None, description="Cu payability")
+    cu_tc: Optional[float] = Field(default=None, description="Treatment charge ($/dmt)")
+    cu_rc: Optional[float] = Field(default=None, description="Refining charge Cu ($/lb)")
+    cu_freight: Optional[float] = Field(default=None, description="Freight ($/dmt)")
+
+    # Goal Seek specific
+    target_variable: str = Field(
+        ..., description="Variable to solve for (e.g., 'cu_price', 'cu_tc')"
+    )
+    target_nsr: float = Field(
+        default=0.0, description="Target NSR value in $/t (default 0 = break-even)"
+    )
+
+    model_config = {
+        "json_schema_extra": {
+            "example": {
+                "mine": "Vermelhos UG",
+                "area": "Vermelhos Sul",
+                "cu_grade": 0.8,
+                "au_grade": 0.15,
+                "ag_grade": 1.5,
+                "target_variable": "cu_price",
+                "target_nsr": 50.0,
+            }
+        }
+    }
+
+
+class GoalSeekResponse(BaseModel):
+    """Response for Goal Seek computation."""
+
+    target_variable: str
+    target_variable_unit: str
+    target_nsr: float
+    threshold_value: float
+    current_value: float
+    current_nsr: float
+    delta_percent: float
+    is_currently_viable: bool
+    converged: bool
+    iterations: int
+    tolerance_achieved: float
+    bound_hit: str = ""  # "lower", "upper", or "" — when no exact solution in range
+
+
+class GoalSeekVariablesResponse(BaseModel):
+    """Available variables for Goal Seek."""
+
+    variables: List[dict]
+
+
+@router.get("/compute/goal-seek/variables", response_model=GoalSeekVariablesResponse)
+async def list_goal_seek_variables() -> GoalSeekVariablesResponse:
+    """List all variables available for Goal Seek."""
+    variables = []
+    for name, (direction, lower, upper, unit) in GOAL_SEEK_VARIABLES.items():
+        variables.append(
+            {
+                "name": name,
+                "direction": direction,
+                "unit": unit,
+                "lower_bound": lower,
+                "upper_bound": upper,
+            }
+        )
+    return GoalSeekVariablesResponse(variables=variables)
+
+
+@router.post("/compute/goal-seek", response_model=GoalSeekResponse)
+async def compute_goal_seek(request: GoalSeekRequest) -> GoalSeekResponse:
+    """
+    Goal Seek: find the value of a variable that yields a target NSR.
+
+    Like Excel's Goal Seek, but for NSR calculations. Finds the minimum
+    metal price (or maximum cost) needed for viability.
+
+    Example: "What Cu price do I need for NSR = $50/t?"
+    """
+    try:
+        # Fetch live prices if not provided
+        cu_price = request.cu_price
+        au_price = request.au_price
+        ag_price = request.ag_price
+
+        if cu_price is None or au_price is None or ag_price is None:
+            live_prices = await get_metal_prices()
+            if cu_price is None:
+                cu_price = live_prices.cu_price_per_lb
+            if au_price is None:
+                au_price = live_prices.au_price_per_oz
+            if ag_price is None:
+                ag_price = live_prices.ag_price_per_oz
+
+        nsr_input = NSRInput(
+            mine=request.mine,
+            area=request.area,
+            cu_grade=request.cu_grade,
+            au_grade=request.au_grade,
+            ag_grade=request.ag_grade,
+            ore_tonnage=request.ore_tonnage,
+            mine_dilution=request.mine_dilution,
+            ore_recovery=request.ore_recovery,
+            cu_price=cu_price,
+            au_price=au_price,
+            ag_price=ag_price,
+            cu_payability=request.cu_payability,
+            cu_tc=request.cu_tc,
+            cu_rc=request.cu_rc,
+            cu_freight=request.cu_freight,
+        )
+
+        result = goal_seek(
+            base_input=nsr_input,
+            target_variable=request.target_variable,
+            target_nsr=request.target_nsr,
+        )
+
+        return GoalSeekResponse(
+            target_variable=result.target_variable,
+            target_variable_unit=result.target_variable_unit,
+            target_nsr=result.target_nsr,
+            threshold_value=result.threshold_value,
+            current_value=result.current_value,
+            current_nsr=result.current_nsr,
+            delta_percent=result.delta_percent,
+            is_currently_viable=result.is_currently_viable,
+            converged=result.converged,
+            iterations=result.iterations,
+            tolerance_achieved=result.tolerance_achieved,
+            bound_hit=result.bound_hit,
+        )
+
+    except GoalSeekError as e:
+        raise HTTPException(status_code=422, detail=str(e))
+    except ValueError as e:
+        raise HTTPException(status_code=422, detail=str(e))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Goal Seek error: {str(e)}")