📚 Documentation

1. 🏗️ Architecture

flowchart LR
  DS["OpenTDB API"] -->|"import: base64 decode + map"| CPT["qw_quiz / qw_question CPTs"]
  CPT -->|"GET /quizwizz/v1/quiz/{id} (with answers)"| PLAY["Alpine player in browser"]
  PLAY -->|"local grading"| PLAY
  PLAY -->|"window.print()"| PRINT["printable sheet + key"]

flowchart TD
    DS[DATASETS] --> CPT[CPT quiz+question]
    CPT --> REST[REST]
    REST --> AP[Alpine player browser]
    AP --> PS[print / share]
    
    BT[batch translate] --> CPT
    CW[🧙 chat wizard NL→draft] --> CPT
    OR[OpenRouter server-side, key hidden] --> CW
    API[Abilities API + Data Views] -.-> BT
    API -.-> CW

Plain: facts live in WordPress → browser plays them → AI only fills the two arrows (translate, wizard).

2. 🗄️ Data Model

📦 Entity	Kind	Key fields
quiz	CPT	title, mode(practice/timed/shuffle), form(A/B/C), lang, question refs
question	CPT	stem, type, choices[], correct_idx, explanation, source
taxonomies	tax	subject · difficulty · language · tag

🗃️ External Datasets & Scale Analysis

QuizWizz is designed to scale beyond the bundled OpenTDB pool by leveraging two massive academic and trivia benchmarks for future expansion:

🌍 Global-MMLU (The Academic Benchmark)

• Scope & Size: ~14,000 highly-curated samples spanning 42 languages and 57 academic subjects (physics, law, history, etc.).
• Time-Relevance: Highly static. Because it tests universal academic concepts, the factual validity does not decay over time.
• Storage Footprint: Micro (~30 MB). The dataset is purely structured text (stem, choices, correct index), making it incredibly lightweight to store and query.
• Scrapeability/Access: Trivial. It is officially hosted and maintained on Hugging Face (CohereLabs/Global-MMLU), bypassing any need for complex web scraping.

🧩 TriviaQA (The Heavyweight Open-QA Standard)

• Scope & Size: ~95,000 base Q&A pairs authored by trivia enthusiasts. This scales to ~650,000 triples when combined with its reading comprehension evidence documents.
• Time-Relevance: Semi-static. While most historical/factual trivia remains accurate, questions regarding “current” events from its 2017 release date experience slow decay.
• Storage Footprint: The Q&A pairs alone are lightweight (~150 MB). However, the full context corpus (including Wikipedia/web evidence docs) expands from a 2.6 GB compressed download to ~18 GB uncompressed on disk.
• Scrapeability/Access: Trivial. Natively integrated into Hugging Face (mandarjoshi/trivia_qa) with clean train, validation, and test splits.

3. 🛣️ Routes

Method	Endpoint	🔐 Auth	Does
GET	/models	logged-in	OpenRouter list, cached 1h → picker
POST	/generate	edit_posts + rate-limit	🧙 NL → quiz draft (SSE stream)
POST	/translate	manage_options	batch translate via WP-Cron
GET	/quiz/{id}	public	quiz JSON for play
GET	/wp/v2/settings	manage_options	React settings (core)

4. 🎨 UI/UX

🖥️ Surface	What	Built with
Admin list	filter/sort quizzes & questions	Data Views
Settings	API key · default model+prompt · languages	React + /wp/v2/settings
Frontend	quiz block → card · progress · timer · results	Block v3 + Alpine
🧙 Wizard	floating bubble (↘) → model+prompt dropdowns → NL box → insert draft	Alpine + /generate
Finish	Print + Share buttons	native APIs

5. 🔌 OpenRouter

Knob	Setting
Picker	GET /api/v1/models?order=newest → cache 1h → dropdown (model & prompt user-selectable)
Chat/Translate	OpenAI-compatible /chat/completions, stream:true (+ non-stream fallback)
Reliability	response_format=json_schema → clean question objects
Cost	:floor variant · max_tokens cap · BYOK · provider spend-limit
🔑 Key	server-side only (wp-config/env) — never client JS

6. 🔒 Security

cap_check → nonce → sanitize → ESCAPE · $wpdb->prepare('%s %d %i') · defined('ABSPATH')||exit · sanitize HTML before mPDF · 2FA on wp.org acct.

7. 📝 Builder Checklists

QuizWizz Builder 🧙 — the config that makes a quiz: category × count × difficulty × mode{🖥️online|🖨️print}. Checklist below is priority-tagged: ✅ MVP · 🔜 Phase-2 · 🧊 YAGNI-cut (don’t build until a real story forces it).

1. ✅ Builder Form

Acceptance: pick category(ies) + count + difficulty + mode → a valid, buildable quiz, every time.

