# appflow.md — BioFlow AI Application Flow

## 1. Two Tracks ✅ Both shipped
- **Prototype Track (Days 1–18):** one golden path — Sequence In → BLAST → AI-interpreted report. ✅
- **Full Build Track:** additional operations, pipeline chaining, learning section, projects. ✅

## 2. Sitemap (Current)
/                    Landing (DNA-helix hero, bento features, pipeline route)

/analyze             Tool catalog — operation cards (all active)

/analyze/[tool]      Individual tools: blast, alignment, pairwise, compare, docking, domains,
                     function, interactions, md, pathway, phylo, primers, sequencing,
                     structure, uniprot, admet

/wizard              Pipeline wizard (8-step: BLAST → UniProt → MSA → Phylo → Domains →
                     Pathway → AlphaFold → AI)

/jobs                Job history (guest + authed)

/jobs/[jobId]        Processing → Results (shareable, persistent)

/results/[jobId]     Unified results page

/report/[jobId]      PDF/JSON report export

/learn               Documentation (10+ topic pages + glossary)

/settings            Profile, guest→account upgrade, API key management, tutorial replay

/auth/*              Sign-up / sign-in (triggered from guest banner)

## 3. Screen-by-Screen

### 3.1 Landing (`/`)
- Hero with a live "typewriter" sequence animation (see design.md §6).
- Single CTA: **Analyze a Sequence** → `/analyze`. No login wall.

### 3.2 Wizard Step 1 — Choose Operation (`/analyze`)
- Grid of operation cards. **All cards active**: BLAST, Pairwise, MSA, Phylo, Domains, Pathway, Structure, Docking, MD, ADMET, Function, Interactions, Primers, Sequencing, UniProt.
- State: `selectedOperation: 'blast' | 'pairwise' | ... | null`

### 3.3 Wizard Step 2 — Provide Input (`/analyze/blast`)
- Two tabs:
  - **Paste Sequence** — textarea, client-side FASTA validation, auto-detects nucleotide vs. protein (composition heuristic).
  - **Fetch by Accession** — text input → backend calls NCBI `efetch` → returns sequence + metadata for the user to confirm before proceeding.
- Database/program auto-suggested from detected type (`blastp`/`nr` for protein, `blastn`/`nt` for nucleotide), with an **Advanced** disclosure for manual override.
- State: `inputMode`, `rawInput`, `detectedType`, `advancedParams`

### 3.4 Wizard Step 3 — Confirm & Run
- Plain-English summary card: *"We'll run a blastp search of your 142-aa protein against the nr database."*
- **Run Analysis** → `POST /jobs` (status: `queued`) → redirect to `/jobs/[id]`.

### 3.5 Job Page — Processing State (`/jobs/[id]`)
- Polls `GET /jobs/{id}` every 3s.
- Step states: `queued` → `submitted_to_ncbi` → `polling_ncbi` → `parsing` → `interpreting` → `complete` | `failed`.
- Each state has friendly copy + expectation-setting: *"Usually 30s–3min depending on NCBI load."*
- **This page is the persistence guarantee**: closing the tab and returning to the same URL later shows the saved result — no "session expired" dead end.
- Guest banner: *"This result is saved for 24 hours. Create a free account to keep it forever."*

### 3.6 Job Page — Results State
1. **AI Summary** (always visible, top) — 2–3 sentence plain-English overview.
2. **Top Hits Table** — accession, description, % identity, E-value, bit score; rows expandable.
3. **Visual Score Bar** — top 10 hits, color-coded by confidence band (design.md §2.4).
4. **Alignment View** — monospace, matched regions highlighted, for the top hit.
5. **"What does this mean?" expandables** next to E-value / bit score / % identity — contextual instruction, not a separate manual.
6. **Export** — "Copy as report" now; PDF export in Phase 1.

### 3.7 Guest → Account Conversion
- Triggered from the banner (3.5/3.6) or "Save to Dashboard."
- Implementation: Supabase anonymous auth (already active from first visit) → upgrade via `linkIdentity` when the user adds email/password. Same `user_id`, zero data migration.
- Post-conversion: redirect back to the same `/jobs/[id]`, banner disappears permanently.

### 3.8 Dashboard (`/dashboard`)
- Job cards: operation type, input snippet, status, date → click through to `/jobs/[id]`.
- Empty state: *"Run your first analysis"* → `/analyze`.

## 4. Job Lifecycle (drives 3.5 + 3.8)

| Step status         | User-facing label                          | Typical duration |
|----------------------|---------------------------------------------|-------------------|
| `queued`             | "Queued"                                     | < 1s |
| `submitted_to_ncbi`  | "Submitted to NCBI BLAST"                    | instant |
| `polling_ncbi`       | "NCBI is searching — this can take a minute" | 30s–5min |
| `parsing`            | "Reading results"                            | < 5s |
| `interpreting`       | "Writing your explanation"                   | 5–15s |
| `complete`           | results render                               | — |
| `failed`             | error state + retry button                   | — |

## 5. Full Build Additions (originally "not in prototype") — ✅ All shipped
- Operation catalog expands: UniProt annotation, PDB structure + Mol* 3D viewer, pairwise alignment, Clustal Omega MSA, Reactome/WikiPathways lookup ✅ — plus docking, MD, ADMET, function, interactions, primers, sequencing
- **Pipeline chaining**: Wizard builds a step sequence (BLAST → UniProt → MSA → Phylo → Domains → Pathway → AlphaFold → AI), each step a `job_steps` row linked via `parent_job_id` ✅ (pipeline v2 engine)
- `/learn` documentation section (generated from the same explanation content used in §3.6.5 — write once, reuse) ✅
- Onboarding tutorial (first-run modal series) ✅
- "Projects" — group related jobs 🔜 (jobs/dashboard shipped; grouping not yet)
- `/settings` ✅ (profile, guest→account, API keys, tutorial replay)