pdf-quiz-generator/CLAUDE.md

PedsHub — AI Synopsis for Codebase Work

What this is

PedsHub is a pediatric question bank and reading library. Educators upload PREP exam PDFs, AI proposes MCQs and flashcards from them, a person reviews what is worth keeping, and learners sit it as sessions with an AI tutor beside them. Sign-in is through Authentik at sso.pedshub.com; the companion scribe app is at app.pedshub.com. Everything runs in Docker.

The LMS — courses, modules, lessons, enrolments — was removed. Anything in this file or the code that still mentions a course is stale; say so rather than building against it.

Critical rules

• Never restart services while a Celery task is running — check docker compose logs celery --tail=5 first
• Backend and Celery share the same code but build separate images — after changing backend code, you must docker compose build --no-cache backend celery then docker compose up -d backend celery --force-recreate
• Frontend is a Vite build inside Docker — source changes require docker compose build frontend then docker compose up -d frontend. Vite minifies function names, so grep FunctionName on the built JS won't work.
• Never import inside a function body if the same name exists at module level — Python treats it as a local variable for the entire function scope, causing UnboundLocalError before the import line executes. This was a real bug with sa_text.
• docker compose restart does NOT pick up code changes — it reuses the old image. Always build then up -d --force-recreate.
• Pydantic schemas must match DB nullability — if a column allows NULL, the schema field must be type | None. A mismatch causes 500 on serialization.
• The Question model uses source_quiz_id as the Python attribute but quiz_id as the DB column — use Question.source_quiz_id in SQLAlchemy filters, never Question.quiz_id.

Stack

• Backend: FastAPI + SQLAlchemy + PostgreSQL 16 (pgvector) + Redis + Celery
• Frontend: React 18 + Vite + React Router 6 + plain CSS + Milkdown (markdown WYSIWYG) + Nginx
• AI: LiteLLM proxy routes to Claude/GPT/Gemini/Bedrock. _proxy_model() in ai_service.py adds openai/ prefix for the proxy.
• Vectors: ChromaDB for document page chunks (RAG), pgvector for question embeddings (semantic search)
• Config: Backend reads .env via pydantic-settings. Frontend uses runtime window.__APP_CONFIG__ injected by docker-entrypoint.sh (not Vite build-time env).

Architecture

Browser → Nginx (frontend) → FastAPI (4 uvicorn workers)
                                ├── PostgreSQL (users, quizzes, questions, flashcards, attempts + pgvector embeddings)
                                ├── ChromaDB (document page chunks for extraction context)
                                ├── Redis (Celery broker, rate limits, settings, job progress, session locks)
                                └── Celery (2 fork workers: PDF processing, quiz extraction, flashcard generation, classification, embedding regeneration)
                                └── db-backup (daily PostgreSQL dumps, 14 daily / 4 weekly / 6 monthly retention, ./backups/)

## Who may do what

Three roles, and one kind of grant.

- **admin** — everything, including Settings: models, people, site policy.
- **moderator** — the whole bank: every question, article, category, card
  deck, image library, and the editorial queue. Nothing that configures the
  site.
- **user** — their own sittings, notes, starred questions and folders. No
  bank content at all unless a grant says otherwise.

Roles come from the identity provider's groups, never from this app. With
`OIDC_ROLE_CLAIM` set, `services/sso_roles.apply()` runs on every SSO sign-in
and brings the role into line with the person's groups — so removal at the
provider takes the role away here too. The two in-app role endpoints answer 409
while that mapping is on, because a role set here would be silently overwritten
at the next sign-in. The one demotion the sync refuses is the last
administrator.

`CategoryGrant` is the per-user half, given inside this app by a moderator or
admin (`/access`). It names a category branch, an image library or a folder,
and makes the holder an editor of what is inside it — which also makes the
Questions and Images menu entries appear. It never comes from a claim and is
never self-assignable.

**Nothing in the bank has an owner.** Questions, articles, categories, decks,
documents, media and shared quizzes all carry `user_id = NULL`, and every
creation path writes NULL. Authorship confers no rights anywhere: `may_edit_question`
and `can_edit_article` ask the role and the grants and nothing else. What keeps
an owner is what is genuinely one person's — attempts, notes, favourites,
collections, folders, study-plan progress, and the unshared quizzes that are
somebody's own sittings. See migration `q6a7b8c9d0e1`.

## Signing in

SSO only, through Authentik at `sso.pedshub.com`. There is no sign-up form, no
invite codes and no email sign-in codes — all three were this app doing the
provider's job, and all three were removed (migration `r7b8c9d0e1f2` drops
their tables).

- `GET /auth/sso/login` → 302 to the provider. It must stay `async` and the
  redirect must be awaited; authlib's Starlette client returns a coroutine, and
  returning it unawaited is a 500 on every click.
