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)

• Create bioflow-frontend and bioflow-backend repos
• Create Supabase project, run schema.md migrations
• Create Cloudflare R2 bucket
• Get API keys: Gemini (Resend optional for prototype)
• 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 ✅