implementationplan.md

# implementationplan.md — BioFlow AI Implementation Plan

> **Current status (v4.0, 2026-08-05):** Track A prototype completed. Track B sprints 1–10 completed. Additional sprints 11–15 (structure suite, docking, MD, ADMET, function, sequencing, design system) shipped. See Track B below.

## Track A — Prototype Sprint (18 Days) ✅ Completed

One golden path only: **Sequence In → BLAST → AI-interpreted report.** Everything else is Track B.

### Day 0 — Pre-flight (~2 hrs, today)
- [x] Create `bioflow-frontend` and `bioflow-backend` repos
- [x] Create Supabase project, run schema.md migrations
- [x] Create Cloudflare R2 bucket
- [x] Get API keys: Gemini (Resend optional for prototype)
- [x] Confirm NCBI BLAST URL API access — **no key required, but max 1 request every 10s**; build this constraint in from day one, not as a fix later

### Days 1–2 — Foundations
**Backend**
- FastAPI scaffold + `/health`
- Supabase client wrapper (`core/db.py`), R2 wrapper (`core/storage.py`)
- Pydantic models for `jobs` / `job_steps`
- `POST /jobs` (create, status=`queued`), `GET /jobs/{id}`

**Frontend**
- Next.js + TS + Tailwind scaffold, design tokens from design.md → `tailwind.config.ts` / `globals.css`
- Supabase client (anon key) + anonymous session on first visit
- Layout shell, static landing page

> Job CRUD is the spine everything attaches to — get it working with dummy data before touching NCBI.

### Days 3–4 — NCBI BLAST Integration (core engine)
- `integrations/ncbi/blast.py`: `submit_blast()`, `check_status()`, `fetch_results()` against the QBLAST URL API
- Background task (start with `asyncio.create_task` — sufficient for a single-instance prototype): on job create, submit → poll every 15s → on `READY`, fetch XML, push to R2, update `job_steps`
- XML parser → hit list (accession, description, % identity, E-value, bit score, alignment)

**Risk flag:** NCBI `nr` searches can take 1–5 min and occasionally queue longer. Build a **demo-mode fallback** now — pick 1–2 well-characterized sequences (e.g., human insulin), pre-run them, cache the result. This is your insurance for Day 18.

### Day 5 — Sequence Input + Validation
- `integrations/ncbi/efetch.py` — fetch sequence by accession
- Sequence-type detection (nucleotide vs. protein, composition-based)
- `POST /sequences/validate`
- Frontend: wizard shell, step indicator, Step 1 (operation grid), Step 2 (paste/accession tabs + validation feedback)

### Days 6–7 — Wizard → Job Creation → Processing Screen
- Step 3 (confirm/run) → `POST /jobs` → `/jobs/[id]`
- Processing screen: `useJobStatus` polling hook, animated status indicator, friendly per-state copy
- Backend: wire job creation to the Day 3–4 background task, update `job_steps` at each stage

**Checkpoint:** by end of Day 7 you can paste a sequence, hit run, and watch real NCBI status updates. First "it's alive" moment.

### Days 8–9 — Results Rendering (raw, no AI yet)
- Frontend: hits table, score-bar visualization (confidence bands), alignment view for top hit
- Backend: `GET /jobs/{id}/results` — parsed hits + top-hit alignment from stored XML

### Days 10–11 — AI Interpretation Layer
- `services/interpreter.py` — Gemini call
- Prompt template at `/prompts/blast_interpretation.md`: takes parsed hits, returns a 2–3 sentence summary + per-term explanations (E-value, bit score, % identity) *in context of this specific result*. System instruction bakes in the "faithful execution, not 100% accuracy" framing from the PRD.
- New step `interpreting` → result stored in `job_steps.result_json`
- Frontend: AI Summary component, "What does this mean?" expandables wired to the AI response

### Day 12 — Guest → Account Flow
- Banner component (appflow §3.5/3.6)
- Sign-up modal → Supabase `linkIdentity` upgrade
- Post-conversion redirect handling

### Day 13 — Dashboard
- `GET /jobs?user_id=`
- Dashboard page — job cards, empty state, click-through

### Day 14 — Landing Page Polish
- Full design system applied
- Sequence typewriter hero animation
- CTA wiring

### Day 15 — Error States & Edge Cases
- Invalid sequence input messaging
- NCBI timeout/failure → `failed` status + retry
- Zero significant hits → its own AI framing ("no strong matches — here's what that can mean")
- Rate-limit queueing if multiple jobs fire close together

