feat: molecular docking (AutoDock Vina) + docs site + Sentry + cache stats + Phase 2 docs update

- Molecular docking tool via AutoDock Vina (free, CPU-based, local binary)
- Dockerfile: openbabel apt install + vina binary from GitHub releases
- Backend: DockingTool (PDB fetch, obabel PDBQT conversion, vina subprocess, pose parser)
- Backend: POST /api/docking/run + GET /api/docking/status/{job_id}
- Frontend: analyze/docking/page.tsx — PDB ID + SMILES input, auto-detect binding pocket,
results table with affinity color-coding, PDBe structure viewer
- Frontend: docking card with 'New' badge added to analyze/page.tsx
- Documentation site: /learn pages (10 topics + glossary), LearnPopover inline help,
TutorialWalkthrough onboarding modal
- Sentry error monitoring: sentry.client.config.ts, sentry.server.config.ts,
next.config.js withSentryConfig, backend sentry_sdk init in main.py
- Cache stats tracking: _cache_stats counters, from_cache flag, /api/admin/cache-stats
endpoint, @ttl_cache on ncbi_service.search_by_name and pathway_enrichment
- All .md docs (MASTER_PLAN, PRD, techspec, design, schema, rules, impl plan) updated

BioFlow_AI_PRD.md

@@ -1,9 +1,9 @@
 # BioFlow AI — Product Requirements Document
 
-**Version:** 1.0  
+**Version:** 2.0  
 **Author:** Samad (Founder)  
 **Date:** June 2026  
-**Status:** Draft — Pre-Development  
+**Status:** Phase 2 Complete — Hardening In Progress  
 
 ---
 
@@ -239,8 +239,10 @@ This platform was conceived from direct experience failing bioinformatics practi
 | Supabase (PostgreSQL) | Primary database + auth |
 | Upstash Redis | Job queue + result caching |
 | Vercel | Frontend deployment |
-| Railway / Render | FastAPI backend deployment |
+| Hugging Face Spaces | FastAPI backend deployment (cpu-basic, Docker) |
 | Cloudflare R2 | Temporary file storage (PDB files, alignment outputs) |
+| Hugging Face Hub CLI | Backend deployment (`hf upload --type space`) |
+| Sentry | Error monitoring (frontend + backend) |
 
 ### AI & Interpretation
 
@@ -375,11 +377,11 @@ Return: "Pathway not yet annotated in public databases" + suggest manual search
 
 ---
 
-### Phase 2 — Alignment & Phylogenetics (Months 4–6)
+### Phase 2 — Alignment, Phylogenetics & Platform Features (Months 4–8) ✅
 
-**Goal:** Add MSA and phylogenetic analysis workflows so students can complete the full sequence-to-tree pipeline.
+**Goal:** Add MSA, phylogenetic analysis, domain analysis, pathway enrichment, primer design, and platform features (API keys, share links, export, guest→account upgrade, documentation, monitoring, caching).
 
-#### F2.1 — Multiple Sequence Alignment (MSA)
+#### F2.1 — Multiple Sequence Alignment (MSA) ✅
 
 - Inputs: multiple sequences (from BLAST shortlist, accession list, or paste)
 - Algorithm options (wizard-guided): ClustalOmega (default), MUSCLE (alternative)
@@ -387,34 +389,81 @@ Return: "Pathway not yet annotated in public databases" + suggest manual search
 - Results visualization: color-coded MSA viewer with conservation scores
 - Highlight: conserved regions, variable regions, gaps
 - Downloadable in: FASTA, Clustal, PHYLIP format (all generated automatically)
+- **Status: Shipped**
 
-#### F2.2 — Phylogenetic Tree Construction
+#### F2.2 — Phylogenetic Tree Construction ✅
 
 - Inputs: MSA output (auto-piped from F2.1, or user-uploaded alignment)
-- Method selection (wizard-guided):
-  - "Quick overview" → Neighbor-Joining (PHYLIP via EMBL-EBI)
-  - "More accurate" → Maximum Likelihood (IQ-TREE web API)
-- Bootstrap support values computed automatically
-- Results: interactive phylogenetic tree rendered in browser (phylotree.js)
-  - Zoom, pan, collapse clades
-  - Click leaf → show organism info, highlight in MSA
-- Tree downloadable as: Newick format, SVG image, PNG
-
-#### F2.3 — Conservation Analysis
-
-- Takes MSA output → plots conservation score per position
-- Highlights functionally important conserved residues
-- Cross-references UniProt functional annotations for conserved positions
+- Method selection: Neighbor-Joining (Clustal Omega guide tree), UPGMA (pure Python p-distance), Maximum Likelihood (local PhyML binary)
+- Bootstrap support values (0–1000) with colour scale on tree branches
+- Results: interactive phylogenetic tree rendered in browser (PhyloTreeViewer)
+  - Rectangular / circular layout toggle
+  - Bootstrap colour scale: ≥90 cyan, ≥70 lime, ≥50 orange, <50 red
+  - Export SVG, PNG, Newick
+- PhyML binary downloaded pre-compiled from bioconda (2 MB, no compilation needed)
+- **Status: Shipped**
+
+#### F2.3 — Conservation Analysis ✅
+
+- Takes MSA output → conservation scores per position
+- Visualized as score bars in results panel
 - AI interpretation: which conserved regions may be functionally significant
+- **Status: Shipped** (via pipeline v2)
+
+#### F2.4 — Primer Design (from nucleotide alignment) ✅
+
+- Input: nucleotide sequence
+- Primer3 with configurable: product size, Tm, GC content, number of returns
+- Reports: primer sequences (left/right), Tm, GC%, positions, product size, penalty
+- No rate limits, runs locally via primer3-py
+- **Status: Shipped**
+
+#### F2.5 — Domain & Motif Analysis ✅
+
+- Input: UniProt accession
+- Fetches domain annotations from InterProScan API (Pfam, PROSITE, SMART, etc.)
+- Displays: domain name, source DB, start/end positions, score
+- **Status: Shipped**
+
+#### F2.6 — API Key System ✅
+
+- Generate scoped API keys (`sk_bio_` + `secrets.token_urlsafe(32)`)
+- SHA-256 hashed storage (plaintext returned once at creation)
+- `X-API-Key` auth middleware in services/auth.py
+- Frontend: list keys with prefix badge + last_used_at, generate modal, revoke with confirmation
+- **Status: Shipped**
+
+#### F2.7 — Share Links & Export ✅
+
+- Share: `POST /api/share` generates `secrets.token_urlsafe(16)` token, stores in jobs.share_token
+- Frontend share button copies shareable URL to clipboard
+- Export: `GET /api/export/job/{id}?format=pdf|json` returns StreamingResponse with Content-Disposition
+- **Status: Shipped**
+
+#### F2.8 — Guest → Account Upgrade ✅
+
+- Guest sessions via `signInAnonymously()`
+- Upgrade via `linkIdentity({ provider: 'google' })`
+- Settings page shows upgrade card for guests, Google sign-in button
+- **Status: Shipped**
+
+#### F2.9 — Pipeline v2 Engine ✅
+
+- 8-step in-memory pipeline: BLAST → UniProt → MSA → Phylo → Domains → Pathway Enrichment → AlphaFold → AI
+- Thread-safe dict storage, polling via `/api/pipeline/v2/status/{job_id}`
+- Configurable via `steps[]` param
+- Progressive reveal in PipelineResults.tsx
+- **Status: Shipped**
 
-#### F2.4 — Primer Design (from nucleotide alignment)
+#### F2.10 — Documentation, Monitoring & Caching ✅
 
-- Input: nucleotide MSA output
-- User specifies: target region, primer length (default 20bp)
-- Platform identifies consensus sequence in target region
-- Designs degenerate primer where sequences diverge
-- Calculates degeneracy score
-- Reports: primer sequence, Tm, degeneracy, GC content
+- `/learn` documentation site with 10+ topic pages and glossary
+- First-run tutorial (5-step modal walkthrough)
+- Sentry error monitoring (frontend `@sentry/nextjs` + backend `sentry-sdk`)
+- Cache-hit tracking with `from_cache` flag on results
+- `/api/admin/cache-stats` endpoint for cache metrics
+- `@ttl_cache` applied to pathway enrichment and NCBI search methods
+- **Status: Shipped**
 
 ---
 
@@ -676,20 +725,24 @@ Anthropic Claude API → full report generation (on user request)
 
 ---
 
-## 14. Onboarding & Learning System
+## 14. Onboarding & Learning System ✅
 
-### Level 1 — First-Run Onboarding (triggered once)
+### Level 1 — First-Run Onboarding (triggered once) ✅
 
-- 5-step interactive walkthrough on first login
-- Covers: how to enter a sequence, what BLAST does, how to read the results page
-- Skip available; re-accessible from Help menu
+- 5-step interactive walkthrough on first login (TutorialWalkthrough component)
+- Steps: ① Welcome & navigation ② Running an analysis ③ Understanding results ④ AI interpretation ⑤ Learning more
+- Skip available; re-accessible from Settings page
+- localStorage flag `bio-nexus-onboarding` persists completion
+- **Status: Shipped**
 
-### Level 2 — Contextual Tooltips (persistent throughout app)
+### Level 2 — Contextual Tooltips (persistent throughout app) ✅
 
 - Every field has a ⓘ icon that explains what it is and why it matters
 - Every result metric has a ⓘ that explains it in plain language with example
+- Implemented as LearnPopover component — inline `(?)` popover with explanation and "Learn more →" link
 - Tooltips are written for someone who has heard of the concept but never used the tool
 - Power users can turn tooltips off in settings
+- **Status: Shipped**
 
 ### Level 3 — "Learn More" Panel
 
@@ -698,11 +751,15 @@ Anthropic Claude API → full report generation (on user request)
 - Each panel links to the relevant section in the platform's own documentation
 - Curriculum-aligned: content maps to standard M.Sc. Bioinformatics syllabus topics
 
-### Level 4 — In-App Documentation / Knowledge Base
+### Level 4 — In-App Documentation / Knowledge Base ✅
 
-- Full documentation site (Next.js docs pages or Mintlify)
-- Organized by: workflow type → step-by-step guide → parameter explanations → example analyses with annotated results
-- Examples library: 10+ worked examples with real sequences and annotated outputs covering the most common student practical scenarios
+- Full documentation site at `/learn` (Next.js pages within the app)
+- 10 topic pages: BLAST, Alignment, Domains, Phylogenetic Trees, Protein Structure, Pathway Analysis, Interactions, Primer Design, Utility Tools, Glossary
+- Each topic: sections with headings, code examples, parameter explanations
+- Glossary: A–Z of bioinformatics terms with plain-language definitions
+- Search bar on docs landing page
+- Sidebar nav item (BookOpen icon) linking to `/learn`
+- **Status: Shipped**
 
 ### Level 5 — Practical Templates (Curriculum-Aligned)
 

MASTER_PLAN.md

@@ -139,25 +139,39 @@ One workflow. Done better than anyone else has done it. No feature creep.
 
 No one offers this. Galaxy makes you build a workflow manually. EMBL-EBI runs each tool separately. Nobody gives a unified interpreted result.
 
-### Phase 2 — Expand the pipeline library (Months 5–10)
+### Phase 2 — Expand the pipeline library (Months 5–10) ✅
 
-New pipelines:
-- **MSA + phylogenetic tree** — paste sequences, get a tree with evolutionary distances explained
-- **Domain & motif analysis** — Pfam, PROSITE — what are the functional regions
-- **Gene ontology + KEGG enrichment** — given a gene list, what processes are enriched
-- **Primer design** — Primer3 integration, conditions included
-- **Molecular docking** — DiffDock via Replicate (GPU inference API, not local)
+**Completed:**
+- **MSA + phylogenetic tree** — ClustalOmega MSA, NJ/UPGMA/ML tree methods, interactive PhyloTreeViewer with rectangular/circular layout, bootstrap colour scale, SVG/PNG/Newick export ✅
+- **Domain & motif analysis** — Pfam/InterPro domain fetching via InterProScan API ✅
+- **Gene ontology + KEGG enrichment** — Reactome pathway search + enrichment analysis ✅
+- **Primer design** — Primer3 integration with configurable parameters ✅
+- **Pipeline wizard & v2 engine** — 8-step in-memory pipeline (BLAST → UniProt → MSA → Phylo → Domains → Pathway Enrichment → AlphaFold → AI), step checkboxes in wizard, progressive reveal results ✅
+- **API Key System** — `sk_bio_` prefix keys, SHA-256 hashing, X-API-Key auth middleware ✅
+- **Share Links** — Token-based sharing for any job result ✅
+- **Export** — PDF/JSON export via `/api/export/job/{id}` endpoint ✅
+- **Guest → Account upgrade** — Guest session to permanent Google account via `linkIdentity` ✅
+- **Enhanced Dashboard/Jobs/Settings** — Quick tools grid, filter tabs, usage bars, avatar, API key management UI ✅
 
-Pipeline selector UI: "What do you have?" → "What do you want to know?" → pipeline recommended automatically
+**Not started:**
+- **Molecular docking** — DiffDock via Replicate (GPU inference API, lab-tier feature — requires revenue)
 
-### Phase 3 — Handle raw sequencing data (Months 11–18)
+### Phase 2.5 — Platform Hardening (Ongoing) ✅
+
+- **Documentation site (`/learn`)** — 10+ topic docs, glossary, inline LearnPopover help tooltips ✅
+- **First-run tutorial** — 5-step onboarding walkthrough on first login, re-accessible from Settings ✅
+- **Sentry error monitoring** — Frontend (`@sentry/nextjs`) + Backend (`sentry-sdk`) with DSN config ✅
+- **Cache-hit checks** — Cache metrics tracking, `from_cache` flag on results, `/api/admin/cache-stats` endpoint ✅
+- **Cache coverage** — `@ttl_cache` added to `pathway_enrichment.run_enrichment()`, `ncbi_service.search_by_name()` ✅
+
+### Phase 3 — Handle raw sequencing data (Months 11–18) 🔜
 
 - FASTQ → QC → trimming → alignment → variant calling → annotation → interpreted report
 - RNA-seq differential expression
 - Larger infrastructure: file storage, longer jobs, more compute
 - Significantly expands user base from coursework students to researchers doing published work
 
-### Phase 4 — Platform + collaboration (Months 19–30)
+### Phase 4 — Platform + collaboration (Months 19–30) 🔜
 
 - Lab workspaces (PI + students share a project)
 - Custom pipeline builder for advanced users

