phase 5 implementation docs

docs/superpowers/plans/2026-03-28-phase-2-instructor.md

@@ -0,0 +1,1292 @@
+# Phase 2 — Instructor Batch/Topic Management + Upload
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Build the instructor workflow — create a class batch, manage topics, and upload question banks via CSV — plus the NeonDB schema that all phases depend on.
+
+**Architecture:** Backend adds three new FastAPI routers (batches, topics, upload) and a CSV parser utility. Frontend gains an InstructorDashboard (batch creation + topic list with unlock toggles) and an Upload page. All DB tables are created once via a schema script applied against NeonDB.
+
+**Tech Stack:** FastAPI, asyncpg, python-multipart, React 18 + Vite + TypeScript, Tailwind CSS v3, Zustand v5
+
+---
+
+## File Map
+
+### Backend — Create/Modify
+- `backend/db/schema.sql` — all CREATE TABLE statements for the full app
+- `backend/db/apply_schema.py` — one-time script to run schema.sql against NeonDB
+- `backend/utils/__init__.py` — empty package marker
+- `backend/utils/csv_parser.py` — pure CSV-to-dict parser, no DB dependency
+- `backend/db/queries.py` — add batch/topic/question query functions
+- `backend/routers/batches.py` — POST /api/batches, GET /api/batches/mine, GET /api/batches/{batch_id}
+- `backend/routers/topics.py` — POST /api/topics, GET /api/topics?batch_id=..., PATCH /api/topics/{topic_id}
+- `backend/routers/upload.py` — POST /api/upload (multipart CSV + topic_id)
+- `backend/main.py` — register 3 new routers
+
+### Backend — Tests
+- `tests/test_csv_parser.py` — unit tests for parse_csv_questions
+
+### Frontend — Create/Modify
+- `frontend/src/api/topics.ts` — getMyBatch, createBatch, getTopics, createTopic, setTopicUnlock
+- `frontend/src/api/upload.ts` — uploadCSV (multipart fetch)
+- `frontend/src/components/shared/Navbar.tsx` — top nav with user name + logout
+- `frontend/src/components/instructor/StatCard.tsx` — reusable stat display card
+- `frontend/src/components/instructor/UploadZone.tsx` — drag-and-drop CSV input
+- `frontend/src/pages/InstructorDashboard.tsx` — batch creation flow + topic management
+- `frontend/src/pages/Upload.tsx` — CSV upload page
+
+---
+
+## Task 1: NeonDB schema
+
+**Files:**
+- Create: `backend/db/schema.sql`
+- Create: `backend/db/apply_schema.py`
+
+- [ ] **Step 1: Create backend/db/schema.sql**
+
+```sql
+-- backend/db/schema.sql
+-- Run once via: uv run python backend/db/apply_schema.py
+
+-- batches first (no FK to users yet — circular dependency resolved below)
+CREATE TABLE IF NOT EXISTS batches (
+  id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  name          TEXT NOT NULL,
+  instructor_id UUID NOT NULL,
+  class_code    TEXT NOT NULL UNIQUE DEFAULT upper(substring(gen_random_uuid()::text, 1, 8)),
+  created_at    TIMESTAMPTZ DEFAULT NOW()
+);
+
+-- users references batches
+CREATE TABLE IF NOT EXISTS users (
+  id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  full_name     TEXT NOT NULL,
+  email         TEXT NOT NULL UNIQUE,
+  password_hash TEXT NOT NULL,
+  role          TEXT NOT NULL CHECK (role IN ('student', 'instructor')),
+  batch_id      UUID REFERENCES batches(id) ON DELETE SET NULL,
+  created_at    TIMESTAMPTZ DEFAULT NOW()
+);
+
+-- add FK from batches.instructor_id → users.id (deferred until users exists)
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM information_schema.table_constraints
+    WHERE constraint_name = 'batches_instructor_id_fkey'
+      AND table_name = 'batches'
+  ) THEN
+    ALTER TABLE batches
+      ADD CONSTRAINT batches_instructor_id_fkey
+      FOREIGN KEY (instructor_id) REFERENCES users(id) ON DELETE CASCADE;
+  END IF;
+END $$;
+
+CREATE TABLE IF NOT EXISTS refresh_tokens (
+  id         UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id    UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  token_hash TEXT NOT NULL,
+  expires_at TIMESTAMPTZ NOT NULL,
+  created_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+CREATE TABLE IF NOT EXISTS topics (
+  id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  batch_id    UUID NOT NULL REFERENCES batches(id) ON DELETE CASCADE,
+  name        TEXT NOT NULL,
+  is_unlocked BOOLEAN NOT NULL DEFAULT FALSE,
+  order_index INTEGER NOT NULL DEFAULT 0,
+  created_at  TIMESTAMPTZ DEFAULT NOW()
+);
+
+CREATE TABLE IF NOT EXISTS questions (
+  id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  topic_id      UUID NOT NULL REFERENCES topics(id) ON DELETE CASCADE,
+  question_text TEXT NOT NULL,
+  difficulty    TEXT NOT NULL CHECK (difficulty IN ('easy', 'medium', 'hard')) DEFAULT 'medium',
+  created_at    TIMESTAMPTZ DEFAULT NOW()
+);
+
+CREATE TABLE IF NOT EXISTS interview_sessions (
+  id           UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  student_id   UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  topic_id     UUID NOT NULL REFERENCES topics(id) ON DELETE CASCADE,
+  status       TEXT NOT NULL CHECK (status IN ('active', 'completed')) DEFAULT 'active',
+  score        INTEGER CHECK (score >= 0 AND score <= 100),
+  feedback     JSONB,
+  started_at   TIMESTAMPTZ DEFAULT NOW(),
+  completed_at TIMESTAMPTZ
+);
+```
+
+- [ ] **Step 2: Create backend/db/apply_schema.py**
+
+```python
+"""Run once to apply DB schema to NeonDB. Usage: uv run python backend/db/apply_schema.py"""
+import asyncio
+import os
+from pathlib import Path
+
+import asyncpg
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+async def main() -> None:
+    sql = (Path(__file__).parent / "schema.sql").read_text()
+    conn = await asyncpg.connect(os.getenv("NEON_DB_URL"))
+    try:
+        await conn.execute(sql)
+        print("Schema applied successfully.")
+    finally:
+        await conn.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+- [ ] **Step 3: Run schema migration**
+
+Make sure `.env` is present with a valid `NEON_DB_URL`, then run:
+
+```bash
+uv run python backend/db/apply_schema.py
+```
+
+Expected output: `Schema applied successfully.`
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add backend/db/schema.sql backend/db/apply_schema.py
+git commit -m "feat: add NeonDB schema (all tables) and apply_schema script"
+```
+
+---
+
+## Task 2: CSV parser utility + tests
+
+**Files:**
+- Create: `backend/utils/__init__.py`
+- Create: `backend/utils/csv_parser.py`
+- Create: `tests/test_csv_parser.py`
+
+- [ ] **Step 1: Create backend/utils/__init__.py**
+
+```python
+```
+
+(empty file — marks the utils package)
+
+- [ ] **Step 2: Write failing tests first**
+
+Create `tests/test_csv_parser.py`:
+
+```python
+from backend.utils.csv_parser import parse_csv_questions
+
+
+def test_parses_valid_csv():
+    text = "question_text,difficulty\nWhat is Python?,easy\nExplain GIL,hard"
+    result = parse_csv_questions(text)
+    assert len(result) == 2
+    assert result[0] == {"question_text": "What is Python?", "difficulty": "easy"}
+    assert result[1] == {"question_text": "Explain GIL", "difficulty": "hard"}
+
+
+def test_defaults_invalid_difficulty_to_medium():
+    text = "question_text,difficulty\nWhat is Python?,bogus"
+    result = parse_csv_questions(text)
+    assert result[0]["difficulty"] == "medium"
+
+
+def test_skips_empty_question_text():
+    text = "question_text,difficulty\n,easy\nWhat is Python?,easy"
+    result = parse_csv_questions(text)
+    assert len(result) == 1
+
+
+def test_missing_difficulty_column_defaults_to_medium():
+    text = "question_text\nWhat is Python?"
+    result = parse_csv_questions(text)
+    assert result[0]["difficulty"] == "medium"
+
+
+def test_empty_csv_returns_empty_list():
+    text = "question_text,difficulty\n"
+    result = parse_csv_questions(text)
+    assert result == []
+
+
+def test_strips_whitespace():
+    text = "question_text,difficulty\n  What is Python?  ,  easy  "
+    result = parse_csv_questions(text)
+    assert result[0]["question_text"] == "What is Python?"
+    assert result[0]["difficulty"] == "easy"
+```
+
+- [ ] **Step 3: Run tests — expect failure**
+
+```bash
+uv run pytest tests/test_csv_parser.py -v
+```
+
+Expected: `FAILED` — `ModuleNotFoundError`
+
+- [ ] **Step 4: Implement backend/utils/csv_parser.py**
+
+```python
+import csv
+import io
+
+_VALID_DIFFICULTIES = {"easy", "medium", "hard"}
+
+
+def parse_csv_questions(text: str) -> list[dict]:
+    """
+    Parse CSV text into question dicts.
+    Expected columns: question_text, difficulty
+    Returns list of {"question_text": str, "difficulty": str}.
+    Skips rows where question_text is empty.
+    Defaults difficulty to 'medium' if missing or invalid.
+    """
+    reader = csv.DictReader(io.StringIO(text))
+    rows = []
+    for row in reader:
+        question_text = (row.get("question_text") or "").strip()
+        difficulty = (row.get("difficulty") or "medium").strip().lower()
+        if not question_text:
+            continue
+        if difficulty not in _VALID_DIFFICULTIES:
+            difficulty = "medium"
+        rows.append({"question_text": question_text, "difficulty": difficulty})
+    return rows
+```
+
+- [ ] **Step 5: Run tests — expect all pass**
+
+```bash
+uv run pytest tests/test_csv_parser.py -v
+```
+
+Expected: `6 passed`
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add backend/utils/__init__.py backend/utils/csv_parser.py tests/test_csv_parser.py
+git commit -m "feat: add CSV question parser utility with unit tests"
+```
+
+---
+
+## Task 3: DB queries for batches, topics, questions
+
+**Files:**
+- Modify: `backend/db/queries.py`
+
+- [ ] **Step 1: Append batch/topic/question query functions**
+
+Add to the bottom of `backend/db/queries.py`:
+
+```python
+async def create_batch(name: str, instructor_id: str) -> asyncpg.Record:
+    async with get_pool().acquire() as conn:
+        return await conn.fetchrow(
+            """
+            INSERT INTO batches (name, instructor_id)
+            VALUES ($1, $2)
+            RETURNING *
+            """,
+            name, instructor_id,
+        )
+
+
+async def get_batch_by_instructor_id(instructor_id: str) -> Optional[asyncpg.Record]:
+    async with get_pool().acquire() as conn:
+        return await conn.fetchrow(
+            "SELECT * FROM batches WHERE instructor_id = $1", instructor_id
+        )
+
+
+async def get_batch_by_id(batch_id: str) -> Optional[asyncpg.Record]:
+    async with get_pool().acquire() as conn:
+        return await conn.fetchrow(
+            "SELECT * FROM batches WHERE id = $1", batch_id
+        )
+
+
+async def create_topic(batch_id: str, name: str, order_index: int) -> asyncpg.Record:
+    async with get_pool().acquire() as conn:
+        return await conn.fetchrow(
+            """
+            INSERT INTO topics (batch_id, name, order_index)
+            VALUES ($1, $2, $3)
+            RETURNING *
+            """,
+            batch_id, name, order_index,
+        )
+
+
+async def get_topics_by_batch_id(batch_id: str) -> list[asyncpg.Record]:
+    async with get_pool().acquire() as conn:
+        return await conn.fetch(
+            "SELECT * FROM topics WHERE batch_id = $1 ORDER BY order_index ASC",
+            batch_id,
+        )
+
+
+async def get_topic_by_id(topic_id: str) -> Optional[asyncpg.Record]:
+    async with get_pool().acquire() as conn:
+        return await conn.fetchrow(
+            "SELECT * FROM topics WHERE id = $1", topic_id
+        )
+
+
+async def set_topic_unlock(topic_id: str, is_unlocked: bool) -> asyncpg.Record:
+    async with get_pool().acquire() as conn:
+        return await conn.fetchrow(
+            """
+            UPDATE topics SET is_unlocked = $1
+            WHERE id = $2
+            RETURNING *
+            """,
+            is_unlocked, topic_id,
+        )
+
+
+async def create_questions_bulk(topic_id: str, rows: list[dict]) -> int:
+    async with get_pool().acquire() as conn:
+        await conn.executemany(
+            """
+            INSERT INTO questions (topic_id, question_text, difficulty)
+            VALUES ($1, $2, $3)
+            """,
+            [(topic_id, r["question_text"], r["difficulty"]) for r in rows],
+        )
+        return len(rows)
+
+
+async def get_question_count_by_topic(topic_id: str) -> int:
+    async with get_pool().acquire() as conn:
+        result = await conn.fetchrow(
+            "SELECT COUNT(*) AS count FROM questions WHERE topic_id = $1",
+            topic_id,
+        )
+        return result["count"]
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add backend/db/queries.py
+git commit -m "feat: add batch/topic/question DB queries"
+```
+
+---
+
+## Task 4: Batches router
+
+**Files:**
+- Create: `backend/routers/batches.py`
+
+- [ ] **Step 1: Create backend/routers/batches.py**
+
+```python
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel
+
+from backend.auth.deps import require_instructor
+from backend.db import queries
+
+router = APIRouter()
+
+
+class CreateBatchRequest(BaseModel):
+    name: str
+
+
+def _batch_out(batch) -> dict:
+    return {
+        "id": str(batch["id"]),
+        "name": batch["name"],
+        "instructor_id": str(batch["instructor_id"]),
+        "class_code": batch["class_code"],
+    }
+
+
+@router.post("")
+async def create_batch(
+    body: CreateBatchRequest,
+    user: dict = Depends(require_instructor),
+):
+    existing = await queries.get_batch_by_instructor_id(user["user_id"])
+    if existing:
+        raise HTTPException(400, "You already have a batch")
+    batch = await queries.create_batch(body.name, user["user_id"])
+    return _batch_out(batch)
+
+
+@router.get("/mine")
+async def get_my_batch(user: dict = Depends(require_instructor)):
+    batch = await queries.get_batch_by_instructor_id(user["user_id"])
+    if not batch:
+        raise HTTPException(404, "No batch found")
+    return _batch_out(batch)
+
+
+@router.get("/{batch_id}")
+async def get_batch(
+    batch_id: str,
+    user: dict = Depends(require_instructor),
+):
+    batch = await queries.get_batch_by_id(batch_id)
+    if not batch:
+        raise HTTPException(404, "Batch not found")
+    return _batch_out(batch)
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add backend/routers/batches.py
+git commit -m "feat: batches router — create, get mine, get by id"
+```
+
+---
+
+## Task 5: Topics router
+
+**Files:**
+- Create: `backend/routers/topics.py`
+
+- [ ] **Step 1: Create backend/routers/topics.py**
+
+```python
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel
+
+from backend.auth.deps import require_instructor
+from backend.db import queries
+
+router = APIRouter()
+
+
+class CreateTopicRequest(BaseModel):
+    batch_id: str
+    name: str
+
+
+class UpdateTopicRequest(BaseModel):
+    is_unlocked: bool
+
+
+def _topic_out(topic, question_count: int = 0) -> dict:
+    return {
+        "id": str(topic["id"]),
+        "batch_id": str(topic["batch_id"]),
+        "name": topic["name"],
+        "is_unlocked": topic["is_unlocked"],
+        "order_index": topic["order_index"],
+        "question_count": question_count,
+    }
+
+
+@router.post("")
+async def create_topic(
+    body: CreateTopicRequest,
+    user: dict = Depends(require_instructor),
+):
+    batch = await queries.get_batch_by_id(body.batch_id)
+    if not batch or str(batch["instructor_id"]) != user["user_id"]:
+        raise HTTPException(403, "Batch not found or not yours")
+    existing = await queries.get_topics_by_batch_id(body.batch_id)
+    order_index = len(existing)
+    topic = await queries.create_topic(body.batch_id, body.name, order_index)
+    return _topic_out(topic)
+
+
+@router.get("")
+async def list_topics(
+    batch_id: str,
+    user: dict = Depends(require_instructor),
+):
+    topics = await queries.get_topics_by_batch_id(batch_id)
+    result = []
+    for t in topics:
+        count = await queries.get_question_count_by_topic(str(t["id"]))
+        result.append(_topic_out(t, count))
+    return result
+
+
+@router.patch("/{topic_id}")
+async def update_topic(
+    topic_id: str,
+    body: UpdateTopicRequest,
+    user: dict = Depends(require_instructor),
+):
+    topic = await queries.get_topic_by_id(topic_id)
+    if not topic:
+        raise HTTPException(404, "Topic not found")
+    batch = await queries.get_batch_by_id(str(topic["batch_id"]))
+    if not batch or str(batch["instructor_id"]) != user["user_id"]:
+        raise HTTPException(403, "Topic does not belong to your batch")
+    updated = await queries.set_topic_unlock(topic_id, body.is_unlocked)
+    count = await queries.get_question_count_by_topic(topic_id)
+    return _topic_out(updated, count)
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add backend/routers/topics.py
+git commit -m "feat: topics router — create, list, unlock/lock"
+```
+
+---
+
+## Task 6: Upload router
+
+**Files:**
+- Create: `backend/routers/upload.py`
+
+- [ ] **Step 1: Create backend/routers/upload.py**
+
+```python
+from fastapi import APIRouter, Depends, File, Form, HTTPException, UploadFile
+
+from backend.auth.deps import require_instructor
+from backend.db import queries
+from backend.utils.csv_parser import parse_csv_questions
+
+router = APIRouter()
+
+
+@router.post("")
+async def upload_questions(
+    topic_id: str = Form(...),
+    file: UploadFile = File(...),
+    user: dict = Depends(require_instructor),
+):
+    if not (file.filename or "").endswith(".csv"):
+        raise HTTPException(400, "File must be a .csv")
+
+    content = await file.read()
+    text = content.decode("utf-8-sig")  # strips BOM if present
+
+    rows = parse_csv_questions(text)
+    if not rows:
+        raise HTTPException(400, "CSV is empty or contains no valid question rows")
+
+    topic = await queries.get_topic_by_id(topic_id)
+    if not topic:
+        raise HTTPException(404, "Topic not found")
+
+    batch = await queries.get_batch_by_id(str(topic["batch_id"]))
+    if not batch or str(batch["instructor_id"]) != user["user_id"]:
+        raise HTTPException(403, "Topic does not belong to your batch")
+
+    inserted = await queries.create_questions_bulk(topic_id, rows)
+    return {"inserted": inserted}
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add backend/routers/upload.py
+git commit -m "feat: upload router — parse CSV and bulk insert questions"
+```
+
+---
+
+## Task 7: Wire main.py
+
+**Files:**
+- Modify: `backend/main.py`
+
+- [ ] **Step 1: Replace backend/main.py**
+
+```python
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+
+from backend.db.connection import init_db_pool
+from backend.routers import auth, batches, topics, upload
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    await init_db_pool()
+    yield
+
+
+app = FastAPI(lifespan=lifespan)
+
+app.include_router(auth.router, prefix="/api/auth")
+app.include_router(batches.router, prefix="/api/batches")
+app.include_router(topics.router, prefix="/api/topics")
+app.include_router(upload.router, prefix="/api/upload")
+
+# React static build — MUST be last
+# app.mount("/", StaticFiles(directory="frontend/dist", html=True), name="static")
+```
+
+- [ ] **Step 2: Verify backend imports cleanly**
+
+```bash
+uv run python -c "from backend.main import app; print('OK')"
+```
+
+Expected: `OK` (plus possible JWT_SECRET warning — that is fine)
+
+- [ ] **Step 3: Run all backend tests**
+
+```bash
+uv run pytest tests/ -v
+```
+
+Expected: `17 passed` (11 existing + 6 csv parser)
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add backend/main.py
+git commit -m "feat: register batches, topics, upload routers in main.py"
+```
+
+---
+
+## Task 8: Frontend API layer
+
+**Files:**
+- Modify: `frontend/src/api/topics.ts`
+- Create: `frontend/src/api/upload.ts`
+
+- [ ] **Step 1: Implement frontend/src/api/topics.ts**
+
+```typescript
+import { apiFetch } from './client'
+
+export interface Batch {
+  id: string
+  name: string
+  instructor_id: string
+  class_code: string
+}
+
+export interface Topic {
+  id: string
+  batch_id: string
+  name: string
+  is_unlocked: boolean
+  order_index: number
+  question_count: number
+}
+
+export async function getMyBatch(): Promise<Batch> {
+  const res = await apiFetch('/api/batches/mine')
+  if (!res.ok) throw new Error('No batch found')
+  return res.json()
+}
+
+export async function createBatch(name: string): Promise<Batch> {
+  const res = await apiFetch('/api/batches', {
+    method: 'POST',
+    body: JSON.stringify({ name }),
+  })
+  if (!res.ok) {
+    const err = await res.json()
+    throw new Error(err.detail ?? 'Failed to create batch')
+  }
+  return res.json()
+}
+
+export async function getTopics(batch_id: string): Promise<Topic[]> {
+  const res = await apiFetch(`/api/topics?batch_id=${batch_id}`)
+  if (!res.ok) throw new Error('Failed to load topics')
+  return res.json()
+}
+
+export async function createTopic(batch_id: string, name: string): Promise<Topic> {
+  const res = await apiFetch('/api/topics', {
+    method: 'POST',
+    body: JSON.stringify({ batch_id, name }),
+  })
+  if (!res.ok) {
+    const err = await res.json()
+    throw new Error(err.detail ?? 'Failed to create topic')
+  }
+  return res.json()
+}
+
+export async function setTopicUnlock(topic_id: string, is_unlocked: boolean): Promise<Topic> {
+  const res = await apiFetch(`/api/topics/${topic_id}`, {
+    method: 'PATCH',
+    body: JSON.stringify({ is_unlocked }),
+  })
+  if (!res.ok) throw new Error('Failed to update topic')
+  return res.json()
+}
+```
+
+- [ ] **Step 2: Create frontend/src/api/upload.ts**
+
+```typescript
+import { useAuthStore } from '../store/authStore'
+
+export async function uploadCSV(
+  topic_id: string,
+  file: File,
+): Promise<{ inserted: number }> {
+  const token = useAuthStore.getState().accessToken
+  const formData = new FormData()
+  formData.append('file', file)
+  formData.append('topic_id', topic_id)
+
+  // Cannot use apiFetch here — Content-Type must be set by browser for multipart
+  const res = await fetch('/api/upload', {
+    method: 'POST',
+    headers: token ? { Authorization: `Bearer ${token}` } : {},
+    body: formData,
+    credentials: 'include',
+  })
+  if (!res.ok) {
+    const err = await res.json()
+    throw new Error(err.detail ?? 'Upload failed')
+  }
+  return res.json()
+}
+```
+
+- [ ] **Step 3: Verify TypeScript compiles**
+
+```bash
+cd frontend && npx tsc --noEmit && cd ..
+```
+
+Expected: no errors
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add frontend/src/api/topics.ts frontend/src/api/upload.ts
+git commit -m "feat: frontend topics and upload API layer"
+```
+
+---
+
+## Task 9: Navbar + StatCard
+
+**Files:**
+- Modify: `frontend/src/components/shared/Navbar.tsx`
+- Create: `frontend/src/components/instructor/StatCard.tsx`
+
+- [ ] **Step 1: Implement Navbar.tsx**
+
+```typescript
+import { useNavigate } from 'react-router-dom'
+import { logout } from '../../api/auth'
+import { useAuthStore } from '../../store/authStore'
+
+export default function Navbar() {
+  const navigate = useNavigate()
+  const { user, clearAuth } = useAuthStore()
+
+  async function handleLogout() {
+    try { await logout() } catch { /* ignore */ }
+    clearAuth()
+    navigate('/login', { replace: true })
+  }
+
+  return (
+    <nav className="bg-gray-900 border-b border-gray-800 px-6 py-3 flex items-center justify-between">
+      <span className="text-white font-semibold text-lg tracking-tight">InterviewMentor</span>
+      {user && (
+        <div className="flex items-center gap-4">
+          <span className="text-gray-400 text-sm">{user.full_name}</span>
+          <button
+            onClick={handleLogout}
+            className="text-sm text-gray-400 hover:text-white transition-colors"
+          >
+            Sign out
+          </button>
+        </div>
+      )}
+    </nav>
+  )
+}
+```
+
+- [ ] **Step 2: Create frontend/src/components/instructor/StatCard.tsx**
+
+```typescript
+interface Props {
+  label: string
+  value: string | number
+}
+
+export default function StatCard({ label, value }: Props) {
+  return (
+    <div className="bg-gray-900 border border-gray-800 rounded-lg px-4 py-3">
+      <p className="text-gray-400 text-xs uppercase tracking-wide">{label}</p>
+      <p className="text-white text-2xl font-semibold mt-1">{value}</p>
+    </div>
+  )
+}
+```
+
+- [ ] **Step 3: Verify TypeScript compiles**
+
+```bash
+cd frontend && npx tsc --noEmit && cd ..
+```
+
+Expected: no errors
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add frontend/src/components/shared/Navbar.tsx frontend/src/components/instructor/StatCard.tsx
+git commit -m "feat: Navbar with logout and StatCard component"
+```
+
+---
+
+## Task 10: InstructorDashboard page
+
+**Files:**
+- Modify: `frontend/src/pages/InstructorDashboard.tsx`
+
+- [ ] **Step 1: Implement frontend/src/pages/InstructorDashboard.tsx**
+
+```typescript
+import { useState, useEffect, type FormEvent } from 'react'
+import { useNavigate } from 'react-router-dom'
+import Navbar from '../components/shared/Navbar'
+import StatCard from '../components/instructor/StatCard'
+import {
+  getMyBatch, createBatch, getTopics, createTopic, setTopicUnlock,
+  type Batch, type Topic,
+} from '../api/topics'
+
+export default function InstructorDashboard() {
+  const navigate = useNavigate()
+  const [batch, setBatch] = useState<Batch | null>(null)
+  const [topics, setTopics] = useState<Topic[]>([])
+  const [batchName, setBatchName] = useState('')
+  const [newTopicName, setNewTopicName] = useState('')
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState('')
+
+  useEffect(() => {
+    getMyBatch()
+      .then(async (b) => {
+        setBatch(b)
+        const t = await getTopics(b.id)
+        setTopics(t)
+      })
+      .catch(() => { /* 404 = no batch yet */ })
+      .finally(() => setLoading(false))
+  }, [])
+
+  async function handleCreateBatch(e: FormEvent) {
+    e.preventDefault()
+    setError('')
+    try {
+      const b = await createBatch(batchName.trim())
+      setBatch(b)
+      setTopics([])
+      setBatchName('')
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Failed to create batch')
+    }
+  }
+
+  async function handleAddTopic(e: FormEvent) {
+    e.preventDefault()
+    if (!batch || !newTopicName.trim()) return
+    setError('')
+    try {
+      const t = await createTopic(batch.id, newTopicName.trim())
+      setTopics((prev) => [...prev, t])
+      setNewTopicName('')
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Failed to add topic')
+    }
+  }
+
+  async function handleToggleUnlock(topic: Topic) {
+    try {
+      const updated = await setTopicUnlock(topic.id, !topic.is_unlocked)
+      setTopics((prev) => prev.map((t) => (t.id === topic.id ? updated : t)))
+    } catch { /* silently ignore */ }
+  }
+
+  if (loading) {
+    return (
+      <div className="min-h-screen bg-gray-950">
+        <Navbar />
+        <div className="flex items-center justify-center h-64">
+          <p className="text-gray-400">Loading...</p>
+        </div>
+      </div>
+    )
+  }
+
+  return (
+    <div className="min-h-screen bg-gray-950">
+      <Navbar />
+      <div className="max-w-3xl mx-auto px-6 py-8">
+
+        {!batch ? (
+          /* ── Create batch ── */
+          <div className="bg-gray-900 border border-gray-800 rounded-xl p-8 max-w-md mx-auto">
+            <h2 className="text-xl font-semibold text-white mb-2">Create your batch</h2>
+            <p className="text-gray-400 text-sm mb-6">Give your class a name to get started.</p>
+            <form onSubmit={handleCreateBatch} className="space-y-4">
+              <input
+                type="text"
+                value={batchName}
+                onChange={(e) => setBatchName(e.target.value)}
+                required
+                placeholder="e.g. Batch A — Jan 2026"
+                className="w-full bg-gray-800 border border-gray-700 rounded-lg px-4 py-2 text-white placeholder-gray-500 focus:outline-none focus:border-indigo-500"
+              />
+              {error && <p className="text-red-400 text-sm">{error}</p>}
+              <button
+                type="submit"
+                className="w-full bg-indigo-600 hover:bg-indigo-500 text-white rounded-lg px-4 py-2 font-medium transition-colors"
+              >
+                Create batch
+              </button>
+            </form>
+          </div>
+        ) : (
+          <>
+            {/* ── Batch header ── */}
+            <div className="bg-gray-900 border border-gray-800 rounded-xl p-6 mb-6 flex items-start justify-between">
+              <div>
+                <h1 className="text-2xl font-semibold text-white">{batch.name}</h1>
+                <p className="text-gray-400 text-sm mt-1">Share this code with your students</p>
+              </div>
+              <div className="bg-gray-800 border border-gray-700 rounded-lg px-4 py-2 text-center ml-4 shrink-0">
+                <p className="text-xs text-gray-400 mb-1">Class code</p>
+                <p className="text-xl font-mono font-bold text-indigo-400">{batch.class_code}</p>
+              </div>
+            </div>
+
+            {/* ── Stats row ── */}
+            <div className="grid grid-cols-2 gap-4 mb-6">
+              <StatCard label="Topics" value={topics.length} />
+              <StatCard
+                label="Questions"
+                value={topics.reduce((sum, t) => sum + t.question_count, 0)}
+              />
+            </div>
+
+            {/* ── Topic list ── */}
+            <div className="bg-gray-900 border border-gray-800 rounded-xl p-6">
+              <h2 className="text-lg font-semibold text-white mb-4">Topics</h2>
+
+              {topics.length === 0 && (
+                <p className="text-gray-500 text-sm mb-4">No topics yet. Add one below.</p>
+              )}
+
+              <div className="space-y-3 mb-6">
+                {topics.map((topic) => (
+                  <div
+                    key={topic.id}
+                    className="flex items-center justify-between bg-gray-800 border border-gray-700 rounded-lg px-4 py-3"
+                  >
+                    <div>
+                      <p className="text-white font-medium">{topic.name}</p>
+                      <p className="text-gray-400 text-xs mt-0.5">{topic.question_count} questions</p>
+                    </div>
+                    <div className="flex items-center gap-3">
+                      <button
+                        onClick={() =>
+                          navigate(
+                            `/instructor/upload?topic_id=${topic.id}&topic_name=${encodeURIComponent(topic.name)}`,
+                          )
+                        }
+                        className="text-sm text-indigo-400 hover:text-indigo-300 transition-colors"
+                      >
+                        Add questions
+                      </button>
+                      <button
+                        onClick={() => handleToggleUnlock(topic)}
+                        className={`text-xs px-3 py-1 rounded-full font-medium transition-colors ${
+                          topic.is_unlocked
+                            ? 'bg-green-900 text-green-300 hover:bg-green-800'
+                            : 'bg-gray-700 text-gray-400 hover:bg-gray-600'
+                        }`}
+                      >
+                        {topic.is_unlocked ? 'Unlocked' : 'Locked'}
+                      </button>
+                    </div>
+                  </div>
+                ))}
+              </div>
+
+              {/* ── Add topic form ── */}
+              <form onSubmit={handleAddTopic} className="flex gap-2">
+                <input
+                  type="text"
+                  value={newTopicName}
+                  onChange={(e) => setNewTopicName(e.target.value)}
+                  placeholder="New topic name"
+                  className="flex-1 bg-gray-800 border border-gray-700 rounded-lg px-4 py-2 text-white placeholder-gray-500 focus:outline-none focus:border-indigo-500"
+                />
+                <button
+                  type="submit"
+                  className="bg-indigo-600 hover:bg-indigo-500 text-white rounded-lg px-4 py-2 font-medium transition-colors"
+                >
+                  Add
+                </button>
+              </form>
+              {error && <p className="text-red-400 text-sm mt-2">{error}</p>}
+            </div>
+          </>
+        )}
+      </div>
+    </div>
+  )
+}
+```
+
+- [ ] **Step 2: Verify TypeScript compiles**
+
+```bash
+cd frontend && npx tsc --noEmit && cd ..
+```
+
+Expected: no errors
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add frontend/src/pages/InstructorDashboard.tsx
+git commit -m "feat: InstructorDashboard — batch creation, class code display, topic management"
+```
+
+---
+
+## Task 11: Upload page + UploadZone
+
+**Files:**
+- Create: `frontend/src/components/instructor/UploadZone.tsx`
+- Modify: `frontend/src/pages/Upload.tsx`
+
+- [ ] **Step 1: Create frontend/src/components/instructor/UploadZone.tsx**
+
+```typescript
+import { useRef, useState } from 'react'
+
+interface Props {
+  onFile: (file: File) => void
+  uploading: boolean
+}
+
+export default function UploadZone({ onFile, uploading }: Props) {
+  const inputRef = useRef<HTMLInputElement>(null)
+  const [dragging, setDragging] = useState(false)
+
+  function handleDrop(e: React.DragEvent) {
+    e.preventDefault()
+    setDragging(false)
+    const file = e.dataTransfer.files[0]
+    if (file) onFile(file)
+  }
+
+  function handleChange(e: React.ChangeEvent<HTMLInputElement>) {
+    const file = e.target.files?.[0]
+    if (file) onFile(file)
+  }
+
+  return (
+    <div
+      onDragOver={(e) => { e.preventDefault(); setDragging(true) }}
+      onDragLeave={() => setDragging(false)}
+      onDrop={handleDrop}
+      onClick={() => inputRef.current?.click()}
+      className={`border-2 border-dashed rounded-xl p-12 text-center cursor-pointer transition-colors select-none ${
+        dragging ? 'border-indigo-500 bg-indigo-950' : 'border-gray-700 hover:border-gray-600'
+      } ${uploading ? 'opacity-50 pointer-events-none' : ''}`}
+    >
+      <input
+        ref={inputRef}
+        type="file"
+        accept=".csv"
+        className="hidden"
+        onChange={handleChange}
+      />
+      <p className="text-gray-300 font-medium">
+        {uploading ? 'Uploading...' : 'Drop your CSV here or click to browse'}
+      </p>
+      <p className="text-gray-500 text-sm mt-1">.csv files only</p>
+    </div>
+  )
+}
+```
+
+- [ ] **Step 2: Implement frontend/src/pages/Upload.tsx**
+
+```typescript
+import { useState } from 'react'
+import { useNavigate, useSearchParams } from 'react-router-dom'
+import Navbar from '../components/shared/Navbar'
+import UploadZone from '../components/instructor/UploadZone'
+import { uploadCSV } from '../api/upload'
+
+export default function Upload() {
+  const navigate = useNavigate()
+  const [searchParams] = useSearchParams()
+  const topicId = searchParams.get('topic_id') ?? ''
+  const topicName = searchParams.get('topic_name') ?? 'Unknown topic'
+  const [result, setResult] = useState<{ inserted: number } | null>(null)
+  const [error, setError] = useState('')
+  const [uploading, setUploading] = useState(false)
+
+  async function handleFile(file: File) {
+    if (!topicId) {
+      setError('Missing topic ID — go back to the dashboard.')
+      return
+    }
+    setError('')
+    setUploading(true)
+    try {
+      const res = await uploadCSV(topicId, file)
+      setResult(res)
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Upload failed')
+    } finally {
+      setUploading(false)
+    }
+  }
+
+  return (
+    <div className="min-h-screen bg-gray-950">
+      <Navbar />
+      <div className="max-w-2xl mx-auto px-6 py-8">
+        <button
+          onClick={() => navigate('/instructor/dashboard')}
+          className="text-sm text-gray-400 hover:text-white mb-6 inline-flex items-center gap-1 transition-colors"
+        >
+          ← Back to dashboard
+        </button>
+
+        <h1 className="text-2xl font-semibold text-white mb-1">Upload questions</h1>
+        <p className="text-gray-400 text-sm mb-6">
+          Topic: <span className="text-indigo-400">{topicName}</span>
+        </p>
+
+        {result ? (
+          <div className="bg-green-950 border border-green-800 rounded-xl p-8 text-center">
+            <p className="text-green-300 text-lg font-semibold">
+              ✓ {result.inserted} questions uploaded
+            </p>
+            <button
+              onClick={() => navigate('/instructor/dashboard')}
+              className="mt-4 text-sm text-gray-400 hover:text-white transition-colors"
+            >
+              Back to dashboard
+            </button>
+          </div>
+        ) : (
+          <>
+            <UploadZone onFile={handleFile} uploading={uploading} />
+            {error && <p className="text-red-400 text-sm mt-3">{error}</p>}
+            <div className="mt-6 bg-gray-900 border border-gray-800 rounded-lg p-4">
+              <p className="text-gray-400 text-sm font-medium mb-2">CSV format</p>
+              <pre className="text-xs text-gray-500 font-mono whitespace-pre">{`question_text,difficulty\nWhat is Python?,easy\nExplain the GIL,hard\nWhat is a decorator?,medium`}</pre>
+              <p className="text-gray-500 text-xs mt-2">
+                Difficulty: <code className="text-gray-400">easy</code> |{' '}
+                <code className="text-gray-400">medium</code> |{' '}
+                <code className="text-gray-400">hard</code>{' '}
+                (defaults to <code className="text-gray-400">medium</code> if missing or invalid)
+              </p>
+            </div>
+          </>
+        )}
+      </div>
+    </div>
+  )
+}
+```
+
+- [ ] **Step 3: Run full frontend build**
+
+```bash
+cd frontend && npm run build && cd ..
+```
+
+Expected: clean build, no errors
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add frontend/src/components/instructor/UploadZone.tsx frontend/src/pages/Upload.tsx
+git commit -m "feat: Upload page with drag-and-drop UploadZone and CSV format guide"
+```
+
+---
+
+## Task 12: Final verification + push
+
+- [ ] **Step 1: Run all backend tests**
+
+```bash
+uv run pytest tests/ -v
+```
+
+Expected: `17 passed`
+
+- [ ] **Step 2: Verify frontend build**
+
+```bash
+cd frontend && npm run build && cd ..
+```
+
+Expected: clean build
+
+- [ ] **Step 3: Verify backend imports cleanly**
+
+```bash
+uv run python -c "from backend.main import app; print('OK')"
+```
+
+Expected: `OK`
+
+- [ ] **Step 4: Push to GitHub**
+
+```bash
+git push origin main
+```
+
+---
+
+## Self-Review
+
+**Spec coverage:**
+- ✅ NeonDB schema — all 6 tables (Task 1)
+- ✅ `batches.py` router — POST /api/batches, GET /api/batches/mine, GET /api/batches/{batch_id} (Task 4)
+- ✅ `topics.py` router — POST /api/topics, GET /api/topics?batch_id=..., PATCH /api/topics/{topic_id} (Task 5)
+- ✅ `upload.py` router — POST /api/upload with multipart CSV (Task 6)
+- ✅ CSV parser — pure function with 6 unit tests (Task 2)
+- ✅ DB queries — all batch/topic/question operations (Task 3)
+- ✅ Frontend: topics.ts + upload.ts API layer (Task 8)
+- ✅ Frontend: Navbar with logout (Task 9)
+- ✅ Frontend: StatCard component (Task 9)
+- ✅ Frontend: InstructorDashboard — batch creation, class code, topic management (Task 10)
+- ✅ Frontend: Upload page + UploadZone drag-and-drop (Task 11)
+- ✅ main.py updated with all routers (Task 7)
+
+**Type consistency check:**
+- `Batch` interface (topics.ts) matches `_batch_out()` return shape in batches.py ✅
+- `Topic` interface (topics.ts) matches `_topic_out()` return shape in topics.py ✅
+- `uploadCSV(topic_id, file)` in upload.ts matches Form(...) params in upload.py ✅
+- `create_questions_bulk` takes `list[dict]` and returns `int` — matched in upload router ✅