- `GET /auth/sso/callback` matches on the email claim, refuses an explicit
  `email_verified: false`, applies the role from groups, then parks the access
  token in Redis under a one-time code (`sso:exchange:<code>`, 60s) and
  redirects with `?code=`. The token never travels in a URL — nginx logs the
  request line, so it would be written to disk on every sign-in.
- `POST /auth/sso/exchange` spends the code once (GETDEL) and returns the token.
- `settings:sso_only` in Redis closes every password door: login, register,
  forgot/reset password, resend verification, and setting a password through
  `PUT /auth/me`. `GET /auth/signup-policy` reports it so the forms decline to
  draw themselves rather than being refused after the fact.

## Key directories

backend/app/ main.py — App startup, DDL migrations (setup_pgvector), router mounting, singleton lock config.py — All settings from .env models/ — SQLAlchemy ORM (user, quiz, question, flashcard, attempt, section, pdf_document, ...) schemas/ — Pydantic request/response models routers/ — API endpoints (auth, quizzes, questions, flashcards, attempts, admin, teach, tts, tags, ...) services/ ai_service.py — LLM calls, _proxy_model(), get_model_for_task() fallback chain extraction_modes.py — 6 quiz extraction modes + flashcard generation prompt search_service.py — Hybrid retrieval (BM25 + pgvector, RRF), rerank_ids() rerank_service.py — Cross-encoder rerank via the proxy's /v1/rerank vector_service.py — ChromaDB: store/query page chunks, LiteLLMEmbeddingFunction embedding_service.py — pgvector: embed questions for semantic search pdf_service.py — PyMuPDF: text extraction, image extraction with MD5 hash skip list tasks/ quiz_tasks.py — Celery: extract_quiz, classify_questions, regenerate_embeddings, generate_flashcard_deck pdf_tasks.py — Celery: process_pdf (text extraction + vectorization)

frontend/src/ App.jsx — Routes (public, authenticated, moderator-only) context/AuthContext.jsx — Login/logout/register, JWT token management pages/ DocumentDetailPage.jsx — Section management, "Extract Quiz" / "Create Flashcards" buttons, job progress QuestionBankPage.jsx — Browse questions, multi-category + tag filtering, TagBrowser component FlashcardsPage.jsx — Browse decks + card browser with search FlashcardStudyPage.jsx — Flip cards, got-it/review, keyboard nav, progress QuizPage.jsx — Take quiz (exam/study mode), timer, progress save to Redis AdminPage.jsx — Model config, user management, settings components/ Navbar.jsx — Auth-aware nav with jobs badge TeachChat.jsx — AI tutor drawer (lazy loaded, markdown/GFM tables) RichEditor.jsx — Milkdown markdown WYSIWYG editor with toolbar, GFM tables, math, history

## Database tables (key ones)
| Table | Purpose | Key FKs |
|-------|---------|---------|
| users | Accounts with role (admin/moderator/user) | — |
| pdf_documents | Uploaded PDFs | user_id → users |
| sections | Page ranges within a document | document_id → pdf_documents |
| quizzes | A sitting or a shared bank test. `is_shared=1` is the bank's and ownerless; `is_shared=0` is somebody's own session | section_id → sections (nullable), user_id → users (nullable) |
| questions | MCQ questions with pgvector embedding. `user_id` is always NULL — the bank has no owners | source_quiz_id → quizzes (nullable) |
| quiz_question_links | Quiz ↔ Question many-to-many | quiz_id, question_id |
| flashcard_decks | Flashcard deck metadata | section_id → sections, user_id → users |
| flashcards | Individual cards (front/back) | deck_id → flashcard_decks |
| question_tags | Tag definitions (subject/disease/keyword) | — |
| question_tag_links | Question ↔ Tag | question_id, tag_id |
| flashcard_tag_links | Flashcard ↔ Tag | flashcard_id, tag_id |
| quiz_attempts | User quiz sessions with score | quiz_id, user_id |