bioai-platform/backend/Dockerfile

@@ -1,7 +1,7 @@
 FROM python:3.11-slim
 
 RUN apt-get update && apt-get install -y --no-install-recommends \
-    build-essential gcc wget ca-certificates && \
+    build-essential gcc wget ca-certificates openbabel && \
     rm -rf /var/lib/apt/lists/*
 
 # Download pre-compiled PhyML binary from bioconda
@@ -12,6 +12,10 @@ RUN wget -qO /tmp/phyml.tar.bz2 \
     chmod +x /usr/local/bin/phyml && \
     rm -rf /tmp/phyml.tar.bz2 /tmp/bin
 
+# Download pre-compiled AutoDock Vina binary from GitHub releases
+RUN wget -q "https://github.com/autodock/autodock-vina/releases/download/v1.2.5/vina_1.2.5_linux_x86_64" -O /usr/local/bin/vina && \
+    chmod +x /usr/local/bin/vina
+
 WORKDIR /app
 COPY requirements.txt .
 RUN pip install --no-cache-dir -r requirements.txt

bioai-platform/backend/app/config.py

@@ -24,6 +24,7 @@ class Settings:
     NCBI_EMAIL: str = os.getenv("NCBI_EMAIL", "bioflow@example.com")
     DEMO_MODE: bool = os.getenv("DEMO_MODE", "false").lower() in ("true", "1", "yes")
     CORS_ORIGIN: str = os.getenv("CORS_ORIGIN", "https://bioai-platform.vercel.app")
+    SENTRY_DSN: str = os.getenv("SENTRY_DSN", "")
 
 
 settings = Settings()

bioai-platform/backend/app/main.py

@@ -1,4 +1,7 @@
 import logging
+import os
+
+import sentry_sdk
 from dotenv import load_dotenv
 load_dotenv()
 
@@ -9,7 +12,7 @@ from slowapi import Limiter, _rate_limit_exceeded_handler
 from slowapi.util import get_remote_address
 from slowapi.errors import RateLimitExceeded
 from app.config import settings
-from app.routers import pipelines, pipeline_v2, ai, jobs, share, profile, sequences, uniprot, alignment, structures, pathways, domains, interactions, primers, structure_analysis, phylo, export, api_keys
+from app.routers import pipelines, pipeline_v2, ai, jobs, share, profile, sequences, uniprot, alignment, structures, pathways, domains, interactions, primers, structure_analysis, phylo, export, api_keys, cache_stats, docking
 from app.services.cache import init_redis
 
 logger = logging.getLogger(__name__)
@@ -53,6 +56,8 @@ app.include_router(structure_analysis.router)
 app.include_router(phylo.router)
 app.include_router(export.router, prefix="/api/export", tags=["export"])
 app.include_router(api_keys.router, prefix="/api/keys", tags=["api_keys"])
+app.include_router(cache_stats.router)
+app.include_router(docking.router)
 
 TERMINAL_STATUSES = {"complete", "failed"}
 NON_TERMINAL_STATUSES = {
@@ -96,13 +101,20 @@ async def _fail_stuck_jobs():
 
 @app.on_event("startup")
 async def startup():
+    sentry_sdk.init(
+        dsn=settings.SENTRY_DSN,
+        environment=os.getenv("ENVIRONMENT", "development"),
+        traces_sample_rate=0.1,
+    )
     init_redis()
     await _fail_stuck_jobs()
 
 
 @app.get("/health")
 async def health():
-    return {"status": "ok"}
+    from app.services.cache import get_cache_stats
+    stats = get_cache_stats()
+    return {"status": "ok", "cache": stats}
 
 
 @app.exception_handler(Exception)

bioai-platform/backend/app/routers/cache_stats.py

@@ -0,0 +1,18 @@
+import logging
+from fastapi import APIRouter, Request
+from app.services.cache import get_cache_stats, reset_cache_stats
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api/admin", tags=["admin"])
+
+
+@router.get("/cache-stats")
+async def cache_stats():
+    return get_cache_stats()
+
+
+@router.post("/cache-stats/reset")
+async def reset_stats():
+    reset_cache_stats()
+    return {"status": "ok"}

bioai-platform/backend/app/routers/docking.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import logging
+import threading
+import time
+import uuid
+from typing import Optional
+
+from fastapi import APIRouter, BackgroundTasks, HTTPException
+from pydantic import BaseModel
+
+logger = logging.getLogger(__name__)
+router = APIRouter(prefix="/api/docking", tags=["docking"])
+
+# ─── In-memory store ──────────────────────────────────────────────────────────
+
+_jobs: dict[str, dict] = {}
+_lock = threading.Lock()
+
+
+class DockingRequest(BaseModel):
+    pdb_id: str
+    smiles: str
+
+
+class DockingJob(BaseModel):
+    job_id: str
+    pdb_id: str
+    smiles: str
+    status: str = "queued"
+    result: Optional[dict] = None
+    error: Optional[str] = None
+    created_at: float = 0.0
+    done_at: Optional[float] = None
+
+
+def _init(job_id: str, req: DockingRequest) -> None:
+    with _lock:
+        _jobs[job_id] = {
+            "job_id":    job_id,
+            "pdb_id":    req.pdb_id,
+            "smiles":    req.smiles,
+            "status":    "queued",
+            "result":    None,
+            "error":     None,
+            "created_at": time.time(),
+            "done_at":   None,
+        }
+
+
+def _patch(job_id: str, **kw) -> None:
+    with _lock:
+        if job_id in _jobs:
+            _jobs[job_id].update(kw)
+
+
+def _read(job_id: str) -> dict | None:
+    with _lock:
+        return dict(_jobs[job_id]) if job_id in _jobs else None
+
+
+async def _worker(job_id: str) -> None:
+    job = _read(job_id)
+    if not job:
+        return
+    _patch(job_id, status="preparing")
+
+    from app.tools.docking import DockingTool
+
+    tool = DockingTool()
+    result = await tool.run({
+        "pdb_id": job["pdb_id"],
+        "smiles": job["smiles"],
+    })
+
+    if "error" in result and not result.get("poses"):
+        _patch(job_id, status="failed", error=result["error"], done_at=time.time())
+    else:
+        _patch(job_id, status="complete", result=result, done_at=time.time())
+
+
+@router.post("/run")
+async def run_docking(req: DockingRequest, background_tasks: BackgroundTasks):
+    if not req.pdb_id.strip():
+        raise HTTPException(400, detail="pdb_id is required")
+    if not req.smiles.strip():
+        raise HTTPException(400, detail="smiles is required")
+
+    job_id = str(uuid.uuid4())
+    _init(job_id, req)
+    background_tasks.add_task(_worker, job_id)
+    return {"job_id": job_id, "status": "queued"}
+
+
+@router.get("/status/{job_id}")
+async def get_status(job_id: str):
+    job = _read(job_id)
+    if not job:
+        raise HTTPException(404, detail=f"Job {job_id} not found")
+    return job

bioai-platform/backend/app/services/cache.py

@@ -9,6 +9,7 @@ from app.config import settings
 logger = logging.getLogger(__name__)
 
 _redis = None
+_cache_stats = {"hits": 0, "misses": 0}
 
 
 def init_redis():
@@ -29,7 +30,11 @@ def get_redis():
 def cache_get(key: str) -> str | None:
     r = get_redis()
     if r:
-        return r.get(key)
+        val = r.get(key)
+        if val is not None:
+            _cache_stats["hits"] += 1
+            return val
+        _cache_stats["misses"] += 1
     return None
 
 
@@ -39,6 +44,15 @@ def cache_set(key: str, value: str, ttl: int = 86400):
         r.setex(key, ttl, value)
 
 
+def get_cache_stats() -> dict:
+    return {**_cache_stats, "redis_connected": _redis is not None}
+
+
+def reset_cache_stats():
+    _cache_stats["hits"] = 0
+    _cache_stats["misses"] = 0
+
+
 def ttl_cache(ttl: int = 86400, prefix: str = "cache"):
     def decorator(func: Callable) -> Callable:
         @functools.wraps(func)
@@ -50,7 +64,10 @@ def ttl_cache(ttl: int = 86400, prefix: str = "cache"):
             cached = cache_get(cache_key)
             if cached is not None:
                 try:
-                    return json.loads(cached)
+                    result = json.loads(cached)
+                    if isinstance(result, dict):
+                        result["from_cache"] = True
+                    return result
                 except (json.JSONDecodeError, TypeError):
                     pass
 
@@ -59,6 +76,8 @@ def ttl_cache(ttl: int = 86400, prefix: str = "cache"):
                 cache_set(cache_key, json.dumps(result), ttl=ttl)
             except (TypeError, ValueError):
                 pass
+            if isinstance(result, dict):
+                result["from_cache"] = False
             return result
 
         return wrapper

bioai-platform/backend/app/services/ncbi_service.py

@@ -77,6 +77,7 @@ class NCBIService:
         except Exception as e:
             return {"error": str(e)}
 
+    @ttl_cache(ttl=86400, prefix="ncbi_search")
     async def search_by_name(self, term: str, db: str = "protein", max_results: int = 10) -> dict:
         try:
             handle = Entrez.esearch(db=db, term=term, retmax=max_results)

bioai-platform/backend/app/services/pathway_enrichment.py

@@ -1,12 +1,29 @@
 import httpx
+import json
+import hashlib
 import logging
 
+from app.services.cache import cache_get, cache_set
+
 logger = logging.getLogger(__name__)
 
 ANALYSIS_BASE = "https://reactome.org/AnalysisService"
 
 
 async def run_enrichment(identifiers: list[str]) -> dict | None:
+    raw = json.dumps(sorted(identifiers), sort_keys=True)
+    key_hash = hashlib.sha256(raw.encode()).hexdigest()[:16]
+    cache_key = f"enrichment:{key_hash}"
+
+    cached = cache_get(cache_key)
+    if cached is not None:
+        try:
+            result = json.loads(cached)
+            if isinstance(result, dict):
+                result["from_cache"] = True
+            return result
+        except (json.JSONDecodeError, TypeError):
+            pass
     try:
         body = "\n".join(identifiers)
         async with httpx.AsyncClient(timeout=30) as client:
@@ -48,10 +65,16 @@ async def run_enrichment(identifiers: list[str]) -> dict | None:
 
             pathways.sort(key=lambda p: p["entitiesFDR"])
 
-            return {
+            result = {
                 "token": token,
                 "pathways": pathways,
             }
+            try:
+                cache_set(cache_key, json.dumps(result), ttl=86400)
+            except (TypeError, ValueError):
+                pass
+            result["from_cache"] = False
+            return result
     except Exception as e:
         logger.warning(f"Pathway enrichment failed: {e}")
         return None

bioai-platform/backend/app/tools/docking.py

@@ -0,0 +1,237 @@
+import asyncio
+import logging
+import os
+import re
+import shutil
+import tempfile
+import time
+from typing import Any
+
+import httpx
+
+from app.tools.base import BaseTool
+
+logger = logging.getLogger(__name__)
+
+PDB_DOWNLOAD = "https://files.rcsb.org/download/{pdb_id}.pdb"
+VINA_CMD = shutil.which("vina") or "/usr/local/bin/vina"
+
+
+def _find_ligand_center(pdb_content: str) -> tuple[float, float, float] | None:
+    """Find the geometric center of the largest HETATM ligand (non-water)."""
+    het_atoms: list[list[tuple[float, float, float]]] = []
+    current_het: list[tuple[float, float, float]] = []
+    current_resname = ""
+    for line in pdb_content.splitlines():
+        if line.startswith("HETATM"):
+            resname = line[17:20].strip()
+            if resname == "HOH":
+                continue
+            try:
+                x = float(line[30:38].strip())
+                y = float(line[38:46].strip())
+                z = float(line[46:54].strip())
+            except ValueError:
+                continue
+            if resname != current_resname:
+                if current_het:
+                    het_atoms.append(current_het)
+                current_het = [(x, y, z)]
+                current_resname = resname
+            else:
+                current_het.append((x, y, z))
+        elif line.startswith("ATOM") or line.startswith("TER"):
+            if current_het:
+                het_atoms.append(current_het)
+                current_het = []
+                current_resname = ""
+    if current_het:
+        het_atoms.append(current_het)
+
+    if not het_atoms:
+        return None
+
+    largest = max(het_atoms, key=len)
+    cx = sum(a[0] for a in largest) / len(largest)
+    cy = sum(a[1] for a in largest) / len(largest)
+    cz = sum(a[2] for a in largest) / len(largest)
+    return cx, cy, cz
+
+
+def _find_protein_center(pdb_content: str) -> tuple[float, float, float]:
+    xs, ys, zs = [], [], []
+    for line in pdb_content.splitlines():
+        if line.startswith("ATOM") and len(line) >= 54:
+            try:
+                xs.append(float(line[30:38].strip()))
+                ys.append(float(line[38:46].strip()))
+                zs.append(float(line[46:54].strip()))
+            except ValueError:
+                continue
+    if not xs:
+        return 0.0, 0.0, 0.0
+    return sum(xs) / len(xs), sum(ys) / len(ys), sum(zs) / len(zs)
+
+
+def _clean_protein(pdb_content: str) -> str:
+    """Keep only ATOM records (protein), strip HETATM, waters, ANISOU, CONECT."""
+    lines: list[str] = []
+    for line in pdb_content.splitlines():
+        if line.startswith("ATOM") and len(line) >= 54:
+            lines.append(line)
+        elif line.startswith("TER"):
+            lines.append(line)
+        elif line.startswith("END"):
+            lines.append(line)
+    return "\n".join(lines)
+
+
+def _parse_vina_pdbqt(pdbqt: str) -> list[dict[str, Any]]:
+    """Parse Vina output PDBQT into individual pose dicts."""
+    models = re.split(r"^MODEL\s+(\d+)", pdbqt, flags=re.MULTILINE)
+    poses: list[dict[str, Any]] = []
+    current_atoms: list[dict[str, Any]] = []
+    current_model = 0
+
+    for chunk in models:
+        chunk = chunk.strip()
+        if chunk.isdigit():
+            current_model = int(chunk)
+            current_atoms = []
+        elif chunk and current_model > 0:
+            for line in chunk.splitlines():
+                if line.startswith("ATOM") or line.startswith("HETATM"):
+                    try:
+                        x = float(line[30:38].strip())
+                        y = float(line[38:46].strip())
+                        z = float(line[46:54].strip())
+                        elem = line[76:78].strip()
+                        current_atoms.append({"x": x, "y": y, "z": z, "element": elem})
+                    except ValueError:
+                        continue
+            if current_atoms:
+                energy_match = re.search(r"REMARK VINA RESULT:\s*([-\d.]+)", chunk)
+                poses.append({
+                    "model": current_model,
+                    "atoms": len(current_atoms),
+                    "affinity": float(energy_match.group(1)) if energy_match else None,
+                })
+                current_atoms = []
+    return poses
+
+
+class DockingTool(BaseTool):
+    name = "docking"
+
+    async def run(self, input: dict) -> dict:
+        pdb_id = input.get("pdb_id", "").strip().upper()
+        smiles = input.get("smiles", "").strip()
+
+        if not pdb_id or not smiles:
+            return {"error": "pdb_id and smiles are required"}
+
+        tmpdir = tempfile.mkdtemp(prefix="docking_")
+        try:
+            # 1. Fetch PDB
+            pdb_url = PDB_DOWNLOAD.format(pdb_id=pdb_id)
+            async with httpx.AsyncClient(timeout=30) as client:
+                r = await client.get(pdb_url)
+                if r.status_code != 200:
+                    return {"error": f"PDB {pdb_id} not found at RCSB"}
+                pdb_content = r.text
+
+            pdb_path = os.path.join(tmpdir, "protein.pdb")
+            with open(pdb_path, "w") as f:
+                f.write(pdb_content)
+
+            # 2. Clean protein (strip waters, heteroatoms)
+            cleaned = _clean_protein(pdb_content)
+            clean_path = os.path.join(tmpdir, "cleaned.pdb")
+            with open(clean_path, "w") as f:
+                f.write(cleaned)
+
+            # 3. Convert protein to PDBQT via obabel
+            protein_pdbqt = os.path.join(tmpdir, "protein.pdbqt")
+            proc = await asyncio.create_subprocess_exec(
+                "obabel", clean_path, "-O", protein_pdbqt, "-xr",
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+            _, stderr = await proc.communicate()
+            if proc.returncode != 0 or not os.path.exists(protein_pdbqt):
+                err = stderr.decode() if stderr else "obabel failed"
+                return {"error": f"Protein PDBQT preparation failed: {err}"}
+
+            # 4. Convert SMILES to 3D PDBQT via obabel
+            ligand_pdbqt = os.path.join(tmpdir, "ligand.pdbqt")
+            proc = await asyncio.create_subprocess_exec(
+                "obabel", f"-:{smiles}", "-O", ligand_pdbqt, "--gen3d", "-h",
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+            _, stderr = await proc.communicate()
+            if proc.returncode != 0 or not os.path.exists(ligand_pdbqt):
+                err = stderr.decode() if stderr else "obabel failed"
+                return {"error": f"Ligand PDBQT preparation failed: {err}"}
+
+            # 5. Determine binding site box
+            center = _find_ligand_center(pdb_content)
+            if center:
+                cx, cy, cz = center
+                sx = sy = sz = 20
+            else:
+                cx, cy, cz = _find_protein_center(pdb_content)
+                sx = sy = sz = 30
+
+            # 6. Run Vina
+            out_pdbqt = os.path.join(tmpdir, "out.pdbqt")
+            vina_cmd = await asyncio.create_subprocess_exec(
+                VINA_CMD,
+                "--receptor", protein_pdbqt,
+                "--ligand", ligand_pdbqt,
+                "--out", out_pdbqt,
+                "--center_x", str(cx),
+                "--center_y", str(cy),
+                "--center_z", str(cz),
+                "--size_x", str(sx),
+                "--size_y", str(sy),
+                "--size_z", str(sz),
+                "--exhaustiveness", "8",
+                "--num_modes", "9",
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+            try:
+                stdout, stderr = await asyncio.wait_for(vina_cmd.communicate(), timeout=600)
+            except asyncio.TimeoutError:
+                vina_cmd.kill()
+                await vina_cmd.communicate()
+                return {"error": "Docking timed out after 10 minutes"}
+
+            if vina_cmd.returncode != 0 or not os.path.exists(out_pdbqt):
+                err = stderr.decode("utf-8", errors="replace")[:500] if stderr else ""
+                return {"error": f"Vina failed (exit {vina_cmd.returncode}): {err}"}
+
+            # 7. Parse results
+            with open(out_pdbqt) as f:
+                out_content = f.read()
+
+            poses = _parse_vina_pdbqt(out_content)
+            log = stdout.decode() if stdout else ""
+
+            return {
+                "pdb_id": pdb_id,
+                "smiles": smiles,
+                "poses": poses,
+                "num_poses": len(poses),
+                "box_center": {"x": cx, "y": cy, "z": cz},
+                "box_size": {"x": sx, "y": sy, "z": sz},
+                "vina_log": log[:2000],
+                "from_cache": False,
+            }
+
+        except Exception as e:
+            logger.exception("Docking run failed")
+            return {"error": f"Docking failed: {e}"}
+        finally:
+            shutil.rmtree(tmpdir, ignore_errors=True)

bioai-platform/backend/requirements.txt

@@ -6,6 +6,7 @@ httpx
 aiohttp
 biopython
 litellm
+sentry-sdk
 python-dotenv
 supabase
 reportlab

bioai-platform/frontend/.env.local.example

@@ -4,3 +4,7 @@ NEXT_PUBLIC_SUPABASE_ANON_KEY=
 
 # API URL (set for production deploy, defaults to localhost:8000)
 NEXT_PUBLIC_API_URL=
+
+# Sentry (optional — set your DSN from sentry.io)
+NEXT_PUBLIC_SENTRY_DSN=
+SENTRY_DSN=

bioai-platform/frontend/next.config.js

@@ -1,3 +1,5 @@
+const { withSentryConfig } = require('@sentry/nextjs');
+
 /** @type {import('next').NextConfig} */
 const nextConfig = {
   async rewrites() {
@@ -11,4 +13,7 @@ const nextConfig = {
   },
 };
 
-module.exports = nextConfig;
+module.exports = withSentryConfig(nextConfig, {
+  silent: true,
+  hideSourceMaps: true,
+});

bioai-platform/frontend/package.json

@@ -9,6 +9,7 @@
     "lint": "next lint"
   },
   "dependencies": {
+    "@sentry/nextjs": "^10.60.0",
     "@supabase/ssr": "^0.12.0",
     "@supabase/supabase-js": "^2.49.4",
     "axios": "^1.7.9",
@@ -25,12 +26,12 @@
     "@types/node": "^22.13.4",
     "@types/react": "^18.3.18",
     "@types/react-dom": "^18.3.5",
+    "@types/three": "^0.184.1",
     "autoprefixer": "^10.4.20",
     "eslint": "^8.56.0",
     "eslint-config-next": "^14.2.23",
     "postcss": "^8.5.2",
     "tailwindcss": "^3.4.17",
-    "@types/three": "^0.184.1",
     "typescript": "^5.7.3"
   }
 }