### Day 16 — Deploy
- Frontend → Vercel, Backend → Railway or Render
- Env vars wired per techspec.md
- Full flow test on deployed URLs

### Day 17 — Demo Prep + Buffer
- Finalize 2–3 demo sequences with rich, interesting hits; pre-run and cache them
- Fix whatever broke on Day 16

### Day 18 — Demo Day
- Final run-through with cached demo-mode results as backup
- Buffer only — no new features

---

## Track B — Phase 1 Full Build (post-prototype, ~10–12 weeks)

### Sprint 1–2: Pairwise Alignment + Pipeline Chaining Foundation ✅
- Add Clustal Omega pairwise alignment as the second live operation ✅
- Implement `parent_job_id` chaining (schema already supports this) ✅
- Operation grid: two live cards ✅

### Sprint 3–4: UniProt + PDB ✅
- UniProt annotation lookup ✅
- PDB structure fetch + Mol* 3D viewer ✅ (3Dmol.js viewer)
- Chain: "from this BLAST hit → fetch structure" ✅

### Sprint 5–6: MSA + Phylogenetic Tree ✅
- Clustal Omega multi-sequence alignment ✅ (multi-method: ClustalOmega/MUSCLE/Kalign/MAFFT/T-Coffee)
- Basic tree construction + visualization ✅
- Completes the BLAST → shortlist → MSA → tree workflow from your syllabus mapping ✅

### Sprint 7: Pathway Integration ✅
- Gene/protein → pathway lookup via Reactome/WikiPathways ✅
- Pathway diagram viewer ✅

### Sprint 8: Onboarding + `/learn` ✅
- First-run tutorial (TutorialWalkthrough component, 5 steps, localStorage flag) ✅
- 10+ documentation pages at `/learn` (BLAST, Alignment, Domains, Phylo, Structure, Pathways, Interactions, Primers, Tools, Glossary) ✅
- LearnPopover component for inline `(?)` help tooltips ✅

### Sprint 9–10: Hardening ✅
- PDF report export (`GET /api/export/job/{id}?format=pdf|json`) ✅
- Cache-hit check with `from_cache` flag, `/api/admin/cache-stats` endpoint ✅
- `@ttl_cache` coverage: pathway enrichment, NCBI search, BLAST, UniProt, AlphaFold ✅
- Sentry error monitoring (`@sentry/nextjs` frontend + `sentry-sdk` backend) ✅

### Sprint 11: Pipeline v2 Engine + Domain/Structure Depth ✅
- 8-step in-memory pipeline: BLAST → UniProt → MSA → Phylo → Domains → Pathway Enrichment → AlphaFold → AI ✅
- Pipeline wizard with step checkboxes, progressive reveal results ✅
- Global/local BLAST modes, DNA query support, poll cap 65 min ✅
- Pairwise: global/local via "Align pair" from BLAST hits + standalone tool + full-length view ✅
- Domains: PROSITE raw-sequence scan, reviewed/organism UniProt filters ✅
- Structure analysis suite: Ramachandran, secondary structure, Foldseek comparison ✅

### Sprint 12: Drug Discovery Compute ✅
- AutoDock Vina docking: full 1.2.7 log (RMSD l.b./u.b., version, seed), RMSD table, run-config UI ✅
- MD simulation: verified force field × solvent matrix, startup probe, 25-min budget ✅
- ADMET: RDKit descriptor computation + traffic-light output ✅
- Function prediction + protein interactions ✅

### Sprint 13: Sequencing MVP ✅
- FASTQ upload → QC → trimming → assembly/consensus → variant calling → annotation ✅
- SARS-CoV-2 reference, job persistence, progress polling ✅

### Sprint 14: Reliability ✅
- AI model fallback chain (Groq → Gemini → Ollama), honest failure banner ✅
- Share links fixed for all job types + enriched share message ✅
- Wizard jobs persisted to dashboard history ✅
- BLAST params honored (program/db/max_hits), long MD jobs not abandoned ✅

### Sprint 15: Design System (v4.0) ✅
- Dark-only OLED theme, semantic color tokens, AA text tiers, 4-band confidence bands ✅
- Geist fonts, Phosphor icons, HUD glass components, tiered motion ✅
- Landing rebuild: DNA-helix hero, bento features, route-style pipeline ✅
- Dashboard/tools/results converted to native dark tokens ✅