## Common patterns
- **Tag filtering SQL**: `WHERE tag_id = ANY(:tag_ids) GROUP BY ... HAVING COUNT(DISTINCT tag_id) = :cnt` — AND logic across tags
- **Multi-category filtering**: `category_ids` param (comma-separated), uses `.in_()` — OR logic within categories
- **Job progress**: Celery tasks push steps to Redis lists (`extraction:steps:{job_id}`), frontend polls `GET /quizzes/job/{job_id}`
- **Model selection**: Admin configures models per task (extraction, teach, article, tts, stt, keyword, flashcard, tool). `get_model_for_task(db, task)` returns (model_id, api_key) with fallback to `settings.LITELLM_MODEL`; `get_configured_model(db, task)` returns None instead of falling back, for work that must not run on a model nobody chose.
- **Vision fallback**: `vision_service.image_context(db, images, model_id=...)` returns the message parts to splice into a user message. If the job's model is vision-capable it gets the images; if not, the `tool` model describes them and the primary reads the description. Capability comes from the proxy's `/model/info` `supports_vision` (cached in-process), and where that is absent from a one-off 8px probe (cached in Redis) — never from a hard-coded list of model names. No tool model configured raises `VisionUnavailable`.
- **Reranking**: `search_service.rerank_ids(db, q, kind, ids)` reorders the first 50 of a fused ranking with a cross-encoder (`LITELLM_RERANK_MODEL`, default `cohere-rerank-v4.0-pro`, Redis override `settings:rerank_model`). It is a *permutation* — an unset, unreachable or malformed reranker returns the ids untouched, never fewer. Applied to question and article search, the test builder's description path, and the AI Mode shortlist; deliberately not to the typeahead, flashcard/media search, or the AI Mode closeness thresholds. Cached in Redis for a day, keyed on model + query + document text. See docs/reranking.md.
- **Uploads**: `file_intake.read()` then `kind_of()` then `text_from()` — size, then type sniffed from the leading bytes, then text. PDF, DOCX and images only (2 MB); an extension is a claim, never the decision. Images are read by the `tool` model, and say so when none is configured.
- **Small talk in AI Mode**: `ai_mode_service.is_small_talk()` runs *before* retrieval. A greeting scores 0.46–0.51 against a clinical corpus, which is either side of the adjacency threshold, so the closeness gate cannot be the guard. Mode "chat" means no shortlist, no citations, and no thread name.
- **`==key points==`**: a remark plugin (`utils/keyPoints.js`) → `<mark class="key-point">`. Never rewrite the markdown string before parsing: highlights and the read-aloud cursor are offsets into the raw text.
- **useEffect dependencies**: Use `.join(',')` on arrays to create a stable string key (e.g., `tagIdsKey`, `catIdsKey`)
- **Admin page data refresh**: `loadData(false)` — the `false` param skips the loading spinner on re-fetch after actions

## Database migrations (Alembic)

**What's a migration?** A migration is a small, ordered change to the database schema — adding a column, renaming a table, changing a type. Each change lives in a Python file under `backend/alembic/versions/`. Alembic tracks which ones have been applied in an `alembic_version` table inside Postgres, so it knows what's new next time you run it.

**Why it exists here:** until now, schema was created via `Base.metadata.create_all()` in `main.py:478`, which only creates *missing tables* — it never alters existing ones. Every column change required manual `ALTER TABLE`. Alembic makes schema changes versioned, reversible, and reproducible across environments.

**Current setup**
- `alembic.ini` contains no hardcoded URL; `alembic/env.py` injects `DATABASE_URL` from the container's env.
- Live DB is stamped at revision `9bac7bf02e38` (the latest in `alembic/versions/`).
- `Base.metadata.create_all()` remains in place as a fallback for fresh deploys — **don't remove it** without first generating a complete baseline migration from the live schema.

**Developer workflow**
```bash
# where am I?
docker compose exec backend alembic current
docker compose exec backend alembic heads

# create a new migration (auto-diff model vs live DB)
docker compose exec backend alembic revision --autogenerate -m "add some column"
# ↑ review the generated file under backend/alembic/versions/ before applying

# apply pending migrations
docker compose exec backend alembic upgrade head

# roll back the last one
docker compose exec backend alembic downgrade -1

When to write one — any schema change: new column, dropped column, renamed field, new table, altered index, new FK. Model edit → migration → apply → commit both together.

Gotchas

• Migrations run as a normal transaction. A failed migration rolls back cleanly.
• --autogenerate doesn't catch: server_default changes, CHECK constraints, enum value additions, data migrations. Hand-edit the file when needed.
• After applying a new migration in dev, rebuild the backend image (docker compose build backend celery) so it ships with the migration file baked in.
• The alembic_version table should only ever have one row. If you see multiple, you have branched heads — run alembic merge to reconcile.

What NOT to do

• Don't add from sqlalchemy import text as X inside functions — import at module top only
• Don't use Question.quiz_id — it's Question.source_quiz_id
• Don't set Content-Type: multipart/form-data manually on axios FormData uploads — axios handles it
• Don't use [someValue === null] as a useEffect dependency — it evaluates to a constant boolean
• Don't docker compose restart expecting code changes to apply — must rebuild
• Don't use window.confirm() — user hates browser popups, use inline confirmation or the Dialog component
• Don't use MDXEditor — it's an MDX parser that chokes on < and { in medical content. Milkdown (CommonMark) is used instead.
• Don't put documents listing on the dashboard — it's in Settings page under Nextcloud.
• Don't gate anything on x.user_id == current_user.id for bank content. Authorship confers nothing; ask the role or a grant.
• Don't stamp a creator on new bank content — write user_id=None.
• Don't reintroduce invite codes or email sign-in codes. The identity provider does that.
• Don't put a token in a URL. nginx logs the request line.