bioai-platform/frontend/sentry.client.config.ts

@@ -0,0 +1,14 @@
+import * as Sentry from '@sentry/nextjs';
+
+Sentry.init({
+  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN || '',
+  environment: process.env.NEXT_PUBLIC_VERCEL_ENV || 'development',
+  tracesSampleRate: 0.1,
+  integrations: [Sentry.browserTracingIntegration()],
+  beforeSend(event) {
+    if (event.exception) {
+      console.error('[Sentry] Captured exception:', event.exception.values?.[0]?.value);
+    }
+    return event;
+  },
+});

bioai-platform/frontend/sentry.server.config.ts

@@ -0,0 +1,7 @@
+import * as Sentry from '@sentry/nextjs';
+
+Sentry.init({
+  dsn: process.env.SENTRY_DSN || process.env.NEXT_PUBLIC_SENTRY_DSN || '',
+  environment: process.env.NEXT_PUBLIC_VERCEL_ENV || 'development',
+  tracesSampleRate: 0.1,
+});

bioai-platform/frontend/src/app/(dashboard)/analyze/docking/page.tsx

@@ -0,0 +1,257 @@
+'use client';
+
+import { useState, useEffect, useCallback } from 'react';
+import { useRouter } from 'next/navigation';
+import { motion } from 'framer-motion';
+import { ArrowLeft, LoaderCircle, FlaskConical, CheckCircle, XCircle, AlertTriangle } from 'lucide-react';
+import { fadeUp } from '@/lib/animations';
+import { runDocking, getDockingStatus } from '@/lib/api';
+import type { DockingResult } from '@/lib/api';
+
+const PDB_EXAMPLES = ['1TIM', '4HHB', '1A42', '2XAB'];
+const SMILES_EXAMPLES = [
+  { label: 'Aspirin', value: 'CC(=O)Oc1ccccc1C(=O)O' },
+  { label: 'Caffeine', value: 'CN1C=NC2=C1C(=O)N(C(=O)N2C)C' },
+  { label: 'Ibuprofen', value: 'CC(C)Cc1ccc(cc1)C(C)C(=O)O' },
+];
+
+function affinityColor(affinity: number | null): string {
+  if (affinity === null) return 'text-text-muted';
+  if (affinity <= -8) return 'text-green-400';
+  if (affinity <= -5) return 'text-amber-400';
+  return 'text-red-400';
+}
+
+export default function DockingPage() {
+  const router = useRouter();
+  const [pdbId, setPdbId] = useState('');
+  const [smiles, setSmiles] = useState('');
+  const [jobId, setJobId] = useState<string | null>(null);
+  const [result, setResult] = useState<DockingResult | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [polling, setPolling] = useState(false);
+
+  const startDocking = async () => {
+    if (!pdbId.trim() || !smiles.trim()) return;
+    setLoading(true);
+    setError(null);
+    setResult(null);
+    setJobId(null);
+    try {
+      const { job_id } = await runDocking(pdbId.trim().toUpperCase(), smiles.trim());
+      setJobId(job_id);
+      setPolling(true);
+    } catch (err: unknown) {
+      setError(err instanceof Error ? err.message : 'Failed to start docking');
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const poll = useCallback(async () => {
+    if (!jobId) return;
+    try {
+      const status = await getDockingStatus(jobId);
+      setResult(status);
+      if (status.status === 'complete' || status.status === 'failed') {
+        setPolling(false);
+      }
+    } catch {
+      setPolling(false);
+      setError('Failed to check docking status');
+    }
+  }, [jobId]);
+
+  useEffect(() => {
+    if (!polling) return;
+    const interval = setInterval(poll, 3000);
+    return () => clearInterval(interval);
+  }, [polling, poll]);
+
+  useEffect(() => {
+    if (jobId) poll();
+  }, [jobId, poll]);
+
+  const statusIcon = () => {
+    if (!result) return null;
+    if (result.status === 'complete') return <CheckCircle className="w-5 h-5 text-green-400" />;
+    if (result.status === 'failed') return <XCircle className="w-5 h-5 text-red-400" />;
+    return <LoaderCircle className="w-5 h-5 text-accent-cyan animate-spin" />;
+  };
+
+  const bestPose = result?.result?.poses?.length
+    ? result.result.poses.reduce((a, b) => (a.affinity !== null && (b.affinity === null || a.affinity < b.affinity) ? a : b))
+    : null;
+
+  return (
+    <div className="max-w-3xl">
+      <button onClick={() => router.push('/analyze')} className="flex items-center gap-1 text-sm text-text-muted hover:text-text-primary mb-6 transition-colors">
+        <ArrowLeft className="w-4 h-4" /> Choose a different operation
+      </button>
+
+      <motion.div variants={fadeUp} initial="hidden" animate="show" className="mb-8">
+        <h1 className="text-2xl font-bold text-text-primary mb-1">Molecular Docking</h1>
+        <p className="text-sm text-text-secondary">Dock a small molecule (SMILES) into a protein structure (PDB ID) using AutoDock Vina. CPU-based, runs entirely on our server. Expect 1–5 min for completion.</p>
+      </motion.div>
+
+      <motion.div variants={fadeUp} initial="hidden" animate="show" className="glass-card p-5 mb-6 space-y-4">
+        <div>
+          <label className="block text-sm font-medium text-text-primary mb-1.5">PDB ID</label>
+          <input
+            type="text"
+            value={pdbId}
+            onChange={(e) => setPdbId(e.target.value.toUpperCase())}
+            onKeyDown={(e) => e.key === 'Enter' && startDocking()}
+            placeholder="e.g. 1TIM"
+            className="w-full px-4 py-3 rounded-xl border border-glass-border focus:border-accent-cyan/40 focus:ring-2 focus:ring-accent-cyan/10 outline-none transition text-sm font-mono bg-surface-1 text-text-primary"
+          />
+          <div className="flex gap-2 mt-2 flex-wrap">
+            <span className="text-xs text-text-muted">Examples:</span>
+            {PDB_EXAMPLES.map((pdb) => (
+              <button
+                key={pdb}
+                onClick={() => setPdbId(pdb)}
+                className="px-2 py-1 text-xs rounded bg-accent-cyan/10 text-accent-cyan hover:bg-accent-cyan/20 transition font-mono"
+              >
+                {pdb}
+              </button>
+            ))}
+          </div>
+        </div>
+
+        <div>
+          <label className="block text-sm font-medium text-text-primary mb-1.5">Ligand SMILES</label>
+          <input
+            type="text"
+            value={smiles}
+            onChange={(e) => setSmiles(e.target.value)}
+            onKeyDown={(e) => e.key === 'Enter' && startDocking()}
+            placeholder="e.g. CC(=O)Oc1ccccc1C(=O)O"
+            className="w-full px-4 py-3 rounded-xl border border-glass-border focus:border-accent-cyan/40 focus:ring-2 focus:ring-accent-cyan/10 outline-none transition text-sm font-mono bg-surface-1 text-text-primary"
+          />
+          <div className="flex gap-2 mt-2 flex-wrap">
+            <span className="text-xs text-text-muted">Examples:</span>
+            {SMILES_EXAMPLES.map((ex) => (
+              <button
+                key={ex.label}
+                onClick={() => setSmiles(ex.value)}
+                className="px-2 py-1 text-xs rounded bg-accent-cyan/10 text-accent-cyan hover:bg-accent-cyan/20 transition"
+              >
+                {ex.label}
+              </button>
+            ))}
+          </div>
+        </div>
+
+        <button onClick={startDocking} disabled={loading || !pdbId.trim() || !smiles.trim() || polling}
+          className="btn-primary w-full py-3 flex items-center justify-center gap-2 disabled:opacity-50">
+          {loading ? <LoaderCircle className="w-4 h-4 animate-spin" /> : <FlaskConical className="w-4 h-4" />}
+          {loading ? 'Starting...' : polling ? 'Running...' : 'Run Docking'}
+        </button>
+      </motion.div>
+
+      {error && (
+        <motion.div variants={fadeUp} initial="hidden" animate="show" className="glass-card p-4 mb-6 border border-red-400/20">
+          <div className="flex items-start gap-3">
+            <AlertTriangle className="w-5 h-5 text-red-400 flex-shrink-0 mt-0.5" />
+            <p className="text-sm text-red-400">{error}</p>
+          </div>
+        </motion.div>
+      )}
+
+      {result && (
+        <motion.div variants={fadeUp} initial="hidden" animate="show" className="space-y-4">
+          <div className="glass-card p-5">
+            <div className="flex items-center justify-between mb-3">
+              <div className="flex items-center gap-2">
+                {statusIcon()}
+                <span className="text-sm font-medium text-text-primary capitalize">{result.status}</span>
+              </div>
+              <span className="text-xs text-text-muted font-mono">{result.result?.pdb_id} + {result.result?.smiles?.slice(0, 20)}...</span>
+            </div>
+
+            {result.status === 'failed' && result.error && (
+              <div className="p-3 rounded-lg bg-red-400/5 border border-red-400/20 mt-3">
+                <pre className="text-xs text-red-400 whitespace-pre-wrap font-mono">{result.error}</pre>
+              </div>
+            )}
+          </div>
+
+          {result.result?.poses && result.result.poses.length > 0 && (
+            <div className="glass-card p-5">
+              <h3 className="text-sm font-semibold text-text-primary mb-3">Docking Results</h3>
+
+              <div className="grid grid-cols-2 gap-4 mb-4">
+                <div className="p-3 rounded-xl bg-surface-1">
+                  <p className="text-xs text-text-muted">Best Affinity</p>
+                  <p className={`text-lg font-bold font-mono ${affinityColor(bestPose?.affinity ?? null)}`}>
+                    {bestPose?.affinity?.toFixed(2) ?? '—'} <span className="text-xs font-normal">kcal/mol</span>
+                  </p>
+                </div>
+                <div className="p-3 rounded-xl bg-surface-1">
+                  <p className="text-xs text-text-muted">Poses Generated</p>
+                  <p className="text-lg font-bold text-text-primary font-mono">{result.result.num_poses}</p>
+                </div>
+              </div>
+
+              <div className="overflow-x-auto">
+                <table className="w-full text-sm">
+                  <thead>
+                    <tr className="text-xs text-text-muted uppercase border-b border-glass-border">
+                      <th className="text-left py-2 pr-4">Pose</th>
+                      <th className="text-left py-2 pr-4">Atoms</th>
+                      <th className="text-left py-2">Affinity (kcal/mol)</th>
+                    </tr>
+                  </thead>
+                  <tbody className="divide-y divide-glass-border">
+                    {result.result.poses.map((pose) => (
+                      <tr key={pose.model} className="text-text-primary">
+                        <td className="py-2 pr-4 font-mono">{pose.model}</td>
+                        <td className="py-2 pr-4 font-mono">{pose.atoms}</td>
+                        <td className={`py-2 font-mono ${affinityColor(pose.affinity)}`}>
+                          {pose.affinity !== null ? pose.affinity.toFixed(2) : '—'}
+                        </td>
+                      </tr>
+                    ))}
+                  </tbody>
+                </table>
+              </div>
+            </div>
+          )}
+
+          {result.result?.box_center && (
+            <div className="glass-card p-5">
+              <h3 className="text-sm font-semibold text-text-primary mb-3">Binding Site Search Box</h3>
+              <div className="grid grid-cols-2 gap-4 text-sm">
+                <div>
+                  <p className="text-xs text-text-muted mb-1">Center (x, y, z)</p>
+                  <p className="text-text-primary font-mono">
+                    {result.result.box_center.x.toFixed(2)}, {result.result.box_center.y.toFixed(2)}, {result.result.box_center.z.toFixed(2)}
+                  </p>
+                </div>
+                <div>
+                  <p className="text-xs text-text-muted mb-1">Size (x, y, z)</p>
+                  <p className="text-text-primary font-mono">
+                    {result.result.box_size.x}Å, {result.result.box_size.y}Å, {result.result.box_size.z}Å
+                  </p>
+                </div>
+              </div>
+            </div>
+          )}
+
+          {result.result?.pdb_id && (
+            <div className="glass-card p-5">
+              <h3 className="text-sm font-semibold text-text-primary mb-3">Structure</h3>
+              <iframe
+                src={`https://www.ebi.ac.uk/pdbe/entry/pdb/${result.result.pdb_id}/embedded/`}
+                className="w-full h-80 rounded-xl border-0"
+                title="Protein structure"
+              />
+            </div>
+          )}
+        </motion.div>
+      )}
+    </div>
+  );
+}

bioai-platform/frontend/src/app/(dashboard)/analyze/page.tsx

@@ -1,7 +1,7 @@
 'use client';
 
 import { useRouter } from 'next/navigation';
-import { Dna, Layout, Search, Globe, GitBranch, Beaker, Layers, Share2, FlaskConical, Shuffle, GitFork } from 'lucide-react';
+import { Dna, Layout, Search, Globe, GitBranch, Beaker, Layers, Share2, FlaskConical, Shuffle, GitFork, Atom } from 'lucide-react';
 import { motion } from 'framer-motion';
 import { fadeUp, stagger, cardHover } from '@/lib/animations';
 import { ReactNode } from 'react';
@@ -33,6 +33,7 @@ const groups: { title: string; items: Operation[] }[] = [
       { id: 'pathway',     name: 'Pathway Analysis',       description: 'Map genes to biological pathways from Reactome/KEGG.',      icon: GitBranch, active: true },
       { id: 'interactions', name: 'Protein Interactions',  description: 'Explore interaction partners from the STRING database.',     icon: Share2,    active: true },
       { id: 'compare',     name: 'Structure Compare',      description: 'Find structurally similar proteins via PDBeFold (TM-align).', icon: Shuffle, active: true },
+      { id: 'docking',     name: 'Molecular Docking',      description: 'Dock a small molecule into a protein using AutoDock Vina (free, CPU-based).', icon: Atom, active: true, badge: 'New' },
     ],
   },
   {

bioai-platform/frontend/src/app/(dashboard)/layout.tsx

@@ -11,6 +11,7 @@ import {
   History,
   Search,
   Settings,
+  BookOpen,
   ChevronRight,
   LogOut,
   Dna,
@@ -19,6 +20,7 @@ import {
 import { useAuth } from '@/contexts/auth';
 import { ThemeToggle } from '@/components/ThemeToggle';
 import { ErrorBoundary } from '@/components/ErrorBoundary';
+import { TutorialWalkthrough } from '@/components/TutorialWalkthrough';
 
 const NAV_ITEMS = [
   { href: '/dashboard', icon: LayoutDashboard, label: 'Dashboard'  },
@@ -26,6 +28,7 @@ const NAV_ITEMS = [
   { href: '/retrieve',  icon: Search,          label: 'Retrieve'   },
   { href: '/jobs',      icon: Clock,           label: 'Jobs'       },
   { href: '/history',   icon: History,         label: 'History'    },
+  { href: '/learn',     icon: BookOpen,        label: 'Learn'      },
   { href: '/settings',  icon: Settings,        label: 'Settings'   },
 ] as const;
 
@@ -303,6 +306,7 @@ export default function DashboardLayout({ children }: { children: React.ReactNod
           </div>
         </main>
       </div>
+      <TutorialWalkthrough />
     </div>
   );
 }

bioai-platform/frontend/src/app/(dashboard)/learn/[topic]/page.tsx

@@ -0,0 +1,295 @@
+'use client';
+
+import { useParams, useRouter } from 'next/navigation';
+import Link from 'next/link';
+import { motion } from 'framer-motion';
+import { fadeUp } from '@/lib/animations';
+import { ArrowLeft } from 'lucide-react';
+
+type Section = {
+  heading: string;
+  content: string;
+  code?: string;
+};
+
+type TopicData = {
+  title: string;
+  description: string;
+  sections: Section[];
+};
+
+const topics: Record<string, TopicData> = {
+  blast: {
+    title: 'BLAST Search',
+    description: 'Basic Local Alignment Search Tool — the most widely used method for finding sequence similarity.',
+    sections: [
+      {
+        heading: 'What is BLAST?',
+        content: 'BLAST compares a query sequence against a database of sequences and finds regions of local similarity. It uses a heuristic approach that is much faster than full dynamic programming (Smith-Waterman) while remaining sensitive enough for most searches. BLAST comes in several variants: BLASTP (protein-protein), BLASTN (nucleotide-nucleotide), BLASTX (translated nucleotide query against protein database), TBLASTN (protein query against translated nucleotide database), and TBLASTX (translated nucleotide against translated nucleotide).',
+      },
+      {
+        heading: 'How to read E-values',
+        content: 'The E-value (Expect value) describes how many matches you would expect to see by chance when searching a database of a given size. A lower E-value means a more significant match. An E-value of 0.05 means there is a 5% chance of seeing that match by chance alone. A good rule of thumb: E-values below 1e-5 (0.00001) are typically considered significant for homology searches. Values between 0.001 and 0.1 may indicate distant homology and should be investigated further.',
+        code: 'E-value = K × m × n × e^(−λS)\n\n  K = search-space constant\n  m = query length\n  n = database length\n  S = raw alignment score\n  λ = scoring-system lambda',
+      },
+      {
+        heading: 'Understanding bit scores',
+        content: 'The bit score is a normalized, log-scaled version of the raw alignment score. It is independent of database size and scoring matrix, making it comparable across different searches. A bit score of 50 or higher typically indicates a biologically relevant match. Bit scores are calculated as S\' = (λS − ln K) / ln 2, where S is the raw score, λ and K are statistical parameters of the scoring system.',
+      },
+      {
+        heading: 'Interpreting identity percentage',
+        content: 'Percent identity is simply the fraction of aligned positions where the residues match exactly, expressed as a percentage. It is the most intuitive metric but can be misleading for divergent sequences. For proteins, 30% identity over a full-length alignment is often considered the "twilight zone" below which inferring homology becomes unreliable. However, short regions of high identity can be functionally significant even when overall identity is low.',
+      },
+    ],
+  },
+  alignment: {
+    title: 'Sequence Alignment',
+    description: 'Comparing sequences to identify regions of similarity — the foundation of bioinformatics.',
+    sections: [
+      {
+        heading: 'Pairwise vs Multiple Alignment',
+        content: 'Pairwise alignment compares two sequences at a time. It can be global (Needleman-Wunsch) which aligns the entire length of both sequences, or local (Smith-Waterman) which finds the best matching subsequence. Multiple sequence alignment (MSA) extends this to three or more sequences, revealing conserved regions across a family. Common MSA tools include Clustal Omega, MAFFT, and MUSCLE. MSA is the basis for building phylogenetic trees, identifying conserved motifs, and improving structure prediction.',
+      },
+      {
+        heading: 'Scoring matrices',
+        content: 'Scoring matrices define the score for aligning any two residues. BLOSUM (BLOcks SUbstitution Matrix) matrices are the most common for proteins. BLOSUM62 is the default for most searches — it assumes sequences with ~62% identity. Higher numbers (BLOSUM80) are better for closely related sequences; lower numbers (BLOSUM45) are better for distantly related ones. For nucleotides, simple match/mismatch scores are typically used (e.g., +1/-1 or +2/-3).',
+        code: 'BLOSUM62 example (positive scores = conserved substitutions):\n\n     A   R   N   D   C   Q   E   G ...\n  A  4  -1  -2  -2   0  -1  -1   0\n  R -1   5   0  -2  -3   1   0  -2\n  N -2   0   6   1  -3   0   0   0\n  D -2  -2   1   6  -3   0   2  -1',
+      },
+      {
+        heading: 'Gap penalties',
+        content: 'Gap penalties control the cost of inserting gaps in an alignment. They consist of two components: a gap-open penalty (cost for starting a gap) and a gap-extension penalty (cost for extending an existing gap). Typical values for protein alignments are 10-12 for opening and 1-2 for extension. High gap penalties produce shorter, more compact alignments; low penalties allow longer gaps but risk over-fitting.',
+      },
+      {
+        heading: 'Reading alignment output',
+        content: 'Standard alignment output uses a three-line format for each block: the query sequence, a match line showing identical (|), conserved (:), and gap ( ) symbols, and the subject sequence. Identical residues indicate perfect conservation; conserved substitutions (similar biochemical properties) are shown with colons; non-conserved substitutions have no symbol. Gaps introduced in either sequence are shown as dashes.',
+        code: 'Query:   MKLLVLFLLGLVALSECDIYNYNA...KLCGVL\n                ||:||| || | ::|.||:  ...||:..|\nSubject: MKLLILFLLGLVALLLCEPSLYNYNA...NYCTAL',
+      },
+    ],
+  },
+  domains: {
+    title: 'Domain Analysis',
+    description: 'Identifying conserved functional and structural units within proteins.',
+    sections: [
+      {
+        heading: 'What are protein domains?',
+        content: 'A protein domain is a conserved, independently folding region of a protein that carries a specific function. Domains are the evolutionary building blocks of proteins — they can be shuffled, duplicated, and combined in different arrangements to create proteins with new functions. Most eukaryotic proteins contain multiple domains. Identifying domains helps predict protein function, even when the overall sequence has no known homologs.',
+      },
+      {
+        heading: 'Pfam and InterPro',
+        content: 'Pfam is a comprehensive database of protein domain families, each represented by a multiple sequence alignment and a hidden Markov model (HMM) profile. InterPro combines multiple domain databases (Pfam, SMART, PROSITE, CDD, etc.) into a single resource. When you run a domain analysis, your query is scanned against these HMM profiles to identify known domains. Each hit includes an E-value, bitscore, and the region of the query that matches the domain model.',
+      },
+      {
+        heading: 'Domain architecture',
+        content: 'Domain architecture refers to the linear arrangement of domains along a protein sequence. Many proteins have a modular architecture where different domains work together. For example, a signaling protein might have a receptor domain, a kinase domain, and a protein-protein interaction domain. Analyzing domain architecture helps predict function, evolutionary relationships, and potential interactions with other proteins.',
+        code: 'Example domain architecture:\n\n  Protein: EGFR (Epidermal Growth Factor Receptor)\n  \n  [Receptor L]──[Furin-like]──[GF_recep]──[TM]──[PKinase_Tyr]\n      |              |             |       |         |\n   Ligand-binding    |          Growth    Trans-   Tyrosine\n   (extracellular)   |          factor    membrane  kinase\n                  Cysteine-rich   rec.               (cytoplasmic)\n                  domain        domain',
+      },
+    ],
+  },
+  phylo: {
+    title: 'Phylogenetic Trees',
+    description: 'Reconstructing evolutionary relationships from molecular sequences.',
+    sections: [
+      {
+        heading: 'Phylogenetic trees',
+        content: 'A phylogenetic tree is a branching diagram showing the evolutionary relationships among species, genes, or sequences. Trees consist of branches (edges) and nodes (branch points). Terminal nodes (leaves) represent extant sequences; internal nodes represent hypothetical ancestors. Trees can be rooted (with a known common ancestor) or unrooted. The topology describes the branching order, while branch lengths typically represent evolutionary distance.',
+      },
+      {
+        heading: 'NJ vs UPGMA vs Maximum Likelihood',
+        content: 'Neighbor-Joining (NJ) is a fast distance-based method that builds a tree by iteratively joining the closest pair of sequences. UPGMA is another distance method that assumes a constant molecular clock (same rate across all lineages). Maximum Likelihood (ML) is a more sophisticated method that evaluates different tree topologies and selects the one that makes the sequence data most likely under a given substitution model. ML is slower but more accurate. Modern ML tools include RAxML-NG, IQ-TREE, and PhyML.',
+      },
+      {
+        heading: 'Reading bootstrap values',
+        content: 'Bootstrap values indicate how strongly the data supports a given branch. The original sequences are resampled (with replacement) hundreds or thousands of times, a tree is built from each replicate, and the fraction of replicates that recover the same branch is the bootstrap value. Values above 70% are considered moderately supported; above 95% is strongly supported. Bootstrap values below 50% suggest the branching order at that node is unreliable.',
+        code: 'Example tree with bootstrap values:\n\n                   ┌─── Human\n         ┌─── 98 ──┤\n         │         └─── Chimp\n    ── 100 ─┤\n         │         ┌─── Mouse\n         └─── 72 ──┤\n                   └─── Rat\n\n  100 = very strong support for human/chimp clade\n  72  = moderate support for mouse/rat clade',
+      },
+      {
+        heading: 'Branch lengths',
+        content: 'Branch lengths represent the amount of evolutionary change along a branch. The units are typically substitutions per site — the expected number of residue changes per position along that lineage. Longer branches mean more divergence. In distance-based trees, branch lengths are additive: the distance between two sequences is the sum of branch lengths along the path connecting them. In ML trees, branch lengths are optimized to maximize the likelihood of the data.',
+      },
+    ],
+  },
+  structure: {
+    title: 'Protein Structure',
+    description: 'Understanding the three-dimensional shapes of proteins and how to analyze them.',
+    sections: [
+      {
+        heading: 'PDB format',
+        content: 'The Protein Data Bank (PDB) format is the standard file format for macromolecular structures. Each line in a PDB file contains specific information identified by a record type (ATOM, HETATM, HELIX, SHEET, etc.). The ATOM records contain the coordinates (x, y, z) of each atom, along with the atom name, residue name, chain identifier, residue number, and occupancy/temperature factors. Modern alternatives include mmCIF and PDBx/mmCIF, but PDB remains widely supported.',
+        code: 'Example PDB ATOM record:\n\nATOM      1  N   ALA A   1      21.894  16.287   5.352  1.00  9.58           N\nATOM      2  CA  ALA A   1      22.482  15.026   5.846  1.00  9.74           C\nATOM      3  C   ALA A   1      23.176  14.242   4.744  1.00  9.46           C\nATOM      4  O   ALA A   1      23.121  14.636   3.579  1.00  9.22           O\n\nCol 1-6: Record name\nCol 7-11: Serial number\nCol 13-16: Atom name\nCol 18-20: Residue name\nCol 22: Chain ID\nCol 23-26: Residue number\nCol 31-38: X coordinate\nCol 39-46: Y coordinate\nCol 47-54: Z coordinate',
+      },
+      {
+        heading: 'AlphaFold',
+        content: 'AlphaFold is a deep learning system developed by DeepMind that predicts protein structures from amino acid sequences with accuracy comparable to experimental methods. AlphaFold2 won the CASP14 competition in 2020. Its successor, AlphaFold3, extends predictions to protein-ligand, protein-nucleic acid, and protein-small molecule complexes. The AlphaFold Database contains over 200 million predicted protein structures covering nearly all known proteins.',
+      },
+      {
+        heading: 'Reading pLDDT scores',
+        content: 'pLDDT (predicted Local Distance Difference Test) is AlphaFold\'s per-residue confidence score, ranging from 0 to 100. A pLDDT above 90 indicates very high confidence (comparable to experimental structures). Values between 70 and 90 indicate good backbone prediction. Values between 50 and 70 indicate low confidence, and below 50 indicates very low confidence — likely unstructured or disordered regions. The pLDDT score is stored in the B-factor column of the PDB file in AlphaFold predictions.',
+        code: 'pLDDT confidence interpretation:\n\n  > 90  — Very high (comparable to experiment)\n  70–90 — Good backbone prediction\n  50–70 — Low confidence\n  < 50  — Very low (likely disordered)',
+      },
+      {
+        heading: 'Structure visualization',
+        content: 'Protein structures can be visualized in several representations: cartoon/ribbon (shows secondary structure), surface (shows solvent-accessible surface), sticks (shows atomic bonds), and spheres (space-filling). Web-based viewers like Mol* (MolStar), NGL Viewer, and 3Dmol.js enable interactive visualization directly in the browser. Bio Nexus uses Mol* for structure rendering, supporting PDB and mmCIF files with customizable color schemes and selection highlighting.',
+      },
+    ],
+  },
+  pathways: {
+    title: 'Pathway Analysis',
+    description: 'Mapping genes and proteins to the biological pathways they participate in.',
+    sections: [
+      {
+        heading: 'What are pathways?',
+        content: 'A biological pathway is a series of molecular interactions and reactions that produce a specific cellular outcome. Metabolic pathways involve chemical transformations (e.g., glycolysis, citric acid cycle). Signaling pathways transmit signals from the cell surface to the nucleus (e.g., MAPK/ERK, Wnt). Gene regulatory pathways control gene expression. Pathway analysis helps interpret high-throughput data (RNA-seq, proteomics) by identifying which pathways are enriched in a set of differentially expressed genes.',
+      },
+      {
+        heading: 'Reactome vs KEGG',
+        content: 'Reactome is a free, open-source, manually curated pathway database with detailed molecular-level annotations. It provides excellent cross-references to other databases and supports pathway overrepresentation analysis (ORA). KEGG (Kyoto Encyclopedia of Genes and Genomes) is a comprehensive resource containing pathway maps, ortholog information, and chemical reactions. While KEGG remains popular, its licensing has become more restrictive. Reactome is generally preferred for open academic use.',
+      },
+      {
+        heading: 'Enrichment analysis',
+        content: 'Enrichment analysis determines whether a set of genes (e.g., upregulated in an RNA-seq experiment) contains more genes from a particular pathway than expected by chance. The standard method is Fisher\'s exact test or a hypergeometric test, corrected for multiple testing (Benjamini-Hochberg FDR). The result is a list of pathways ranked by significance, with enrichment ratios and adjusted p-values. Bio Nexus performs pathway enrichment against both Reactome and KEGG databases.',
+        code: 'Enrichment analysis results example:\n\nPathway                        Genes   Expected   Ratio   p-value    FDR\n──────────────────────────────────────────────────────────────────────\nDNA Replication                  12       2.1      5.7    8e-12    2e-9\nCell Cycle                       18       4.3      4.2    2e-10    3e-8\np53 Signaling                     8       1.2      6.7    5e-8     4e-6\n\nRatio = observed / expected count\nFDR   = false discovery rate (corrected p-value)',
+      },
+    ],
+  },
+  interactions: {
+    title: 'Protein Interactions',
+    description: 'Exploring the network of physical and functional associations between proteins.',
+    sections: [
+      {
+        heading: 'STRING database',
+        content: 'STRING (Search Tool for the Retrieval of Interacting Genes/Proteins) is a comprehensive database of known and predicted protein-protein interactions. It covers over 67 million proteins from more than 14,000 organisms. Interactions are derived from four sources: experimental evidence, curated databases, text mining of scientific literature, and computational predictions (gene neighborhood, gene fusions, gene co-occurrence). Each interaction is scored by how well the evidence supports it.',
+      },
+      {
+        heading: 'Interaction networks',
+        content: 'An interaction network consists of nodes (proteins) and edges (interactions). Networks can be visualized with different layout algorithms: force-directed (Fruchterman-Reingold), circular, or hierarchical. The network topology reveals hub proteins (highly connected), bottlenecks, and clusters corresponding to functional modules. Bio Nexus uses the STRING API to fetch interaction data and renders interactive networks using a force-directed layout.',
+      },
+      {
+        heading: 'Confidence scores',
+        content: 'STRING assigns each interaction a confidence score from 0 to 1,000, with higher values indicating stronger evidence. Scores are divided into three tiers: low confidence (< 150), medium confidence (150–700), and high confidence (> 700). The combined score integrates evidence from all sources using a naive Bayes approach. For most analyses, filtering at medium confidence (≥ 400) provides a good balance of sensitivity and specificity.',
+        code: 'STRING confidence tiers:\n\n  > 700  — High confidence (strong experimental + database evidence)\n  400–700 — Medium confidence (good for most analyses)\n  150–400 — Low confidence (primarily text-mining)\n  < 150  — Very low (likely noise)',
+      },
+    ],
+  },
+  primers: {
+    title: 'Primer Design',
+    description: 'Designing oligonucleotide primers for PCR amplification.',
+    sections: [
+      {
+        heading: 'PCR basics',
+        content: 'The Polymerase Chain Reaction (PCR) amplifies a specific DNA region between two primer binding sites. Each cycle consists of three steps: denaturation (95°C — separate DNA strands), annealing (50–65°C — primers bind), and extension (72°C — DNA polymerase extends). After 30–35 cycles, the target region is amplified by over a billion-fold. Successful PCR depends on well-designed primers that are specific, have appropriate melting temperatures, and do not form secondary structures.',
+      },
+      {
+        heading: 'Primer3',
+        content: 'Primer3 is the most widely used primer design software. It picks PCR primers from a template sequence, optimizing for melting temperature, GC content, primer length, and avoiding problematic features like hairpins, self-dimers, and cross-dimers. Bio Nexus uses Primer3 via its backend API to design primers for any input sequence. The tool evaluates hundreds of candidate primer pairs and returns the best ones ranked by a quality score.',
+      },
+      {
+        heading: 'Melting temperature',
+        content: 'The melting temperature (Tm) of a primer is the temperature at which half of the primer molecules are annealed to the template. It depends on primer length, GC content, and salt concentration. A common rule of thumb: Tm = 2°C × (A+T) + 4°C × (G+C). For PCR, primers should have Tm values between 55°C and 65°C, and the forward and reverse primers should have Tm values within 2–5°C of each other.',
+        code: 'Tm estimation (nearest-neighbor, simplified):\n\n  Tm = ΔH / (ΔS + R × ln(C/4)) − 273.15 + 16.6 × log([Na+])\n\n  ΔH = enthalpy change\n  ΔS = entropy change\n  R  = gas constant (1.987 cal/mol·K)\n  C  = primer concentration\n\nRule of thumb:\n  Tm ≈ 2(A+T) + 4(G+C)',
+      },
+      {
+        heading: 'GC content',
+        content: 'GC content — the percentage of guanine and cytosine bases in a primer — affects both melting temperature and secondary structure formation. Ideal primers have 40–60% GC content. Too high GC content (> 65%) increases the risk of non-specific binding and stable secondary structures. Too low GC content (< 35%) results in weak binding and low Tm. Primers with balanced GC content across the 3\' end provide the most reliable amplification.',
+      },
+    ],
+  },
+  tools: {
+    title: 'Format Converter',
+    description: 'Converting between common bioinformatics sequence formats.',
+    sections: [
+      {
+        heading: 'Format conversion',
+        content: 'Bio Nexus supports conversion between FASTA, GenBank, EMBL, and plain text formats. FASTA is the simplest format — a header line starting with ">" followed by the sequence. GenBank and EMBL are richer formats that include annotations, features, and references. When converting between formats, only the sequence and basic header information are preserved. Annotations and features are kept when converting between GenBank and EMBL.',
+        code: 'FASTA format:\n\n  >seq_id description\n  ATGCGATCGTAGCTAGCTAGCTAGCATCGATCG\n  GCTAGCTAGCATCGATCGATCGATCGATCGTAG\n\nGenBank format:\n\n  LOCUS       NM_001 1234 bp DNA linear\n  DEFINITION  Sample sequence.\n  ORIGIN\n      1 atgcgatcgt agctagctag ctagcatcga tcg\n     61 gctagctagc atcgatcgat cgatcgtagg tagcta\n  //',
+      },
+      {
+        heading: 'Sequence validation',
+        content: 'Sequence validation checks that your input contains only valid residues for the specified molecule type. For DNA, valid characters are A, C, G, T, and U (uracil is converted to thymine). For RNA, valid characters are A, C, G, and U. For protein, valid characters are the 20 standard amino acids (plus B, Z, X, and * for selenocysteine/pyrrolysine/stop). The validator also detects common issues like whitespace, line breaks, and numeric characters embedded in the sequence.',
+      },
+    ],
+  },
+  glossary: {
+    title: 'Glossary',
+    description: 'A–Z reference of bioinformatics terms with plain-English definitions.',
+    sections: [
+      {
+        heading: 'A–C',
+        content: 'Alignment — The arrangement of sequences to identify regions of similarity.\nAmino acid — One of 20 organic compounds that form proteins.\nBLAST — Basic Local Alignment Search Tool for finding sequence similarity.\nBit score — Normalized, database-size-independent score from a sequence search.\nBootstrap — Resampling method to assess confidence in phylogenetic tree branches.\nCDS — Coding Sequence, the region of a gene that is translated into protein.\nConserved — A residue or region that remains unchanged across evolution.\nContig — A contiguous sequence assembled from overlapping sequencing reads.',
+      },
+      {
+        heading: 'D–H',
+        content: 'Domain — A conserved, independently folding functional unit of a protein.\nE-value — Expect value: number of chance matches expected in a database search.\nEnrichment — Statistical overrepresentation of a pathway in a gene set.\nFASTA — Text-based sequence format using a single-line header starting with ">".\nFDR — False Discovery Rate, a correction for multiple hypothesis testing.\nGap — A space inserted in an alignment to compensate for insertions/deletions.\nGC content — Percentage of guanine and cytosine bases in a sequence.\nHMM — Hidden Markov Model, a statistical model used for profile searches.',
+      },
+      {
+        heading: 'I–M',
+        content: 'Identity — The percentage of exactly matching residues in an alignment.\nInterPro — Integrated database of protein domains, families, and functional sites.\nKEGG — Kyoto Encyclopedia of Genes and Genomes, a pathway database.\nLocal alignment — Alignment of only the most similar subsequences (Smith-Waterman).\nMelting temperature (Tm) — Temperature at which half of DNA duplex dissociates.\nML — Maximum Likelihood, a phylogenetic method that optimizes tree topology.\nMSA — Multiple Sequence Alignment, alignment of three or more sequences.\nMutation — A change in the nucleotide sequence of a genome.',
+      },
+      {
+        heading: 'N–R',
+        content: 'NJ — Neighbor-Joining, a fast distance-based phylogenetic tree-building method.\nORF — Open Reading Frame, a region of DNA potentially coding for a protein.\nOrtholog — Genes in different species that evolved from a common ancestral gene.\nPCR — Polymerase Chain Reaction, a method to amplify specific DNA sequences.\nPDB — Protein Data Bank, the global repository of 3D macromolecular structures.\nPfam — A database of protein domain families with associated HMM profiles.\nPhylogeny — The evolutionary history and relationships among organisms/sequences.\npLDDT — Predicted Local Distance Difference Test, AlphaFold\'s per-residue confidence.',
+      },
+      {
+        heading: 'S–Z',
+        content: 'Scoring matrix — A table of scores for aligning each pair of residues.\nSmith-Waterman — An algorithm for local sequence alignment.\nSTRING — Database of known and predicted protein-protein interactions.\nSubstitution — A residue replaced by another during evolution.\nTopology — The branching pattern of a phylogenetic tree (not including branch lengths).\nTwilight zone — Region of sequence similarity (~20–35% identity) where homology is uncertain.\nUPGMA — Unweighted Pair Group Method with Arithmetic Mean, a distance-based clustering method.\nVariant — A specific form of a genetic sequence that differs from the reference.',
+      },
+    ],
+  },
+};
+
+export default function TopicPage() {
+  const params = useParams();
+  const router = useRouter();
+  const topic = params.topic as string;
+  const data = topics[topic];
+
+  if (!data) {
+    return (
+      <div className="text-center py-20">
+        <h1 className="text-2xl font-bold text-text-primary mb-2">Topic not found</h1>
+        <p className="text-text-muted mb-6">No documentation available for &ldquo;{topic}&rdquo;.</p>
+        <button
+          onClick={() => router.push('/learn')}
+          className="btn-primary px-5 py-2.5 text-sm"
+        >
+          Back to Documentation
+        </button>
+      </div>
+    );
+  }
+
+  return (
+    <div className="max-w-3xl">
+      <motion.div variants={fadeUp} initial="hidden" animate="show">
+        <Link
+          href="/learn"
+          className="inline-flex items-center gap-1.5 text-sm text-text-muted hover:text-text-primary transition mb-6"
+        >
+          <ArrowLeft className="w-4 h-4" />
+          Back to Documentation
+        </Link>
+
+        <h1 className="text-2xl font-bold text-text-primary mb-2">{data.title}</h1>
+        <p className="text-text-muted mb-10 text-sm">{data.description}</p>
+      </motion.div>
+
+      <div className="space-y-10">
+        {data.sections.map((section, i) => (
+          <motion.section
+            key={i}
+            variants={fadeUp}
+            initial="hidden"
+            animate="show"
+          >
+            <h2 className="text-lg font-semibold text-text-primary mb-3">{section.heading}</h2>
+            <p className="text-sm text-text-secondary leading-relaxed whitespace-pre-line">{section.content}</p>
+            {section.code && (
+              <pre className="mt-4 p-4 rounded-xl bg-surface-1 border border-glass-border overflow-x-auto text-xs font-mono text-text-secondary leading-relaxed">
+                <code>{section.code}</code>
+              </pre>
+            )}
+          </motion.section>
+        ))}
+      </div>
+    </div>
+  );
+}

bioai-platform/frontend/src/app/(dashboard)/learn/page.tsx

@@ -0,0 +1,130 @@
+'use client';
+
+import Link from 'next/link';
+import {
+  Search, Dna, Layout, Layers, GitFork, Globe,
+  GitBranch, Share2, FlaskConical, Beaker, BookOpen, ArrowRight,
+} from 'lucide-react';
+import { motion } from 'framer-motion';
+import { fadeUp, stagger, cardHover } from '@/lib/animations';
+import { useState } from 'react';
+import type { LucideIcon } from 'lucide-react';
+
+type Topic = {
+  id: string;
+  title: string;
+  description: string;
+  icon: LucideIcon;
+};
+
+const groups: { title: string; items: Topic[] }[] = [
+  {
+    title: 'Sequence Analysis',
+    items: [
+      { id: 'blast',     title: 'BLAST Search',            description: 'Find similar sequences and understand E-values, bit scores, and identity.',   icon: Search },
+      { id: 'alignment', title: 'Sequence Alignment',      description: 'Pairwise and multiple alignment — scoring matrices, gap penalties, and output.', icon: Layout },
+      { id: 'domains',   title: 'Domain Analysis',         description: 'Protein domains, Pfam, InterPro, and domain architecture.',                     icon: Layers },
+      { id: 'phylo',     title: 'Phylogenetic Trees',      description: 'Tree-building methods, bootstrap values, and branch lengths.',                  icon: GitFork },
+    ],
+  },
+  {
+    title: 'Structure & Networks',
+    items: [
+      { id: 'structure',   title: 'Protein Structure',     description: 'PDB format, AlphaFold, pLDDT scores, and structure visualization.',            icon: Dna },
+      { id: 'pathways',    title: 'Pathway Analysis',      description: 'Reactome vs KEGG, pathway mapping, and enrichment analysis.',                  icon: GitBranch },
+      { id: 'interactions', title: 'Protein Interactions', description: 'STRING database, interaction networks, and confidence scores.',                icon: Globe },
+    ],
+  },
+  {
+    title: 'Utilities',
+    items: [
+      { id: 'primers', title: 'Primer Design',        description: 'PCR basics, Primer3, melting temperature, and GC content.',           icon: FlaskConical },
+      { id: 'tools',   title: 'Format Converter',     description: 'Sequence format conversion and validation utilities.',                 icon: Beaker },
+      { id: 'glossary', title: 'Glossary',            description: 'A–Z of bioinformatics terms with plain-English definitions.',          icon: BookOpen },
+    ],
+  },
+];
+
+function TopicCard({ topic }: { topic: Topic }) {
+  const Icon = topic.icon;
+  return (
+    <motion.div variants={fadeUp} whileHover={cardHover}>
+      <Link
+        href={`/learn/${topic.id}`}
+        className="relative block p-5 rounded-2xl border border-glass-border bg-glass-card hover:bg-surface-1 transition h-full"
+      >
+        <div className="flex items-start gap-4">
+          <div className="p-3 rounded-xl bg-accent-cyan/10 flex-shrink-0">
+            <Icon className="w-5 h-5 text-accent-cyan" />
+          </div>
+          <div className="flex-1 min-w-0">
+            <h3 className="font-semibold text-text-primary">{topic.title}</h3>
+            <p className="text-sm text-text-muted mt-1 leading-relaxed">{topic.description}</p>
+            <div className="flex items-center gap-1 mt-3 text-xs text-accent-cyan font-medium">
+              Learn more <ArrowRight className="w-3 h-3" />
+            </div>
+          </div>
+        </div>
+      </Link>
+    </motion.div>
+  );
+}
+
+export default function LearnPage() {
+  const [query, setQuery] = useState('');
+
+  const filtered = query.trim()
+    ? groups.map(g => ({
+        ...g,
+        items: g.items.filter(t =>
+          t.title.toLowerCase().includes(query.toLowerCase()) ||
+          t.description.toLowerCase().includes(query.toLowerCase())
+        ),
+      })).filter(g => g.items.length > 0)
+    : groups;
+
+  return (
+    <div>
+      <motion.div variants={fadeUp} initial="hidden" animate="show">
+        <h1 className="text-2xl font-bold text-text-primary mb-1">Documentation & Learning</h1>
+        <p className="text-text-muted mb-6">Learn the concepts behind every tool in Bio Nexus.</p>
+      </motion.div>
+
+      <motion.div variants={fadeUp} className="relative mb-10 max-w-xl">
+        <Search className="absolute left-4 top-1/2 -translate-y-1/2 w-4 h-4 text-text-muted" />
+        <input
+          type="text"
+          value={query}
+          onChange={e => setQuery(e.target.value)}
+          placeholder="Search topics..."
+          className="w-full pl-11 pr-4 py-3 rounded-2xl border border-glass-border bg-glass-card text-text-primary text-sm placeholder:text-text-muted/50 outline-none focus:border-accent-cyan/30 transition"
+        />
+      </motion.div>
+
+      {filtered.map(group => (
+        <div key={group.title} className="mb-10">
+          <motion.h2 variants={fadeUp} className="text-sm font-semibold text-text-muted uppercase tracking-wider mb-4">
+            {group.title}
+          </motion.h2>
+          <motion.div
+            variants={stagger}
+            initial="hidden"
+            whileInView="show"
+            viewport={{ once: true, margin: '-40px' }}
+            className="grid md:grid-cols-2 gap-4"
+          >
+            {group.items.map(topic => (
+              <TopicCard key={topic.id} topic={topic} />
+            ))}
+          </motion.div>
+        </div>
+      ))}
+
+      {filtered.length === 0 && (
+        <motion.p variants={fadeUp} className="text-text-muted text-sm text-center py-12">
+          No topics found for &ldquo;{query}&rdquo;.
+        </motion.p>
+      )}
+    </div>
+  );
+}

bioai-platform/frontend/src/components/LearnPopover.tsx

@@ -0,0 +1,66 @@
+'use client';
+
+import { useState, useRef, useEffect } from 'react';
+import Link from 'next/link';
+import { HelpCircle } from 'lucide-react';
+
+interface LearnPopoverProps {
+  term: string;
+  explanation: string;
+  topic?: string;
+  children: React.ReactNode;
+}
+
+export function LearnPopover({ term, explanation, topic, children }: LearnPopoverProps) {
+  const [open, setOpen] = useState(false);
+  const wrapperRef = useRef<HTMLSpanElement>(null);
+
+  useEffect(() => {
+    function handleClickOutside(e: MouseEvent) {
+      if (wrapperRef.current && !wrapperRef.current.contains(e.target as Node)) {
+        setOpen(false);
+      }
+    }
+    if (open) {
+      document.addEventListener('mousedown', handleClickOutside);
+    }
+    return () => document.removeEventListener('mousedown', handleClickOutside);
+  }, [open]);
+
+  return (
+    <span ref={wrapperRef} className="inline-flex items-center gap-0.5 relative">
+      <span
+        className="cursor-pointer border-b border-dotted border-accent-cyan/40 hover:border-accent-cyan transition"
+        onClick={() => setOpen(!open)}
+        role="button"
+        tabIndex={0}
+        onKeyDown={e => { if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); setOpen(!open); } }}
+        aria-label={`Learn about ${term}`}
+      >
+        {children}
+      </span>
+      <HelpCircle
+        size={12}
+        className="inline-block text-text-muted cursor-pointer hover:text-accent-cyan transition flex-shrink-0"
+        onClick={() => setOpen(!open)}
+      />
+      {open && (
+        <div
+          className="absolute z-50 top-full left-0 mt-2 p-4 rounded-xl border border-glass-border bg-surface-2 shadow-glass-md max-w-xs text-sm"
+          style={{ backdropFilter: 'blur(16px)' }}
+        >
+          <p className="font-semibold text-text-primary text-xs mb-1">{term}</p>
+          <p className="text-text-secondary text-xs leading-relaxed">{explanation}</p>
+          {topic && (
+            <Link
+              href={`/learn/${topic}`}
+              className="inline-block mt-2 text-xs text-accent-cyan hover:underline font-medium"
+            >
+              Learn more &rarr;
+            </Link>
+          )}
+        </div>
+      )}
+    </span>
+  );
+}

bioai-platform/frontend/src/components/TutorialWalkthrough.tsx

@@ -0,0 +1,171 @@
+'use client';
+
+import { useState, useEffect, useCallback } from 'react';
+import { motion, AnimatePresence } from 'framer-motion';
+import { X, ChevronLeft, ChevronRight, BookOpen } from 'lucide-react';
+
+const STEPS = [
+  {
+    title: 'Welcome to Bio Nexus',
+    description: 'Bio Nexus is your all-in-one bioinformatics platform. From BLAST searches to protein structure visualization, everything is designed to be fast and intuitive. This short tour will show you the essentials.',
+    highlight: 'sidebar',
+  },
+  {
+    title: 'Running an analysis',
+    description: 'Click any tool from the sidebar — BLAST, Alignment, Domain Analysis, and more. Paste a sequence, adjust parameters, and hit run. Results appear in seconds.',
+    highlight: 'nav-analyze',
+  },
+  {
+    title: 'Understanding results',
+    description: 'Results are displayed with clean, interactive visualizations. Tables, graphs, and 3D viewers help you interpret your data at a glance. Each result can be downloaded or shared.',
+    highlight: 'results',
+  },
+  {
+    title: 'AI interpretation',
+    description: 'Click "Interpret with AI" on any result page to get a plain-English explanation of what your results mean. The AI understands BLAST hits, pathway enrichment, domain architectures, and more.',
+    highlight: 'ai',
+  },
+  {
+    title: 'Learning more',
+    description: 'Visit the Learn section for in-depth documentation on every concept — E-values, bootstrap values, pLDDT scores, and dozens more. Terms marked with a (?) icon have instant explanations.',
+    highlight: 'nav-learn',
+  },
+];
+
+const STORAGE_KEY = 'bio-nexus-onboarding';
+
+export function TutorialWalkthrough() {
+  const [step, setStep] = useState(0);
+  const [visible, setVisible] = useState(false);
+
+  useEffect(() => {
+    const seen = localStorage.getItem(STORAGE_KEY);
+    if (!seen) {
+      setVisible(true);
+    }
+  }, []);
+
+  const dismiss = useCallback(() => {
+    setVisible(false);
+    localStorage.setItem(STORAGE_KEY, 'true');
+  }, []);
+
+  const next = useCallback(() => {
+    if (step < STEPS.length - 1) {
+      setStep(s => s + 1);
+    } else {
+      dismiss();
+    }
+  }, [step, dismiss]);
+
+  const prev = useCallback(() => {
+    if (step > 0) {
+      setStep(s => s - 1);
+    }
+  }, []);
+
+  const current = STEPS[step];
+
+  return (
+    <AnimatePresence>
+      {visible && (
+        <motion.div
+          key="tutorial-backdrop"
+          initial={{ opacity: 0 }}
+          animate={{ opacity: 1 }}
+          exit={{ opacity: 0 }}
+          transition={{ duration: 0.2 }}
+          className="fixed inset-0 z-[200] flex items-center justify-center"
+          style={{ background: 'rgba(4,4,10,0.75)', backdropFilter: 'blur(8px)' }}
+        >
+          <motion.div
+            key={`step-${step}`}
+            initial={{ opacity: 0, y: 24, scale: 0.97 }}
+            animate={{ opacity: 1, y: 0, scale: 1 }}
+            exit={{ opacity: 0, y: -16, scale: 0.97 }}
+            transition={{ duration: 0.35, ease: [0.25, 1, 0.5, 1] }}
+            className="relative w-full max-w-lg mx-4 p-8 rounded-2xl border border-glass-border shadow-glass-lg"
+            style={{
+              background: 'rgba(13,13,26,0.92)',
+              backdropFilter: 'blur(32px) saturate(180%)',
+            }}
+          >
+            <button
+              onClick={dismiss}
+              className="absolute top-4 right-4 p-1.5 rounded-lg text-text-muted hover:text-text-primary hover:bg-surface-1 transition"
+              aria-label="Skip tutorial"
+            >
+              <X className="w-4 h-4" />
+            </button>
+
+            <div className="flex items-center gap-3 mb-6">
+              <div className="p-2.5 rounded-xl bg-accent-cyan/10">
+                <BookOpen className="w-5 h-5 text-accent-cyan" />
+              </div>
+              <div>
+                <h2 className="text-lg font-semibold text-text-primary">{current.title}</h2>
+                <p className="text-xs text-text-muted">Step {step + 1} of {STEPS.length}</p>
+              </div>
+            </div>
+
+            <p className="text-sm text-text-secondary leading-relaxed mb-8">
+              {current.description}
+            </p>
+
+            {/* Step dots */}
+            <div className="flex items-center justify-center gap-1.5 mb-6">
+              {STEPS.map((_, i) => (
+                <div
+                  key={i}
+                  className={`h-1.5 rounded-full transition-all duration-300 ${
+                    i === step
+                      ? 'w-6 bg-accent-cyan'
+                      : i < step
+                        ? 'w-1.5 bg-accent-cyan/40'
+                        : 'w-1.5 bg-glass-border'
+                  }`}
+                />
+              ))}
+            </div>
+
+            <div className="flex items-center justify-between">
+              <button
+                onClick={prev}
+                disabled={step === 0}
+                className="btn-ghost px-4 py-2 text-sm disabled:opacity-30"
+              >
+                <ChevronLeft className="w-4 h-4" />
+                Back
+              </button>
+
+              <div className="flex items-center gap-3">
+                <button
+                  onClick={dismiss}
+                  className="text-xs text-text-muted hover:text-text-primary transition"
+                >
+                  Skip
+                </button>
+
+                <button
+                  onClick={next}
+                  className="btn-primary px-5 py-2 text-sm"
+                >
+                  {step < STEPS.length - 1 ? (
+                    <>Next <ChevronRight className="w-4 h-4" /></>
+                  ) : (
+                    'Get Started'
+                  )}
+                </button>
+              </div>
+            </div>
+          </motion.div>
+        </motion.div>
+      )}
+    </AnimatePresence>
+  );
+}
+
+export function startTutorial() {
+  localStorage.removeItem(STORAGE_KEY);
+  window.location.reload();
+}

bioai-platform/frontend/src/lib/api.ts

@@ -245,3 +245,35 @@ export async function runEnrichment(identifiers: string[]): Promise<EnrichmentRe
   const res = await api.post('/api/pathways/enrichment', { identifiers });
   return res.data;
 }
+
+export type DockingPose = {
+  model: number;
+  atoms: number;
+  affinity: number | null;
+};
+
+export type DockingResult = {
+  job_id: string;
+  status: string;
+  result?: {
+    pdb_id: string;
+    smiles: string;
+    poses: DockingPose[];
+    num_poses: number;
+    box_center: { x: number; y: number; z: number };
+    box_size: { x: number; y: number; z: number };
+    vina_log?: string;
+    from_cache?: boolean;
+  };
+  error?: string;
+};
+
+export async function runDocking(pdbId: string, smiles: string): Promise<{ job_id: string; status: string }> {
+  const res = await api.post('/api/docking/run', { pdb_id: pdbId, smiles });
+  return res.data;
+}
+
+export async function getDockingStatus(jobId: string): Promise<DockingResult> {
+  const res = await api.get(`/api/docking/status/${jobId}`);
+  return res.data;
+}

design.md

@@ -82,6 +82,16 @@ Type scale: `12 / 14 / 16 / 20 / 28 / 40 / 56px`, line-height 1.5 for body, 1.1
 ## 7. Iconography
 - Lucide icons (already in your stack), 1.5px stroke, sizes 16/20/24.
 
-## 8. Accessibility
+## 8. Documentation Site Design (`/learn`)
+
+- **Layout**: Centered content (max-width 880px), topic pages with back navigation, sticky right-side section nav for long pages
+- **Topic cards**: Same glass-card pattern as /analyze — icon + title + description in a 2-column grid
+- **Code examples**: `font-mono` on `bg-elevated` background, with horizontal scroll for long lines
+- **Glossary**: A–Z listing with letter dividers, term in `font-mono` semibold, definition in `text-text-secondary`
+- **LearnPopover**: Small `(?)` icon in `text-accent-cyan/60` next to term → click opens floating glass-card popover (max-width 320px) with 1-2 sentence explanation + optional "Learn more →" link in accent cyan
+
+## 9. Accessibility
 - All `--accent` on `--bg-base` text combinations pass WCAG AA at ≥14px.
 - Confidence bands are never color-only — always paired with the text label (colorblind-safe, and this is scientific data where ambiguity matters).
+- Tutorial walkthrough has keyboard navigation (Tab/Enter + Escape to close)
+- Sequence data rendered in monospace (`font-mono`) — never sans-serif

implementationplan.md

@@ -111,11 +111,13 @@ One golden path only: **Sequence In → BLAST → AI-interpreted report.** Every
 - Gene/protein → pathway lookup via Reactome/WikiPathways
 - Pathway diagram viewer
 
-### Sprint 8: Onboarding + `/learn`
-- First-run tutorial
-- Documentation pages generated from existing "what does this mean" content — write once, reuse
-
-### Sprint 9–10: Hardening
-- PDF report export
-- Cache-hit check before re-calling external APIs (raw responses already stored from Day 1)
-- Error monitoring (Sentry free tier)
+### 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) ✅

rules.md

@@ -1,15 +1,15 @@
 # BioFlow AI — Rules
 
-**Version:** 1.0  
-**Scope:** Both repos — `bioflow-frontend` and `bioflow-backend`  
+**Version:** 2.0  
+**Scope:** Both repos — `bioflow-frontend` and `bioflow-backend` (monorepo at `bio-nexus/bioai-platform/`)  
 **Last Updated:** June 2026
 
 ---
 
 ## 0 — The Prime Rule
 
-**The prototype ships June 30. Every decision is evaluated against this.**  
-If a rule conflicts with shipping the demo, ship the demo. Document the deviation. Fix it after.
+**The prototype shipped June 30 — Phase 2 is complete.**  
+Hardening (docs, Sentry, cache checks) is done. Phase 3+ items should be planned before building.
 
 ---
 
@@ -473,23 +473,61 @@ Data:
 
 ---
 
-## 8 — What NOT To Build (Pre-Demo)
-
-This list exists because scope creep during the 18-day sprint will kill the demo.
-
-❌ MSA wizard (Phase 2)  
-❌ Phylogenetic tree viewer (Phase 2)  
-❌ Protein 3D structure viewer (Phase 3)  
-❌ AlphaFold integration (Phase 3)  
-❌ Drug docking features (Phase 4)  
-❌ PDF export (post-demo Phase 1)  
-❌ Onboarding tutorial (post-demo Phase 1)  
-❌ Email notifications  
-❌ Rate limiting UI  
-❌ Admin panel  
-❌ Analytics dashboard  
-❌ Dark/light mode toggle (dark by default — toggle later)  
-❌ Mobile app  
-❌ Public API  
-
-If you find yourself working on any of the above before June 30: stop, commit your current work, and return to the demo track.
+## 8 — Monitoring & Observability Rules (Sentry)
+
+1. **Errors must be captured.** Every unhandled exception in production should reach Sentry. Frontend: `@sentry/nextjs` with `beforeSend` filtering. Backend: `sentry_sdk.init()` in startup.
+
+2. **No secrets in Sentry.** Ensure `beforeSend` strips auth tokens, API keys, and sequence data from Sentry events.
+
+3. **Traces** at `tracesSampleRate: 0.1` (10%) — enough for debugging, cheap enough for free tier.
+
+4. **Environment tagging.** All Sentry events must be tagged with `environment: development | production`.
+
+---
+
+## 9 — Caching Rules
+
+1. **Cache-first architecture.** Every external API call must check the corresponding cache before executing. Use `@ttl_cache` decorator from `services/cache.py`.
+
+2. **Cache key format.** `{prefix}:{sha256_first_16_chars_of_json_input}` — consistent, deterministic.
+
+3. **TTL guidelines:**
+   - BLAST results: 24h
+   - UniProt records: 24h
+   - AlphaFold predictions: 30 days
+   - Pathway enrichment: 12h
+   - NCBI sequence/search: 24h
+
+4. **Cache misses are tracked.** `get_cache_stats()` exposes hit/miss counts. Monitor via `/api/admin/cache-stats`.
+
+5. **`from_cache` flag.** All cached results include `from_cache: true/false` in the response dict for observability.
+
+6. **Graceful fallback.** If Redis is unavailable (`_redis = None`), caching is silently disabled — the app still works.
+
+---
+
+## 10 — Documentation & Learning Rules
+
+1. **`/learn` is the canonical docs source.** All inline "Learn more →" links must point to a valid `/learn/{topic}` route.
+
+2. **LearnPopover consistency.** Every scientific term shown to users (E-value, bit score, pLDDT, bootstrap, etc.) must have a LearnPopover component available.
+
+3. **First-run tutorial.** New users see the TutorialWalkthrough once. It must be re-accessible from the Settings page.
+
+4. **Plain language.** All docs and help text must be understandable by a first-year M.Sc. student. No jargon without explanation.
+
+---
+
+## 11 — What NOT To Build (Current)
+
+This list keeps scope in check for Phase 3+.
+
+❌ **Phase 2 items** — already built (MSA, Phylo, Domains, Pathways, Primers, API keys, Share, Export, Guest upgrade, Docs, Sentry, Cache checks)  
+❌ **Molecular docking / DiffDock** — requires revenue for paid Replicate API  
+❌ **RNA-seq pipeline** — Phase 3, requires file storage infrastructure  
+❌ **FASTQ / variant calling** — Phase 3, requires compute  
+❌ **Lab workspaces** — Phase 4, requires institution licensing  
+❌ **Custom pipeline builder** — Phase 4  
+❌ **Mobile app** — not planned  
+❌ **Email notifications** — not planned until Phase 4  
+❌ **Admin panel** — not needed until 100+ users

schema.md

@@ -586,6 +586,37 @@ These are stored in `jobs.input_params` as JSONB:
 
 ## Migration Notes
 
+## Additional Tables (Phase 2)
+
+### API Keys
+
+Applied via migration `006_api_keys.sql`:
+
+```sql
+create table if not exists api_keys (
+  id uuid primary key default gen_random_uuid(),
+  user_id uuid not null,
+  name text not null,
+  key_hash text not null,
+  key_prefix text not null,
+  created_at timestamptz default now(),
+  last_used_at timestamptz
+);
+
+create index if not exists idx_api_keys_user on api_keys(user_id);
+create index if not exists idx_api_keys_hash on api_keys(key_hash);
+
+alter table api_keys enable row level security;
+
+create policy "Users can manage own API keys" on api_keys for all
+  using (auth.uid() = user_id)
+  with check (auth.uid() = user_id);
+```
+
+---
+
+## Migration Notes
+
 - Run migrations in order via Supabase SQL editor or `supabase db push`
 - Never modify enum types after data exists — add new values only
 - Cache tables do not need migrations for TTL changes — update application config

techspec.md

@@ -1,125 +1,141 @@
 # BioFlow AI — Technical Specification
 
-**Version:** 1.0  
-**Repos:** `bioflow-frontend` (Next.js 14) · `bioflow-backend` (FastAPI)  
+**Version:** 2.0  
+**Repos:** Monorepo at `bio-nexus/bioai-platform/` — `frontend/` (Next.js 14) · `backend/` (FastAPI)  
 **Last Updated:** June 2026
 
 ---
 
 ## Repository Structure
 
-### `bioflow-frontend`
+### `bioai-platform/frontend` (Current Structure)
 
 ```
-bioflow-frontend/
-├── app/
-│   ├── (auth)/
-│   │   ├── login/
-│   │   │   └── page.tsx
-│   │   └── signup/
-│   │       └── page.tsx
-│   ├── (app)/
-│   │   ├── dashboard/
-│   │   │   └── page.tsx          # Job history, saved analyses
-│   │   ├── job/
-│   │   │   └── [jobId]/
-│   │   │       └── page.tsx      # Live job status + results
-│   │   └── layout.tsx            # App shell with nav
-│   ├── wizard/
-│   │   ├── page.tsx              # Workflow selection entry
-│   │   └── [workflowType]/
-│   │       └── page.tsx          # Specific wizard flow
-│   ├── api/
-│   │   └── auth/
-│   │       └── [...nextauth]/
-│   │           └── route.ts      # NextAuth handlers
-│   ├── layout.tsx                # Root layout
-│   ├── page.tsx                  # Landing page
-│   └── globals.css
-├── components/
-│   ├── ui/                       # Primitive components (button, input, card, etc.)
-│   ├── visualizations/
-│   │   ├── SequenceViewer.tsx    # Colored sequence display with annotations
-│   │   ├── BlastResultsTable.tsx # Interactive BLAST hits table
-│   │   ├── AlignmentViewer.tsx   # Color-coded pairwise alignment
-│   │   ├── MSAViewer.tsx         # Multiple sequence alignment block view
-│   │   ├── StructureViewer.tsx   # NGL.js / Mol* 3D structure wrapper
-│   │   ├── PhyloTreeViewer.tsx   # phylotree.js tree renderer
-│   │   ├── RamachandranPlot.tsx  # D3.js phi/psi scatter plot
-│   │   ├── ConservationPlot.tsx  # Per-position conservation bar chart
-│   │   └── PathwayViewer.tsx     # Reactome pathway embed
-│   ├── wizard/
-│   │   ├── WizardShell.tsx       # Step container, progress bar, navigation
-│   │   ├── WizardStep.tsx        # Individual step wrapper
-│   │   └── steps/
-│   │       ├── SequenceInputStep.tsx
-│   │       ├── DatabaseSelectStep.tsx
-│   │       ├── AlgorithmSelectStep.tsx
-│   │       └── ConfirmRunStep.tsx
-│   ├── job/
-│   │   ├── JobStatusCard.tsx     # Live step-by-step progress display
-│   │   ├── StepTimeline.tsx      # Visual pipeline step timeline
-│   │   └── ResultsPage.tsx       # Full results layout wrapper
-│   └── layout/
-│       ├── Navbar.tsx
-│       ├── Sidebar.tsx
-│       └── GuestBanner.tsx       # Shown to guest users prompting signup
-├── lib/
-│   ├── api.ts                    # Type-safe backend API client
-│   ├── supabase.ts               # Supabase client (browser)
-│   ├── supabase-server.ts        # Supabase client (server components)
-│   ├── types.ts                  # All shared TypeScript types
-│   └── constants.ts              # Workflow types, step labels, etc.
-├── hooks/
-│   ├── useJobPolling.ts          # React Query polling for job status
-│   ├── useGuestSession.ts        # Guest session cookie management
-│   └── useWorkflowWizard.ts      # Wizard state machine
-└── public/
-    └── fonts/                    # Self-hosted Space Grotesk + JetBrains Mono
+bioai-platform/frontend/
+├── src/
+│   ├── app/
+│   │   ├── (auth)/
+│   │   │   ├── auth/
+│   │   │   │   ├── callback/page.tsx
+│   │   │   │   └── page.tsx
+│   │   │   └── layout.tsx
+│   │   ├── (dashboard)/
+│   │   │   ├── layout.tsx                # App shell with collapsible sidebar + header
+│   │   │   ├── dashboard/page.tsx        # Stats, quick tools grid, recent jobs
+│   │   │   ├── analyze/page.tsx          # Operation hub (all tools listed)
+│   │   │   ├── analyze/blast/page.tsx
+│   │   │   ├── analyze/uniprot/page.tsx
+│   │   │   ├── analyze/structure/page.tsx
+│   │   │   ├── analyze/alignment/page.tsx
+│   │   │   ├── analyze/domains/page.tsx
+│   │   │   ├── analyze/phylo/page.tsx
+│   │   │   ├── analyze/pathway/page.tsx
+│   │   │   ├── analyze/interactions/page.tsx
+│   │   │   ├── analyze/compare/page.tsx
+│   │   │   ├── analyze/tools/page.tsx
+│   │   │   ├── analyze/primers/page.tsx
+│   │   │   ├── wizard/page.tsx           # 4-step guided pipeline wizard
+│   │   │   ├── jobs/page.tsx             # Job list with filter tabs
+│   │   │   ├── jobs/[jobId]/page.tsx     # Job detail + share
+│   │   │   ├── results/[jobId]/page.tsx
+│   │   │   ├── report/[jobId]/page.tsx   # Print-to-PDF report
+│   │   │   ├── history/page.tsx
+│   │   │   ├── retrieve/page.tsx
+│   │   │   ├── settings/page.tsx         # API keys, profile, guest upgrade, usage
+│   │   │   ├── shared/[token]/page.tsx
+│   │   │   └── learn/                    # Documentation site
+│   │   │       ├── page.tsx              # Docs landing with topic grid
+│   │   │       └── [topic]/page.tsx      # Dynamic topic pages
+│   │   ├── layout.tsx                    # Root layout (fonts, providers)
+│   │   ├── providers.tsx                 # Theme + Auth providers
+│   │   └── globals.css                   # Tailwind + glassmorphism overrides
+│   ├── components/
+│   │   ├── phylo/PhyloTreeViewer.tsx
+│   │   ├── results/PipelineResults.tsx
+│   │   ├── learn/LearnPopover.tsx        # Inline help popover
+│   │   ├── TutorialWalkthrough.tsx       # First-run onboarding modal
+│   │   ├── ErrorBoundary.tsx
+│   │   ├── GuestBanner.tsx
+│   │   ├── ThemeToggle.tsx
+│   │   └── ... (BlastPanel, ScoreBars, UniprotPanel, DomainSummary, etc.)
+│   ├── contexts/
+│   │   ├── auth.tsx                      # Auth context (Supabase session)
+│   │   └── theme.tsx                     # Theme context + localStorage
+│   ├── lib/
+│   │   ├── api.ts                        # Type-safe backend API client
+│   │   ├── supabase.ts                   # Supabase client (browser)
+│   │   ├── types.ts
+│   │   └── animations.ts                # Framer motion variants
+│   └── hooks/
+│       └── useJobPolling.ts
+├── sentry.client.config.ts              # Sentry client config
+├── sentry.server.config.ts              # Sentry server config
+├── next.config.js                       # Sentry-wrapped Next config
+└── package.json
 ```
 
-### `bioflow-backend`
+### `bioai-platform/backend` (Current Structure)
 
 ```
-bioflow-backend/
+bioai-platform/backend/
 ├── app/
-│   ├── main.py                   # FastAPI app, CORS, lifespan events
-│   ├── api/
-│   │   ├── deps.py               # Auth dependencies, DB session
-│   │   └── routes/
-│   │       ├── jobs.py           # POST /jobs, GET /jobs/{id}, GET /jobs/{id}/steps
-│   │       ├── sequences.py      # POST /sequences/fetch, POST /sequences/validate
-│   │       ├── blast.py          # POST /blast/submit, GET /blast/{job_id}/status
-│   │       ├── alignment.py      # POST /align/pairwise, POST /align/msa
-│   │       ├── structures.py     # POST /structures/fetch, POST /structures/predict
-│   │       └── dashboard.py      # GET /dashboard/jobs (paginated job history)
+│   ├── main.py                   # FastAPI app, CORS, lifespan (Sentry init, Redis init)
+│   ├── config.py                 # Settings via pydantic-settings + dotenv
+│   ├── routers/                  # 19 route modules
+│   │   ├── pipelines.py          # POST /api/pipelines/run
+│   │   ├── pipeline_v2.py        # POST /api/pipeline/v2/run, GET /status/{job_id}
+│   │   ├── ai.py                 # POST /api/ai/interpret, /interpret/stream
+│   │   ├── jobs.py               # GET/POST/DELETE /api/jobs
+│   │   ├── share.py              # POST /api/share, GET /api/share/{token}
+│   │   ├── profile.py            # GET/PUT /api/profile
+│   │   ├── sequences.py          # POST /api/sequences/fetch, /validate, /search
+│   │   ├── uniprot.py            # POST /api/uniprot/search, /detail
+│   │   ├── alignment.py          # POST /api/alignment/run
+│   │   ├── structures.py         # POST /api/structures/fetch, /search
+│   │   ├── pathways.py           # POST /api/pathways/search, /detail, /kegg/search, /enrichment
+│   │   ├── domains.py            # GET /api/domains/{accession}
+│   │   ├── interactions.py       # GET /api/interactions/{gene_name}
+│   │   ├── primers.py            # POST /api/primers/design
+│   │   ├── structure_analysis.py # GET /api/structure_analysis/ramachandran, /secondary, /compare
+│   │   ├── phylo.py              # POST /phylo/run, GET /status/{job_id}, /models
+│   │   ├── export.py             # GET /api/export/job/{id}?format=pdf|json
+│   │   ├── api_keys.py           # GET/POST /api/keys, DELETE /api/keys/{id}
+│   │   └── cache_stats.py        # GET /api/admin/cache-stats, POST /reset
 │   ├── services/
-│   │   ├── ncbi_service.py       # Entrez API wrapper (fetch, BLAST)
-│   │   ├── embl_service.py       # EMBL-EBI tools (BLAST, ClustalOmega, MUSCLE)
-│   │   ├── pdb_service.py        # RCSB PDB REST API
-│   │   ├── uniprot_service.py    # UniProt REST API
-│   │   ├── alphafold_service.py  # AlphaFold EBI API
-│   │   ├── reactome_service.py   # Reactome REST + WikiPathways fallback
-│   │   ├── groq_service.py       # Groq API for AI interpretation
-│   │   ├── r2_service.py         # Cloudflare R2 upload/download
-│   │   └── cache_service.py      # Cache read/write logic
+│   │   ├── cache.py              # Redis cache wrapper, @ttl_cache decorator, stats tracking
+│   │   ├── auth.py               # JWT auth, X-API-Key middleware
+│   │   ├── export.py             # PDF/JSON report generation (reportlab)
+│   │   ├── ncbi_service.py       # NCBI Entrez (fetch, search) — @ttl_cache on both
+│   │   ├── pathway_enrichment.py # Reactome enrichment — cached via cache_get/set
+│   │   ├── supabase.py           # Supabase REST client
+│   │   ├── rate_limit.py         # Per-user rate limiting
+│   │   ├── redis.py              # Redis connection
+│   │   ├── sequence_utils.py     # Sequence validation, type detection
+│   │   └── validators.py         # Input validation
+│   ├── tools/                    # Tool classes with @ttl_cache on run()
+│   │   ├── blast.py              # EBI BLAST submit/poll/parse
+│   │   ├── uniprot.py            # UniProt REST lookup
+│   │   ├── alphafold.py          # AlphaFold DB query
+│   │   ├── base.py               # Abstract BaseTool
+│   │   └── registration.py       # Tool registry
+│   ├── pipeline/                 # Pipeline v1 engine (deprecated in favor of v2)
 │   ├── workers/
-│   │   └── pipeline_worker.py    # Celery task: executes pipeline steps
-│   ├── parsers/
-│   │   ├── blast_parser.py       # NCBI BLAST XML → structured dict
-│   │   ├── alignment_parser.py   # ClustalW/MSA output → structured dict
-│   │   ├── pdb_parser.py         # PDB/mmCIF parsing via BioPython
-│   │   └── newick_parser.py      # Newick tree validation/normalization
-│   ├── models/
-│   │   └── schemas.py            # Pydantic v2 request/response models
-│   └── core/
-│       ├── config.py             # Settings (env vars via pydantic-settings)
-│       ├── database.py           # Supabase + async DB client
-│       └── exceptions.py         # Custom exception classes
-├── requirements.txt
-├── .env.example
-├── Dockerfile
-└── celery_worker.py              # Celery worker entrypoint
+│   │   ├── pipeline_worker.py    # Thread-based pipeline execution
+│   │   └── celery_app.py         # Celery app config (unused, kept for reference)
+│   ├── ai/                       # AI interpretation layer
+│   │   ├── interpreter.py
+│   │   ├── llm_client.py         # LiteLLM wrapper (Groq)
+│   │   └── prompts.py            # Prompt templates
+│   ├── models/responses.py       # Pydantic response models
+│   ├── integrations/ncbi/        # NCBI-specific modules
+│   │   ├── blast.py              # BLAST submission & polling
+│   │   └── parser.py             # XML parsing
+│   ├── data/demo_results.py      # Demo mode fallback sequences
+│   └── core/storage.py           # R2 storage wrapper
+├── requirements.txt              # + sentry-sdk
+├── .env.deploy                   # Deployment env template (+ SENTRY_DSN)
+├── Dockerfile                    # Pre-compiled PhyML binary download
+└── railway.json / render.yaml    # Deploy configs
 ```
 
 ---
@@ -666,19 +682,20 @@ RATE_LIMIT_EXCEEDED      — user has exceeded daily job quota
 ## Deployment
 
 ### Frontend — Vercel
-- Repo: `bioflow-frontend`
-- Framework preset: Next.js
+- Deployed from `bioai-platform/` (Root Directory: auto-detect)
+- Production URL: https://bioai-platform.vercel.app
 - Environment variables: set in Vercel dashboard
-- Domain: bioflow.ai (or subdomain for staging: staging.bioflow.ai)
+- Sentry DSN set as `NEXT_PUBLIC_SENTRY_DSN` + `SENTRY_DSN`
 
-### Backend — Railway
-- Repo: `bioflow-backend`
-- Service 1: FastAPI web (`uvicorn app.main:app --host 0.0.0.0 --port $PORT`)
-- Service 2: Celery worker (`celery -A celery_worker worker --loglevel=info`)
-- Both services share same repo, different start commands
-- Redis: Upstash (external, connects via REDIS_URL)
+### Backend — Hugging Face Spaces
+- Space: `Samad14/bio-nexus-api`
+- Public URL: https://samad14-bio-nexus-api.hf.space
+- SDK: Docker (cpu-basic, sleeps after 48h)
+- Deployed via `hf upload --type space ...` from local
+- Env vars set in HF Space dashboard (secrets)
+- PhyML binary: downloaded pre-compiled from bioconda in Dockerfile
 
 ### Staging vs Production
-- Two Vercel deployments: `main` → production, `dev` → staging
-- Two Railway environments: production and staging
-- Two Supabase projects: `bioflow-prod` and `bioflow-dev`
+- Single Vercel deployment: `main` → production
+- Single HF Space: `samad14-bio-nexus-api`
+- Supabase project: `bjbktegnmkljhuzlsvrf` (single project, RLS on tables)