☐	Feature	Pri	Must behave like
☐	Category select (multi + “All/Random”)	✅	shows live count per category
☐	Count stepper/input + presets (5/10/20)	✅	clamped to available pool
☐	Difficulty easy/med/hard/mixed	✅	mixed = even split
☐	Mode toggle 🖥️/🖨️	✅	switches output path
☐	Language picker (enabled langs only)	✅	drives translated bank
☐	Live availability counter	✅	“32 questions match”
☐	Validation + disabled CTA + empty-match msg	✅	“loosen filters” hint
☐	Loading/skeleton on generate	✅	no dead clicks
☐	Keyboard + ARIA + mobile	✅	fully operable
☐	Shareable URL state ?cat&count&diff&mode&lang	🔜
☐	Remember last config · Timer setting · Form A/B/C selector	🔜
☐	“Surprise me” · skins · per-question timer · drag-reorder	🧊

2. 🖥️ Online Play

☐	Feature	Pri
☐	Render Q cards (MCQ/T-F) + shuffle Qs & options	✅
☐	Progress X/N · select+lock answer	✅
☐	Results: score · % · per-Q review + explanation	✅
☐	Retry / new quiz · Print results · Share (Web Share API)	✅
☐	Timer · save attempt (logged-in) · immediate-vs-end feedback toggle	🔜
☐	Leaderboards · streaks · achievements · multiplayer	🧊

3. 🖨️ Print Mode

☐	Feature	Pri
☐	Clean question sheet (no site chrome)	✅
☐	Separate answer key (from explanation field)	✅
☐	Header: title + name/date blanks + instructions	✅
☐	@media print/@page: page-breaks + repeat headers	✅
☐	window.print() path	✅
☐	mPDF download (saved/email/non-Latin) · Form A/B/C shuffle · QR version-id · bubble sheet	🔜
☐	OMR auto-grade · multi-column · per-theme fonts	🧊

4. ⚙️ Admin Backend

☐	Feature	Pri
☐	Question bank CRUD via native WP 7.0 Data Views extending edit.php?post_type=qw_question	✅
☐	Import OpenTDB (ready MCQ) + map categories via wp quizwizz import_sqlite CLI command	✅
☐	Choose which categories/difficulties/modes/languages are exposed in builder	✅
☐	Builder limits: default/max count, allowed presets, guest-vs-logged-in	✅
☐	Settings (React): OpenRouter key (server-side) + default model+prompt	✅
☐	Quality gate: review/approve imported Qs (kills bad data)	✅
☐	Batch translate (OpenRouter + WP-Cron / local SQLite fallback): per-lang status via qw_lang native column in DataViews · spot-check flag · cost estimate	✅
☐	🧙 Wizard config: hourly model picker · rate limit · enable/disable	🔜
☐	Attempts log + per-category stats (Data Views) + CSV export	🔜
☐	TriviaQA/Global-MMLU import · dedup · bulk tag · print branding	🔜
☐	A/B configs · full analytics dashboard · gamification admin	🧊

5. 🛡️ Security Checklists

☐ every route: cap → nonce → sanitize → escape · ☐ clamp count to pool server-side (never trust client) · ☐ cache pool-counts + model-list(1h) + built/translated sets · ☐ i18n + a11y + mobile · ☐ Plugin Check green before ship.

6. 📷 Media Assets

(Assets should be placed in projects/quizwizz/assets/ and embedded here as they are generated during development.)

8. 📝 Frontend

The quiz builder and pre-print editor heavily leverage Alpine.js and SortableJS to provide a reactive, zero-build frontend without the overhead of React.

🏗️ Architecture

• Data Hydration: Initial quiz and question metadata are loaded via wp_localize_script() directly into the global qwCraftData object. This eliminates the need for initial AJAX fetching and prevents UI jitter on page load.
• State Management: The <div x-data="qwPdfEditor()"> element acts as the single source of truth for the frontend state. It manages variables like activeTab, quizSearch, questionCount, pdfTheme, and difficulty.
• Progressive Enhancement: Forms initially render with hidden native <input> fields bonded to Alpine models (x-model). When the form is submitted natively (via admin-post.php), the backend receives a standard POST payload, ensuring gracefully degraded operations.
• Visual Pre-print Editor:
  • When a user clicks “Edit/Reroll” or views a draft, a REST API endpoint (/wp-json/quizwizz/v1/craft-draft) validates the current selections and returns a JSON array of questions.
  • Alpine binds this array using x-for, rendering interactive cards.
  • SortableJS is initialized via an $nextTick() Alpine hook on the list container to enable drag-and-drop reordering.
  • Undo/Redo: The editor uses standard pushState() logic maintaining history and future stacks for deep-cloned question arrays.

🧹 Codebase Standards

• No external CDNs. All frontend libraries (Alpine.js 3.15.12, SortableJS 1.15.2) are packaged natively inside assets/js/.
• Vanilla JS elimination: Event listeners like DOMContentLoaded are stripped and replaced natively by x-init or standard Alpine directives (@click, @change).
• CSS Utility Scaling: Extensive use of scoped qw- prefixed utility classes (from Tailwind processed CSS) maintains a minimal stylesheet footprint without bleeding into the broader WordPress theme.