11. Developer Handoff — Building a Web Version

11.1 Backend¶

• Existing Python modules are stateless enough to wrap as REST or RPC handlers: ingest, analyze, snapshot, normalize.

• Recommended stack: FastAPI (async optional) + Pydantic models mirroring performance_latest.json.

11.2 Frontend¶

• React (or Next.js) consuming the same JSON contract; charts: Chart.js or Recharts; auth layer for multi-tenant.

11.3 Data contract — performance_latest.json¶

Top level:

{
  "date": "YYYY-MM-DD",
  "week_number": "YYYY-Www",
  "spy_price": 0.0,
  "groups": {
    "ira_top5":       { "kpi": { ... }, "holdings": [ ... ] },
    "brokerage_top5": { "kpi": { ... }, "holdings": [ ... ] },
    "conviction9":    { "kpi": { ... }, "holdings": [ ... ] },
    "my_ira":         { "kpi": { ... }, "holdings": [ ... ] },
    "my_brokerage":   { "kpi": { ... }, "holdings": [ ... ] }
  }
}

• kpi: aligns with KPI_COLS (see performance_tracker.py).

• holdings: rows align with HISTORY_COLS for fields present (open positions only in holdings array).

This object is the canonical “dashboard DTO” for API GET /performance/latest.

11.4 Authentication and tenancy¶

• Each user must supply their own IBD exports (licensing) and broker connections (read-only portfolio API or file upload). Secrets for broker OAuth must never hit the methodology engine logs.

11.5 Scaling¶

• yfinance: throttle, cache by (ticker, day), consider vendor APIs at scale.

• LibreOffice: .xls conversion is CPU + process heavy — move to server-side queue (Celery/RQ) or require CSV upload only in SaaS.

• Filesystem: Current design assumes local paths; SaaS needs object storage (S3/GCS) keyed by tenant_id/run_id.

11.6 Path to data-source independence (“Path 2”)¶

• Replace IBD columns with internally computed RS/EPS proxies from adjusted OHLCV (52-week highs, EPS estimates from another feed), replicating sorts without IBD files. Keep formula layer (capm_wacc) unchanged; swap ingest adapters only.

11.7 IP considerations¶

• Methodology (math, sort orders, beta penalty) is your IP.

• IBD raw screens are subscriber data — do not redistribute; SaaS should store user-private copies with clear ToS.