pdf-quiz-generator/docs/quiz-revamp-plan.md

# Orthobullets-inspired quiz revamp

Status: implementation authorized and in progress. Git tracking and Forgejo synchronization are ongoing requirements, not a stopping point. Complete the staged implementation, tests and review without another scope-approval gate.

## Confirmed requirements

- Close Orthobullets look and quiz workflow, with PedsHub branding and responsive desktop/mobile layouts.
- Users create custom tests from existing categories/question bank and can share them.
- Include question-count selection, study/exam modes, and all/unused/incorrect/bookmarked filtering.
- Include answer distributions, explanations/references, keyboard shortcuts, calculator, lab-reference panel, topic reading, flashcards and educator-moderated comments.
- Topic links can target a whole article or a subsection; support category/topic breadcrumbs. Educators add and refine articles and cards gradually, but the infrastructure is part of this revamp.
- Keep current categories and assignments; add optional hierarchy without automatic recategorization.
- AI assistance for categorization, articles and flashcards.
- Preserve question/explanation text, existing features and course-quiz isolation.

Orthobullets was inspected through its UI. Its supplied milestone exam is timed and single-attempt, so it was not started. The custom-test builder was inspected without creating a test. No question-bank content, articles, flashcards or branding assets were imported.

## Git and recovery

- Remote: Forgejo `danvics/pdf-quiz-generator`.
- Development branch: `feat/orthobullets-quiz-revamp`.
- Original synchronized master: `e7f91e5`.
- Existing local work preserved in commit `3cf21d4` and tag `baseline/pre-orthobullets-2026-09-06`; both pushed before revamp work.
- Snapshot contains 24 previously uncommitted files, including explanation images, classification snapshots, quiz visibility/resume changes, quiz codes, TTS options and bot formatting.
- Baseline validation: diff whitespace check; 15 changed Python files parsed; heuristic secret scan found no likely credentials. These are NOT full behavioral tests or a deployment certification.
- Use focused commits for subsequent phases, record checks and push to this branch. No force-pushes or implicit production deployment. Keep credentials, uploads, databases, generated builds and backups outside Git.
- Before migrations/deployment, verify database recovery and current schema/image state. Do not restart backend/Celery during running jobs; rebuild matching images as described in `CLAUDE.md`.

## Reuse and implementation plan

### 1. Custom tests and hierarchy

Extend `backend/app/models/question_category.py` and `routers/question_categories.py` with an optional parent, breadcrumbs, descendant selection and cycle-safe editing. Existing categories remain roots and retain their IDs.

Extend `routers/questions.py`, the existing quiz model/junction and `frontend/src/pages/QuestionBankPage.jsx` with a learner-facing category builder: accurate counts, server-side random sampling without duplicates, state filters, count/mode selection and saved question membership. Reuse attempts and favorites for progress/history/bookmarks.

Category-to-quiz creation currently requires moderator privileges and an origin quiz; ordinary users only have selected-question creation. Unify these paths rather than build another quiz engine. The current `/questions/from-bank` lookup does not filter requested IDs through bank visibility: fix the underlying access checks before exposing sharing. Enforce consistent private/shared access on quizzes, questions, attempts and related content; keep course-only questions isolated. `is_shared` exists but current quiz access relies on ownership/`is_published`, so a UI toggle alone is insufficient.

Keep a saved test's membership fixed through category edits. Preserve completed scores/history; add minimal historical snapshots where required instead of copying the whole question bank.

### 2. Runner and review

Restyle `QuizPage.jsx`, `ResultsPage.jsx` and relevant CSS: compact top navigation, question counter/navigator, breadcrumbs, numbered options, clear selection/correctness and full explanations. Preserve images, highlighting, notes, AI tutor and existing useful controls.

Compute answer distributions from real recorded answers with a stated sample count. Never invent statistics or expose answers, distributions or teaching material early in exam mode. Add input-safe shortcuts, an accessible calculator without `eval`, and an accessible lab-reference panel. Lab values need a cited, educator-approved source; do not infer clinical ranges from screenshots or AI.

### 3. Articles, subsections and linked cards

Reuse `RichEditor.jsx` (Milkdown) and existing markdown/AI editor patterns for a focused topic/article library with draft/published states. Link questions to articles or stable section IDs and show category breadcrumbs. Heading renames must not break subsection links; validate/remediate deleted sections.

Provide side-by-side reading on desktop and an accessible mobile drawer. Treat external references as links unless embedding is supported. Reuse existing flashcard models, sharing, edit and study UI; add manual card creation and question/category/article associations instead of a second card system. Empty content is clearly labeled, with educator-only author/link actions.

### 4. AI authoring and moderation

