web/README.md

OncoDSL Lab — React/Next.js front end (Stage 1 MVP)

Interactive front end for the genetic-programming engine. Talks to the FastAPI backend over JSON + Server-Sent Events. Reuses the same DSL, airgap harness, GP engine, and data the Streamlit viewer reads — but shows the GP evolving live, with a button-gated reveal at the end.

┌─────────────┐    POST /runs        ┌────────────────────┐
│             │ ───────────────────▶ │  FastAPI worker    │
│  Lab page   │  GET /runs/{id}/stream│  thread runs the  │
│ (Next.js)   │ ◀─── SSE per-gen ────│  engine + permut. │
│             │  POST /evaluate      │                    │
└─────────────┘ ───────────────────▶ └────────────────────┘

The Lab is client-side (App Router "use client") because it manages SSE, sliders, and reveal state.

Run

# 1) Backend (Python) — needs data/processed/{clinical,expression}.parquet
cd ..
source .venv/bin/activate
uvicorn api.app:app --reload          # :8000

# 2) Frontend (Node ≥ 20)
cd web
npm install
npm run dev                           # :3000

Open http://localhost:3000.

Override the API base URL with NEXT_PUBLIC_API_URL:

NEXT_PUBLIC_API_URL=http://localhost:8001 npm run dev

The Streamlit viewer (streamlit run app/viewer.py) is unaffected — it still reads the persisted MSI artefacts via the legacy /run /result /reveal endpoints.

What's on the page

5 sections, top to bottom:

1. Objective — pick MSI separation (AUROC) or Mutation burden (negative correlation). Survival and Unsupervised are Stage 2.
2. Parameters — generations, population, genes-per-set, λ, seed, prefilter top-N, permutations. Sensible defaults.
3. Run — POST /runs, open SSE.
4. Live view — Recharts line chart of best & median fitness per generation, updated as events arrive; population grid showing the top candidates with survivors in the accent and discarded ones faded.
5. Result + Reveal & evaluate — once the GP finishes, the winning program's metrics show. Click "Reveal & evaluate" against a reference gene set (MMR or immune) to translate the opaque IDs back to symbols and highlight the overlap.

What's NOT here (Stage 2 territory)

• React Flow program diagram. Animations. Free-text objective. Survival / unsupervised paths. Cross-cohort validation.