pdf-quiz-generator/CLAUDE.md

PedsHub — AI Synopsis for Codebase Work

What this is

PedsHub is a pediatric medical learning platform. Admins upload PREP exam PDFs, AI extracts MCQ questions (or generates flashcards), and users study them with an AI tutor. Everything runs in Docker.

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 + 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)

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
    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)

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	Quiz metadata	section_id → sections (nullable), user_id → users
questions	MCQ questions with pgvector embedding	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, tts, keyword, flashcard). get_model_for_task(db, task) returns (model_id, api_key) with fallback to settings.LITELLM_MODEL.
• 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

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