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.
11. 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.
12. Runner header spacing polish (question review / X of Y) — CSS added, verify visually.