docs/superpowers/plans/2026-03-28-phase-5-langgraph-engine.md

@@ -0,0 +1,1135 @@
+# Phase 5 — LangGraph Interview Engine
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Build the LangGraph-powered interview state machine — five nodes, a checkpointer backed by NeonDB, and three FastAPI endpoints (`/interview/start`, `/interview/turn`, `/interview/state/{session_id}`) that drive a full AI mock interview session.
+
+**Architecture:** Each interview is a LangGraph graph compiled with an `AsyncPostgresSaver` checkpointer (stored in NeonDB's `checkpointer` schema). The graph is compiled once at app startup and reused across requests. Each session maps to one LangGraph thread identified by `session_id`. LLM calls go to OpenRouter (MiniMax model) via httpx. All prompt builders are pure functions so they can be unit-tested independently of the LLM.
+
+**Tech Stack:** LangGraph 0.2.50, langgraph-checkpoint-postgres 2.0.8, httpx 0.27.2, FastAPI 0.115.0, asyncpg 0.29.0, Python 3.11
+
+---
+
+## File Map
+
+### Backend — Create
+- `backend/graph/__init__.py` — empty package marker
+- `backend/graph/state.py` — `InterviewState` TypedDict with `add_messages`
+- `backend/llm.py` — `call_llm(messages, max_tokens)` async httpx wrapper for OpenRouter
+- `backend/prompts.py` — 5 pure prompt-builder functions
+- `backend/graph/nodes.py` — 5 async node functions + `route_after_evaluation`
+- `backend/graph/graph.py` — `build_graph(checkpointer)` → compiled LangGraph
+- `backend/checkpointer.py` — `init_checkpointer()` / `get_checkpointer()` lifecycle helpers
+- `backend/routers/interview.py` — `/interview/start`, `/interview/turn`, `/interview/state/{session_id}`
+
+### Backend — Modify
+- `backend/db/queries.py` — add 5 session query functions
+- `backend/main.py` — init checkpointer + graph in lifespan, register interview router
+
+### Tests — Create
+- `tests/test_prompts.py` — unit tests for all 5 prompt builders
+- `tests/test_routing.py` — unit tests for `route_after_evaluation`
+
+---
+
+## Task 1: Session DB queries
+
+**Files:**
+- Modify: `backend/db/queries.py`
+
+- [ ] **Step 1: Append session query functions to backend/db/queries.py**
+
+Read the file first, then append to the bottom:
+
+```python
+import json as _json
+
+
+async def get_questions_by_topic(topic_id: str) -> list[asyncpg.Record]:
+    async with get_pool().acquire() as conn:
+        return await conn.fetch(
+            "SELECT * FROM questions WHERE topic_id = $1 ORDER BY created_at ASC",
+            topic_id,
+        )
+
+
+async def get_best_session_by_student_topic(
+    student_id: str, topic_id: str
+) -> Optional[asyncpg.Record]:
+    async with get_pool().acquire() as conn:
+        return await conn.fetchrow(
+            """
+            SELECT * FROM interview_sessions
+            WHERE student_id = $1 AND topic_id = $2 AND status = 'completed'
+            ORDER BY score DESC NULLS LAST
+            LIMIT 1
+            """,
+            student_id, topic_id,
+        )
+
+
+async def create_interview_session(
+    student_id: str, topic_id: str
+) -> asyncpg.Record:
+    async with get_pool().acquire() as conn:
+        return await conn.fetchrow(
+            """
+            INSERT INTO interview_sessions (student_id, topic_id)
+            VALUES ($1, $2)
+            RETURNING *
+            """,
+            student_id, topic_id,
+        )
+
+
+async def update_session_complete(
+    session_id: str, score: int, feedback: dict
+) -> None:
+    async with get_pool().acquire() as conn:
+        await conn.execute(
+            """
+            UPDATE interview_sessions
+            SET status = 'completed', score = $1, feedback = $2::jsonb,
+                completed_at = NOW()
+            WHERE id = $3
+            """,
+            score, _json.dumps(feedback), session_id,
+        )
+
+
+async def get_session_by_id(session_id: str) -> Optional[asyncpg.Record]:
+    async with get_pool().acquire() as conn:
+        return await conn.fetchrow(
+            "SELECT * FROM interview_sessions WHERE id = $1", session_id
+        )
+```
+
+- [ ] **Step 2: Verify import**
+
+```bash
+uv run python -c "from backend.db import queries; print('OK')"
+```
+
+Expected: `OK`
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add backend/db/queries.py
+git commit -m "feat: add session DB queries (create, complete, get, past best)"
+```
+
+---
+
+## Task 2: InterviewState + LLM client
+
+**Files:**
+- Create: `backend/graph/__init__.py`
+- Create: `backend/graph/state.py`
+- Create: `backend/llm.py`
+
+- [ ] **Step 1: Create backend/graph/__init__.py** (empty)
+
+- [ ] **Step 2: Create backend/graph/state.py**
+
+```python
+from typing import Annotated, Literal, TypedDict
+
+from langgraph.graph.message import add_messages
+
+
+class InterviewState(TypedDict):
+    # Static — set once at session start
+    topic_name: str
+    session_id: str
+    student_id: str
+    questions_remaining: list[dict]        # [{"question_text": str, "difficulty": str}]
+    past_best_score: int | None
+    past_weak_areas: list[str]
+
+    # Dynamic — mutates during session
+    messages: Annotated[list, add_messages]  # appended via reducer
+    conversation_summary: str
+    questions_asked: list[str]
+    student_weak_areas: list[str]
+    turn_count: int
+    awaiting_counter_response: bool
+    last_verdict: str | None               # "strong" | "shallow" | "wrong" | None
+
+    # Terminal — set once at end
+    status: Literal["active", "complete"]
+    score: int | None
+    feedback: dict | None
+```
+
+- [ ] **Step 3: Create backend/llm.py**
+
+```python
+import os
+
+import httpx
+
+_OPENROUTER_URL = "https://openrouter.ai/api/v1/chat/completions"
+_MODEL = "minimax/minimax-01"
+
+
+async def call_llm(messages: list[dict], max_tokens: int = 512) -> str:
+    """Call OpenRouter API. Returns the assistant message content string."""
+    api_key = os.getenv("OPENROUTER_API_KEY", "")
+    async with httpx.AsyncClient(timeout=60.0) as client:
+        response = await client.post(
+            _OPENROUTER_URL,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+            },
+            json={
+                "model": _MODEL,
+                "messages": messages,
+                "max_tokens": max_tokens,
+            },
+        )
+        response.raise_for_status()
+        return response.json()["choices"][0]["message"]["content"]
+```
+
+- [ ] **Step 4: Verify imports**
+
+```bash
+uv run python -c "
+from backend.graph.state import InterviewState
+from backend.llm import call_llm
+print('OK')
+"
+```
+
+Expected: `OK`
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add backend/graph/__init__.py backend/graph/state.py backend/llm.py
+git commit -m "feat: InterviewState TypedDict and OpenRouter LLM client"
+```
+
+---
+
+## Task 3: Prompt builders + tests
+
+**Files:**
+- Create: `backend/prompts.py`
+- Create: `tests/test_prompts.py`
+
+- [ ] **Step 1: Write failing tests first**
+
+Create `tests/test_prompts.py`:
+
+```python
+from backend.prompts import (
+    build_ask_question_prompt,
+    build_counter_prompt,
+    build_evaluate_prompt,
+    build_report_prompt,
+    build_summarize_prompt,
+)
+
+
+def _is_message_list(result) -> bool:
+    return (
+        isinstance(result, list)
+        and all(isinstance(m, dict) and "role" in m and "content" in m for m in result)
+    )
+
+
+def test_ask_question_prompt_returns_messages():
+    result = build_ask_question_prompt("Python", "Some summary", ["What is a list?"])
+    assert _is_message_list(result)
+    assert len(result) == 2
+    combined = " ".join(m["content"] for m in result)
+    assert "Python" in combined
+    assert "Some summary" in combined
+    assert "What is a list?" in combined
+
+
+def test_ask_question_prompt_no_prior_questions():
+    result = build_ask_question_prompt("Python", "", [])
+    assert _is_message_list(result)
+    combined = " ".join(m["content"] for m in result)
+    assert "Python" in combined
+
+
+def test_evaluate_prompt_returns_messages():
+    result = build_evaluate_prompt("What is GIL?", "Global Interpreter Lock", "summary")
+    assert _is_message_list(result)
+    combined = " ".join(m["content"] for m in result)
+    assert "What is GIL?" in combined
+    assert "Global Interpreter Lock" in combined
+    # Must instruct JSON output
+    assert "JSON" in combined or "json" in combined
+
+
+def test_counter_prompt_returns_messages():
+    result = build_counter_prompt("What is GIL?", "I don't know")
+    assert _is_message_list(result)
+    assert len(result) == 2
+    combined = " ".join(m["content"] for m in result)
+    assert "What is GIL?" in combined
+
+
+def test_summarize_prompt_returns_messages():
+    messages = [
+        {"role": "assistant", "content": "What is a decorator?"},
+        {"role": "human", "content": "It wraps a function"},
+    ]
+    result = build_summarize_prompt(messages)
+    assert _is_message_list(result)
+    combined = " ".join(m["content"] for m in result)
+    assert "decorator" in combined
+
+
+def test_report_prompt_includes_past_score():
+    result = build_report_prompt("Python", ["Q1", "Q2"], ["decorators"], "summary", 72)
+    assert _is_message_list(result)
+    combined = " ".join(m["content"] for m in result)
+    assert "72" in combined
+    assert "JSON" in combined or "json" in combined
+
+
+def test_report_prompt_no_past_score():
+    result = build_report_prompt("Python", [], [], "", None)
+    assert _is_message_list(result)
+    combined = " ".join(m["content"] for m in result)
+    assert "first attempt" in combined.lower() or "no previous" in combined.lower() or "first" in combined.lower()
+```
+
+- [ ] **Step 2: Run tests — expect failure**
+
+```bash
+uv run pytest tests/test_prompts.py -v
+```
+
+Expected: `FAILED` — `ModuleNotFoundError`
+
+- [ ] **Step 3: Implement backend/prompts.py**
+
+```python
+def build_ask_question_prompt(
+    topic: str, summary: str, asked: list[str]
+) -> list[dict]:
+    asked_str = "\n".join(f"- {q}" for q in asked) if asked else "None yet."
+    system = (
+        f"You are a technical interview AI conducting a mock interview on: {topic}. "
+        "Ask one clear, focused technical question. "
+        "Do not repeat questions already asked. Be conversational but professional."
+    )
+    user = (
+        f"Conversation summary:\n{summary or 'This is the start of the interview.'}\n\n"
+        f"Questions already asked:\n{asked_str}\n\n"
+        "Ask the next question. Just the question — no numbering, no preamble."
+    )
+    return [{"role": "system", "content": system}, {"role": "user", "content": user}]
+
+
+def build_evaluate_prompt(
+    question: str, answer: str, summary: str
+) -> list[dict]:
+    system = (
+        "You are evaluating a student's answer in a technical interview. "
+        'Respond with ONLY valid JSON: {"verdict": "strong"|"shallow"|"wrong", "weak_area": "topic or null"}\n'
+        "strong = correct and complete. shallow = partially correct, missing depth. "
+        "wrong = incorrect or off-topic."
+    )
+    user = (
+        f"Context: {summary or 'Start of interview.'}\n\n"
+        f"Question: {question}\n"
+        f"Student answer: {answer}\n\n"
+        "Evaluate. Return only the JSON object."
+    )
+    return [{"role": "system", "content": system}, {"role": "user", "content": user}]
+
+
+def build_counter_prompt(question: str, answer: str) -> list[dict]:
+    system = (
+        "You are a technical interviewer. The student gave a shallow answer. "
+        "Ask ONE specific follow-up probing question to dig deeper into what they missed. "
+        "No preamble — just the question."
+    )
+    user = (
+        f"Original question: {question}\n"
+        f"Student's shallow answer: {answer}\n\n"
+        "Ask one targeted follow-up question."
+    )
+    return [{"role": "system", "content": system}, {"role": "user", "content": user}]
+
+
+def build_summarize_prompt(messages: list) -> list[dict]:
+    def _content(m) -> str:
+        return m.get("content", "") if isinstance(m, dict) else getattr(m, "content", "")
+
+    def _role(m) -> str:
+        if isinstance(m, dict):
+            return m.get("role", "unknown")
+        name = type(m).__name__.lower()
+        return "AI" if "ai" in name else "STUDENT"
+
+    transcript = "\n".join(f"{_role(m).upper()}: {_content(m)}" for m in messages)
+    system = (
+        "Summarize this interview transcript in under 150 words. "
+        "Cover: topics discussed, student strengths, weak areas identified."
+    )
+    return [
+        {"role": "system", "content": system},
+        {"role": "user", "content": f"Transcript:\n{transcript}\n\nSummarize:"},
+    ]
+
+
+def build_report_prompt(
+    topic: str,
+    asked: list[str],
+    weak_areas: list[str],
+    summary: str,
+    past_score: int | None,
+) -> list[dict]:
+    past_ctx = (
+        f"Their previous best score on this topic was {past_score}/100."
+        if past_score is not None
+        else "This is their first attempt on this topic."
+    )
+    system = (
+        "Generate a final interview performance report. "
+        "Respond with ONLY valid JSON:\n"
+        '{"score": 0-100, "summary": "string", "concept_score": 0-100, '
+        '"depth_score": 0-100, "mistakes": ["string"], "tips": ["string"]}'
+    )
+    user = (
+        f"Topic: {topic}\n"
+        f"{past_ctx}\n"
+        f"Questions covered: {', '.join(asked) if asked else 'none'}\n"
+        f"Weak areas: {', '.join(weak_areas) if weak_areas else 'none'}\n\n"
+        f"Interview summary:\n{summary or 'No summary available.'}\n\n"
+        "Generate the report JSON."
+    )
+    return [{"role": "system", "content": system}, {"role": "user", "content": user}]
+```
+
+- [ ] **Step 4: Run tests — expect all pass**
+
+```bash
+uv run pytest tests/test_prompts.py -v
+```
+
+Expected: `7 passed`
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add backend/prompts.py tests/test_prompts.py
+git commit -m "feat: prompt builders for all 5 LangGraph nodes with unit tests"
+```
+
+---
+
+## Task 4: Graph nodes + routing tests
+
+**Files:**
+- Create: `backend/graph/nodes.py`
+- Create: `tests/test_routing.py`
+
+- [ ] **Step 1: Write routing tests first**
+
+Create `tests/test_routing.py`:
+
+```python
+"""Unit tests for route_after_evaluation — no LLM, no DB needed."""
+from backend.graph.nodes import route_after_evaluation
+
+
+def _state(**overrides) -> dict:
+    """Build a minimal InterviewState dict for routing tests."""
+    base = {
+        "last_verdict": "strong",
+        "turn_count": 1,
+        "questions_remaining": [{"question_text": "Q2", "difficulty": "easy"}],
+        "awaiting_counter_response": False,
+    }
+    base.update(overrides)
+    return base
+
+
+def test_shallow_not_in_counter_loop_routes_to_counter():
+    state = _state(last_verdict="shallow", awaiting_counter_response=False)
+    assert route_after_evaluation(state) == "counter"
+
+
+def test_shallow_already_in_counter_loop_routes_to_next_question():
+    state = _state(last_verdict="shallow", awaiting_counter_response=True, turn_count=2)
+    assert route_after_evaluation(state) == "next_question"
+
+
+def test_strong_routes_to_next_question():
+    state = _state(last_verdict="strong", turn_count=1)
+    assert route_after_evaluation(state) == "next_question"
+
+
+def test_wrong_routes_to_next_question():
+    state = _state(last_verdict="wrong", turn_count=1)
+    assert route_after_evaluation(state) == "next_question"
+
+
+def test_turn_count_8_routes_to_end():
+    state = _state(last_verdict="strong", turn_count=8)
+    assert route_after_evaluation(state) == "end"
+
+
+def test_no_questions_remaining_routes_to_end():
+    state = _state(last_verdict="strong", turn_count=3, questions_remaining=[])
+    assert route_after_evaluation(state) == "end"
+
+
+def test_every_4_turns_routes_to_summarize():
+    state = _state(last_verdict="strong", turn_count=4)
+    assert route_after_evaluation(state) == "summarize"
+
+
+def test_turn_8_beats_summarize():
+    # turn_count=8 should end, not summarize (end takes priority)
+    state = _state(last_verdict="strong", turn_count=8)
+    assert route_after_evaluation(state) == "end"
+```
+
+- [ ] **Step 2: Run routing tests — expect failure**
+
+```bash
+uv run pytest tests/test_routing.py -v
+```
+
+Expected: `FAILED` — `ModuleNotFoundError`
+
+- [ ] **Step 3: Implement backend/graph/nodes.py**
+
+```python
+import json
+
+from backend.graph.state import InterviewState
+from backend.llm import call_llm
+from backend.prompts import (
+    build_ask_question_prompt,
+    build_counter_prompt,
+    build_evaluate_prompt,
+    build_report_prompt,
+    build_summarize_prompt,
+)
+from backend.db import queries
+
+
+def _msg_content(msg) -> str:
+    return msg.get("content", "") if isinstance(msg, dict) else getattr(msg, "content", "")
+
+
+def _msg_role(msg) -> str:
+    if isinstance(msg, dict):
+        return msg.get("role", "")
+    name = type(msg).__name__.lower()
+    if "human" in name:
+        return "human"
+    return "assistant"
+
+
+async def ask_question(state: InterviewState) -> dict:
+    remaining = list(state["questions_remaining"])
+    if not remaining:
+        return {}
+
+    question = remaining.pop(0)
+    prompt = build_ask_question_prompt(
+        state["topic_name"],
+        state["conversation_summary"],
+        state["questions_asked"],
+    )
+    response = await call_llm(prompt, max_tokens=200)
+
+    return {
+        "questions_remaining": remaining,
+        "questions_asked": state["questions_asked"] + [question["question_text"]],
+        "messages": [{"role": "assistant", "content": response}],
+        "turn_count": state["turn_count"] + 1,
+        "awaiting_counter_response": False,
+    }
+
+
+async def evaluate_answer(state: InterviewState) -> dict:
+    last_student = next(
+        (m for m in reversed(state["messages"]) if _msg_role(m) == "human"),
+        None,
+    )
+    if not last_student:
+        return {"last_verdict": "wrong"}
+
+    last_question = state["questions_asked"][-1] if state["questions_asked"] else ""
+    prompt = build_evaluate_prompt(
+        last_question,
+        _msg_content(last_student),
+        state["conversation_summary"],
+    )
+    raw = await call_llm(prompt, max_tokens=100)
+
+    try:
+        result = json.loads(raw)
+        verdict = result.get("verdict", "wrong")
+        weak_area = result.get("weak_area")
+    except (json.JSONDecodeError, AttributeError):
+        verdict = "wrong"
+        weak_area = None
+
+    weak_areas = list(state["student_weak_areas"])
+    if verdict == "shallow" and weak_area:
+        weak_areas.append(str(weak_area))
+
+    return {
+        "last_verdict": verdict,
+        "student_weak_areas": weak_areas,
+    }
+
+
+async def counter_question(state: InterviewState) -> dict:
+    last_student = next(
+        (m for m in reversed(state["messages"]) if _msg_role(m) == "human"),
+        None,
+    )
+    last_question = state["questions_asked"][-1] if state["questions_asked"] else ""
+    prompt = build_counter_prompt(
+        last_question,
+        _msg_content(last_student) if last_student else "",
+    )
+    response = await call_llm(prompt, max_tokens=150)
+
+    return {
+        "messages": [{"role": "assistant", "content": response}],
+        "awaiting_counter_response": True,
+        "turn_count": state["turn_count"] + 1,
+    }
+
+
+async def summarize(state: InterviewState) -> dict:
+    prompt = build_summarize_prompt(state["messages"])
+    summary = await call_llm(prompt, max_tokens=200)
+
+    return {
+        "conversation_summary": summary,
+        "messages": [],
+        "awaiting_counter_response": False,
+    }
+
+
+async def generate_report(state: InterviewState) -> dict:
+    prompt = build_report_prompt(
+        state["topic_name"],
+        state["questions_asked"],
+        state["student_weak_areas"],
+        state["conversation_summary"],
+        state["past_best_score"],
+    )
+    raw = await call_llm(prompt, max_tokens=400)
+
+    try:
+        feedback = json.loads(raw)
+        score = int(feedback.get("score", 0))
+    except (json.JSONDecodeError, ValueError, TypeError):
+        feedback = {
+            "score": 0,
+            "summary": raw,
+            "concept_score": 0,
+            "depth_score": 0,
+            "mistakes": [],
+            "tips": [],
+        }
+        score = 0
+
+    await queries.update_session_complete(state["session_id"], score, feedback)
+
+    return {
+        "status": "complete",
+        "score": score,
+        "feedback": feedback,
+        "messages": [{"role": "assistant", "content": feedback.get("summary", "Interview complete.")}],
+    }
+
+
+def route_after_evaluation(state: InterviewState) -> str:
+    """Routing function for conditional edges after evaluate_answer."""
+    verdict = state.get("last_verdict", "wrong")
+    turn_count = state["turn_count"]
+    questions_remaining = state["questions_remaining"]
+    awaiting_counter = state["awaiting_counter_response"]
+
+    # Shallow + not already in counter loop → fire counter question
+    if verdict == "shallow" and not awaiting_counter:
+        return "counter"
+
+    # End conditions (checked before summarize to avoid wasted LLM call)
+    if turn_count >= 8 or not questions_remaining:
+        return "end"
+
+    # Compress memory every 4 turns
+    if turn_count % 4 == 0 and turn_count > 0:
+        return "summarize"
+
+    return "next_question"
+```
+
+- [ ] **Step 4: Run routing tests — expect all pass**
+
+```bash
+uv run pytest tests/test_routing.py -v
+```
+
+Expected: `8 passed`
+
+- [ ] **Step 5: Run full test suite**
+
+```bash
+uv run pytest tests/ -v
+```
+
+Expected: `32 passed` (17 existing + 7 prompts + 8 routing)
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add backend/graph/nodes.py tests/test_routing.py
+git commit -m "feat: LangGraph nodes (ask, evaluate, counter, summarize, report) + routing tests"
+```
+
+---
+
+## Task 5: Graph builder + checkpointer
+
+**Files:**
+- Create: `backend/graph/graph.py`
+- Create: `backend/checkpointer.py`
+
+- [ ] **Step 1: Create backend/graph/graph.py**
+
+```python
+from langgraph.graph import END, StateGraph
+
+from backend.graph.nodes import (
+    ask_question,
+    counter_question,
+    evaluate_answer,
+    generate_report,
+    route_after_evaluation,
+    summarize,
+)
+from backend.graph.state import InterviewState
+
+
+def build_graph(checkpointer):
+    """Compile the interview graph with the given checkpointer. Call once at startup."""
+    builder = StateGraph(InterviewState)
+
+    builder.add_node("ask_question", ask_question)
+    builder.add_node("evaluate_answer", evaluate_answer)
+    builder.add_node("counter_question", counter_question)
+    builder.add_node("summarize", summarize)
+    builder.add_node("generate_report", generate_report)
+
+    builder.set_entry_point("ask_question")
+
+    builder.add_edge("ask_question", "evaluate_answer")
+
+    builder.add_conditional_edges(
+        "evaluate_answer",
+        route_after_evaluation,
+        {
+            "counter": "counter_question",
+            "next_question": "ask_question",
+            "summarize": "summarize",
+            "end": "generate_report",
+        },
+    )
+
+    builder.add_edge("counter_question", "evaluate_answer")
+    builder.add_edge("summarize", "ask_question")
+    builder.add_edge("generate_report", END)
+
+    return builder.compile(checkpointer=checkpointer)
+```
+
+- [ ] **Step 2: Create backend/checkpointer.py**
+
+```python
+import os
+
+from langgraph.checkpoint.postgres.aio import AsyncPostgresSaver
+
+_checkpointer: AsyncPostgresSaver | None = None
+
+
+async def init_checkpointer() -> AsyncPostgresSaver:
+    """
+    Initialize the AsyncPostgresSaver and run setup() to create the
+    checkpointer schema + tables in NeonDB. Call once at app startup.
+    """
+    global _checkpointer
+    conn_string = os.getenv("NEON_DB_URL", "")
+
+    # langgraph-checkpoint-postgres 2.x: from_conn_string is an async context manager.
+    # We enter it at startup and keep it open for the app lifetime.
+    cm = AsyncPostgresSaver.from_conn_string(conn_string)
+    _checkpointer = await cm.__aenter__()
+    await _checkpointer.setup()
+    return _checkpointer
+
+
+def get_checkpointer() -> AsyncPostgresSaver:
+    if _checkpointer is None:
+        raise RuntimeError("Checkpointer not initialized — call init_checkpointer() first")
+    return _checkpointer
+```
+
+- [ ] **Step 3: Verify imports compile**
+
+```bash
+uv run python -c "
+from backend.graph.graph import build_graph
+from backend.checkpointer import init_checkpointer, get_checkpointer
+print('OK')
+"
+```
+
+Expected: `OK`
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add backend/graph/graph.py backend/checkpointer.py
+git commit -m "feat: LangGraph graph builder and AsyncPostgresSaver checkpointer"
+```
+
+---
+
+## Task 6: Update main.py
+
+**Files:**
+- Modify: `backend/main.py`
+
+- [ ] **Step 1: Replace backend/main.py**
+
+```python
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+
+from backend.checkpointer import init_checkpointer
+from backend.db.connection import init_db_pool
+from backend.graph.graph import build_graph
+from backend.routers import auth, batches, interview, topics, upload
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Startup
+    await init_db_pool()
+    checkpointer = await init_checkpointer()
+    app.state.graph = build_graph(checkpointer)
+    yield
+    # Shutdown — nothing to clean up (pool managed by asyncpg)
+
+
+app = FastAPI(lifespan=lifespan)
+
+app.include_router(auth.router,      prefix="/api/auth")
+app.include_router(batches.router,   prefix="/api/batches")
+app.include_router(topics.router,    prefix="/api/topics")
+app.include_router(upload.router,    prefix="/api/upload")
+app.include_router(interview.router, prefix="/interview")
+
+# React static build — MUST be last
+# app.mount("/", StaticFiles(directory="frontend/dist", html=True), name="static")
+```
+
+- [ ] **Step 2: Verify — but DON'T start the server yet (interview router doesn't exist yet)**
+
+```bash
+uv run python -c "
+# Just verify imports, not the full app startup
+from backend.graph.graph import build_graph
+from backend.checkpointer import init_checkpointer, get_checkpointer
+from backend.routers import auth, batches, topics, upload
+print('OK')
+"
+```
+
+Expected: `OK`
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add backend/main.py
+git commit -m "feat: wire checkpointer + graph into FastAPI lifespan, register interview router"
+```
+
+---
+
+## Task 7: Interview router
+
+**Files:**
+- Create: `backend/routers/interview.py`
+
+- [ ] **Step 1: Create backend/routers/interview.py**
+
+```python
+from fastapi import APIRouter, Depends, HTTPException, Request
+from pydantic import BaseModel
+
+from backend.auth.deps import require_student
+from backend.db import queries
+
+router = APIRouter()
+
+
+class StartRequest(BaseModel):
+    topic_id: str
+
+
+class TurnRequest(BaseModel):
+    session_id: str
+    student_message: str
+
+
+def _last_ai_message(messages: list) -> str:
+    """Extract content of the last assistant message from a list."""
+    for m in reversed(messages):
+        role = m.get("role", "") if isinstance(m, dict) else getattr(type(m), "__name__", "").lower()
+        content = m.get("content", "") if isinstance(m, dict) else getattr(m, "content", "")
+        if role == "assistant" or "ai" in str(role).lower():
+            return content
+    return ""
+
+
+@router.post("/start")
+async def start_interview(
+    body: StartRequest,
+    request: Request,
+    user: dict = Depends(require_student),
+):
+    topic = await queries.get_topic_by_id(body.topic_id)
+    if not topic:
+        raise HTTPException(404, "Topic not found")
+    if not topic["is_unlocked"]:
+        raise HTTPException(403, "Topic is not unlocked for interviews")
+
+    questions = await queries.get_questions_by_topic(body.topic_id)
+    if not questions:
+        raise HTTPException(400, "No questions available for this topic")
+
+    past = await queries.get_best_session_by_student_topic(user["user_id"], body.topic_id)
+    past_best_score = past["score"] if past else None
+    past_weak_areas: list[str] = []
+    if past and past["feedback"]:
+        import json
+        fb = past["feedback"] if isinstance(past["feedback"], dict) else json.loads(past["feedback"])
+        past_weak_areas = fb.get("tips", [])
+
+    session = await queries.create_interview_session(user["user_id"], body.topic_id)
+    session_id = str(session["id"])
+
+    initial_state = {
+        "topic_name": topic["name"],
+        "session_id": session_id,
+        "student_id": user["user_id"],
+        "questions_remaining": [
+            {"question_text": q["question_text"], "difficulty": q["difficulty"]}
+            for q in questions
+        ],
+        "past_best_score": past_best_score,
+        "past_weak_areas": past_weak_areas,
+        "messages": [],
+        "conversation_summary": "",
+        "questions_asked": [],
+        "student_weak_areas": [],
+        "turn_count": 0,
+        "awaiting_counter_response": False,
+        "last_verdict": None,
+        "status": "active",
+        "score": None,
+        "feedback": None,
+    }
+
+    graph = request.app.state.graph
+    config = {"configurable": {"thread_id": session_id}}
+    result = await graph.ainvoke(initial_state, config)
+
+    return {
+        "session_id": session_id,
+        "message": _last_ai_message(result["messages"]),
+    }
+
+
+@router.post("/turn")
+async def interview_turn(
+    body: TurnRequest,
+    request: Request,
+    user: dict = Depends(require_student),
+):
+    session = await queries.get_session_by_id(body.session_id)
+    if not session:
+        raise HTTPException(404, "Session not found")
+    if session["status"] == "completed":
+        raise HTTPException(400, "Session is already complete")
+
+    graph = request.app.state.graph
+    config = {"configurable": {"thread_id": body.session_id}}
+
+    result = await graph.ainvoke(
+        {"messages": [{"role": "human", "content": body.student_message}]},
+        config,
+    )
+
+    is_complete = result.get("status") == "complete"
+    response: dict = {
+        "message": _last_ai_message(result["messages"]),
+        "is_counter_q": result.get("awaiting_counter_response", False),
+        "is_complete": is_complete,
+    }
+    if is_complete:
+        response["feedback"] = result.get("feedback")
+
+    return response
+
+
+@router.get("/state/{session_id}")
+async def get_interview_state(
+    session_id: str,
+    request: Request,
+    user: dict = Depends(require_student),
+):
+    from backend.checkpointer import get_checkpointer
+
+    checkpointer = get_checkpointer()
+    config = {"configurable": {"thread_id": session_id}}
+    checkpoint = await checkpointer.aget(config)
+
+    if not checkpoint:
+        raise HTTPException(404, "Session state not found")
+
+    channel_values = checkpoint.get("channel_values", {})
+    messages = channel_values.get("messages", [])
+
+    last_msg = _last_ai_message(messages) if messages else None
+
+    return {
+        "status": channel_values.get("status", "active"),
+        "turn_count": channel_values.get("turn_count", 0),
+        "last_message": last_msg,
+    }
+```
+
+- [ ] **Step 2: Verify the full app imports cleanly (all routers now exist)**
+
+```bash
+uv run python -c "from backend.main import app; print('OK')"
+```
+
+Expected: `OK` (plus JWT warning — fine)
+
+- [ ] **Step 3: Run all tests**
+
+```bash
+uv run pytest tests/ -v
+```
+
+Expected: `32 passed`
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add backend/routers/interview.py
+git commit -m "feat: interview router — start, turn, state endpoints"
+```
+
+---
+
+## Task 8: Final verification + push
+
+- [ ] **Step 1: Run all tests**
+
+```bash
+uv run pytest tests/ -v
+```
+
+Expected: `32 passed`
+
+- [ ] **Step 2: Verify all routes registered**
+
+```bash
+uv run python -c "
+from backend.main import app
+routes = [(r.path, list(r.methods)) for r in app.routes if hasattr(r, 'methods')]
+for path, methods in sorted(routes):
+    print(methods, path)
+"
+```
+
+Expected output must include:
+```
+['POST'] /interview/start
+['POST'] /interview/turn
+['GET'] /interview/state/{session_id}
+```
+
+- [ ] **Step 3: Smoke test backend import**
+
+```bash
+uv run python -c "from backend.main import app; print('OK')"
+```
+
+Expected: `OK`
+
+- [ ] **Step 4: Verify frontend build still passes (no regressions)**
+
+```bash
+cd frontend && npm run build && cd ..
+```
+
+Expected: clean build
+
+- [ ] **Step 5: Push to GitHub**
+
+```bash
+git push origin main
+```
+
+---
+
+## Self-Review
+
+**Spec coverage:**
+- ✅ `InterviewState` TypedDict with all fields including `add_messages` (Task 2)
+- ✅ `call_llm` async OpenRouter wrapper (Task 2)
+- ✅ `build_ask_question_prompt` (Task 3)
+- ✅ `build_evaluate_prompt` — returns JSON verdict (Task 3)
+- ✅ `build_counter_prompt` (Task 3)
+- ✅ `build_summarize_prompt` (Task 3)
+- ✅ `build_report_prompt` with past_score context (Task 3)
+- ✅ `ask_question` node — pops from remaining, adds to asked (Task 4)
+- ✅ `evaluate_answer` node — sets last_verdict + grows weak_areas (Task 4)
+- ✅ `counter_question` node — sets awaiting_counter_response=True (Task 4)
+- ✅ `summarize` node — compresses, clears messages (Task 4)
+- ✅ `generate_report` node — writes to DB, sets status=complete (Task 4)
+- ✅ `route_after_evaluation` — all 4 routes: counter/next_question/summarize/end (Task 4)
+- ✅ Graph wired: entry=ask_question, conditional from evaluate_answer, all edges (Task 5)
+- ✅ `AsyncPostgresSaver` with `setup()` call (Task 5)
+- ✅ Graph compiled once at startup, stored in `app.state.graph` (Task 6)
+- ✅ `POST /interview/start` — unlocked check, create session, init state, ainvoke (Task 7)
+- ✅ `POST /interview/turn` — append human message, ainvoke, return AI response (Task 7)
+- ✅ `GET /interview/state/{session_id}` — load checkpoint, return status+turn+last_msg (Task 7)
+- ✅ Thread ID = session_id (Tasks 5, 7)
+- ✅ Session DB queries: get_questions, get_best_past, create_session, update_complete, get_by_id (Task 1)
+
+**Type consistency:**
+- `route_after_evaluation` returns `"counter"` | `"next_question"` | `"summarize"` | `"end"` — matches graph edge keys ✅
+- `InterviewState.last_verdict` set in `evaluate_answer`, read in `route_after_evaluation` ✅
+- `InterviewState.messages` uses `add_messages` reducer — nodes return list, graph appends ✅
+- `update_session_complete(session_id, score, feedback)` called in `generate_report` — signature matches Task 1 ✅

pyproject.toml

@@ -17,3 +17,8 @@ dependencies = [
     "python-multipart==0.0.9",
     "uvicorn==0.30.6",
 ]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+]

uv.lock

@@ -24,6 +24,11 @@ dependencies = [
     { name = "uvicorn" },
 ]
 
+[package.dev-dependencies]
+dev = [
+    { name = "pytest" },
+]
+
 [package.metadata]
 requires-dist = [
     { name = "asyncpg", specifier = "==0.29.0" },
@@ -39,6 +44,9 @@ requires-dist = [
     { name = "uvicorn", specifier = "==0.30.6" },
 ]
 
+[package.metadata.requires-dev]
+dev = [{ name = "pytest", specifier = ">=9.0.2" }]
+
 [[package]]
 name = "annotated-types"
 version = "0.7.0"
@@ -448,6 +456,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/0e/61/66938bbb5fc52dbdf84594873d5b51fb1f7c7794e9c0f5bd885f30bc507b/idna-3.11-py3-none-any.whl", hash = "sha256:771a87f49d9defaf64091e6e6fe9c18d4833f140bd19464795bc32d966ca37ea", size = 71008, upload-time = "2025-10-12T14:55:18.883Z" },
 ]
 
+[[package]]
+name = "iniconfig"
+version = "2.3.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/72/34/14ca021ce8e5dfedc35312d08ba8bf51fdd999c576889fc2c24cb97f4f10/iniconfig-2.3.0.tar.gz", hash = "sha256:c76315c77db068650d49c5b56314774a7804df16fee4402c1f19d6d15d8c4730", size = 20503, upload-time = "2025-10-18T21:55:43.219Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/cb/b1/3846dd7f199d53cb17f49cba7e651e9ce294d8497c8c150530ed11865bb8/iniconfig-2.3.0-py3-none-any.whl", hash = "sha256:f631c04d2c48c52b84d0d0549c99ff3859c98df65b3101406327ecc7d53fbf12", size = 7484, upload-time = "2025-10-18T21:55:41.639Z" },
+]
+
 [[package]]
 name = "jsonpatch"
 version = "1.33"
@@ -688,6 +705,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/20/12/38679034af332785aac8774540895e234f4d07f7545804097de4b666afd8/packaging-25.0-py3-none-any.whl", hash = "sha256:29572ef2b1f17581046b3a2227d5c611fb25ec70ca1ba8554b24b0e69331a484", size = 66469, upload-time = "2025-04-19T11:48:57.875Z" },
 ]
 
+[[package]]
+name = "pluggy"
+version = "1.6.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/f9/e2/3e91f31a7d2b083fe6ef3fa267035b518369d9511ffab804f839851d2779/pluggy-1.6.0.tar.gz", hash = "sha256:7dcc130b76258d33b90f61b658791dede3486c3e6bfb003ee5c9bfb396dd22f3", size = 69412, upload-time = "2025-05-15T12:30:07.975Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/54/20/4d324d65cc6d9205fabedc306948156824eb9f0ee1633355a8f7ec5c66bf/pluggy-1.6.0-py3-none-any.whl", hash = "sha256:e920276dd6813095e9377c0bc5566d94c932c33b27a3e3945d8389c374dd4746", size = 20538, upload-time = "2025-05-15T12:30:06.134Z" },
+]
+
 [[package]]
 name = "psycopg"
 version = "3.3.3"
@@ -792,6 +818,31 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/13/63/b95781763e8d84207025071c0cec16d921c0163c7a9033ae4b9a0e020dc7/pydantic_core-2.20.1-cp313-none-win_amd64.whl", hash = "sha256:65db0f2eefcaad1a3950f498aabb4875c8890438bc80b19362cf633b87a8ab20", size = 1898013, upload-time = "2024-07-03T17:02:15.157Z" },
 ]
 
+[[package]]
+name = "pygments"
+version = "2.19.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/b0/77/a5b8c569bf593b0140bde72ea885a803b82086995367bf2037de0159d924/pygments-2.19.2.tar.gz", hash = "sha256:636cb2477cec7f8952536970bc533bc43743542f70392ae026374600add5b887", size = 4968631, upload-time = "2025-06-21T13:39:12.283Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/c7/21/705964c7812476f378728bdf590ca4b771ec72385c533964653c68e86bdc/pygments-2.19.2-py3-none-any.whl", hash = "sha256:86540386c03d588bb81d44bc3928634ff26449851e99741617ecb9037ee5ec0b", size = 1225217, upload-time = "2025-06-21T13:39:07.939Z" },
+]
+
+[[package]]
+name = "pytest"
+version = "9.0.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "colorama", marker = "sys_platform == 'win32'" },
+    { name = "iniconfig" },
+    { name = "packaging" },
+    { name = "pluggy" },
+    { name = "pygments" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/d1/db/7ef3487e0fb0049ddb5ce41d3a49c235bf9ad299b6a25d5780a89f19230f/pytest-9.0.2.tar.gz", hash = "sha256:75186651a92bd89611d1d9fc20f0b4345fd827c41ccd5c299a868a05d70edf11", size = 1568901, upload-time = "2025-12-06T21:30:51.014Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/3b/ab/b3226f0bd7cdcf710fbede2b3548584366da3b19b5021e74f5bde2a8fa3f/pytest-9.0.2-py3-none-any.whl", hash = "sha256:711ffd45bf766d5264d487b917733b453d917afd2b0ad65223959f59089f875b", size = 374801, upload-time = "2025-12-06T21:30:49.154Z" },
+]
+
 [[package]]
 name = "python-dotenv"
 version = "1.0.1"