implementationplan.md

implementationplan.md — BioFlow AI Implementation Plan

Track A — Prototype Sprint (18 Days)

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
• Chain: "from this BLAST hit → fetch structure"

Sprint 5–6: MSA + Phylogenetic Tree

• Clustal Omega multi-sequence alignment
• 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) ✅