Reuse `get_model_for_task`, existing LiteLLM configuration, Celery and job-progress UI. Existing classification produces tags, not category hierarchy; add reviewable category suggestions rather than automatically moving questions. Support article drafting/refinement and cards from authorized questions/articles.

Implementation default: shared educational AI content is educator-authored and remains draft until approved. Do not fabricate reference claims or auto-publish generated material. Learner-private AI drafting is not required for this release.

Add comments with author ownership, moderation state, pagination and server-side educator controls. Implementation default: learners see their own pending comments; public visibility requires educator approval. Sanitize rendered content and bound request sizes/rates.

### 5. Verification and release

Use existing Vitest/Testing Library and backend tests. Cover category cycles/descendants, available counts/sampling, question permissions, saved membership, sharing/revocation, course isolation, exam secrecy, historical attempts, article anchors, AI drafts and comment moderation. Check calculator/keyboard boundaries and desktop/mobile accessibility.

Run frontend build and targeted/full relevant suites; obtain independent review, inspect actual diffs and browser-check visible outcomes. Use versioned reversible migrations, a database recovery point and matching backend/Celery/frontend builds. Verify live behavior after an approved rollout; retain rollback information.

## Delivery defaults

- AI authoring is available to educators/admins; generated shared material requires review before publication.
- Lab-reference support includes educator-managed entries and source/age/unit fields. Do not publish unsourced or AI-invented ranges. An honest empty state is permitted until verified clinical data is supplied.
- The user has authorized implementation. Continue each completed milestone into verification, review, Git synchronization and the next milestone; stop only for a genuine blocker.
- No migrations or deployments were performed during the initial scoping/Git synchronization. Subsequent implementation and validation evidence must be recorded in focused commits.

## Pending backlog (2026-09-09)

1. Category management page (with search): organize parents/subparents, create new parent, delete with move_to, move questions between categories; link from bank/create pages.
2. ~~Question editor: shared CategoryTree facets.~~ **Done** — the edit and create
   modals live in `components/QuestionEditors.jsx` (shared by the question bank
   and the question manager) and render `CategoryTree` for primary + extra
   categories.
3. ~~Create Custom Test facets.~~ **Done 2026-09-09** — rebuilt against AMBOSS's
   own builder: two cards (Set test topics / Test criteria), facet rows that open
   a search + checklist panel and summarise as "Name +N", a cross-facet filter
   search, and a sticky bar carrying Test type and Create Test.
4. Upload flow: document → matched BANK questions via keywords/embeddings; min 10MB, max 30 questions, 5-day auto-delete.
5. AI "describe what to study" → quiz from matched bank questions (all logged-in users).
6. ~~Quiz action buttons: analysis / rename / repeat / delete.~~ **Done 2026-09-09** —
   `GET /quizzes/sessions` feeds an AMBOSS-style session list on `/quizzes`
   (day groups, progress bar, Start/Resume/Review, action menu with Analysis /
   Repeat / Rename / Share / Edit / Category / Delete). `?restart=1` on the quiz
   runner makes Repeat start a fresh attempt.
7. ~~Study recommendations from weakest categories.~~ **Done 2026-09-09** —
   `GET /study-tools/recommendations` and the `/analysis` page (Performance /
   Recommendations tabs, readiness with sample-size shrinkage, relevance,
   category roll-up, expandable focus rows). Deliberately not called EPC.
8. ~~Dedicated question-management CMS page.~~ **Done 2026-09-09** —
   `/questions/manage` (moderator): editorial health tiles backed by
   `GET /questions/manage/summary`, a `needs` gap filter on `/questions/bank`,
   and `POST /questions/bulk` for category / difficulty / sharing / delete on up
   to 500 checked questions. Per-category educator grants shipped the same day:
   `category_grants` (migration `p8b9c0d1e253`), scope enforcement across
   create/edit/delete/bulk/summary, and a GrantsPanel in the manager.
9. ~~Article pages listing questions.~~ **Done 2026-09-09** — AMBOSS article pages
   list no questions; ours printed every linked stem with its answer and
   explanation. Replaced with a "Practise this topic" panel that builds an
   article-scoped test; educators keep an answer-free unlink list. The lab panel
   lost its Sources footer and its competing bold weights.
10. ~~Vision review finding: question-card row consistency.~~ **Done 2026-09-09** —
   the runner's 78px wrapping category band and three stacked button strips were
   replaced by one meta line plus a single action bar. nginx now sends no-cache
   for index.html so a deploy is actually visible without a hard refresh.
10. Showcase content: `scripts/seed_showcase_articles.py` seeded 8 starter
    articles (one per major system, question-linked). Educator review of the
    text is still pending before these are taught from.
10. Runner header spacing polish (question review / X of Y) — CSS added, verify visually.