Version: 0.1 Last Updated: 2026-04-04 Stage: Pre-development (historical)
⚠️ This is the original pre-development vision, not the current spec. Parts of it are built, parts are planned, and the product has since grown features this doc predates (e.g. the real-time Live Game mode). For what actually ships today, see overview.md, question-types.md, data-model.md, and api-reference.md. Items known not to be implemented yet are marked (planned) below.
QuizBuilder is an online assessment platform for creating, administering, and scoring rich tests. It supports two primary modes: structured exams (sync or async, with submission tracking and grading) and practice (self-paced, offline-capable, with flashcard and partner modes). Content is rich — formulas, images, audio, video, and styled text — to support academic exams, psychological evaluations, language proficiency tests, and more.
| Concept | Definition |
|---|---|
| Test | A collection of questions with delivery configuration (mode, timing, access, scoring) |
| Question | A single item with prompt, rich content, answer options, and optional correct answer |
| Pool | (planned) A named set of questions from which questions are drawn randomly |
| Block | A section of a test. (Per-block pools are planned; today randomization is per-test via draw_count, which draws whole blocks.) |
| Session | One attempt by one taker on one test |
| Submission | The completed answers from a session |
| Taker | The person completing a test — may be anonymous, registered, or code-identified |
| Reviewer | A user who reads and grades open-answer questions manually |
All takers start at the same time. The test creator sets a start time; takers join and wait for the countdown. Timer starts simultaneously for all. Useful for proctored exams, classroom assessments, and competitive quizzes.
Takers start at their own time within an optional availability window. Useful for online course assessments, certification exams, and self-scheduled evaluations.
| Access Type | Description |
|---|---|
| Open link | Any person with the URL can take the test. Submission is anonymous unless taker provides name/email voluntarily. |
| Registered user | Taker must log in. Submission is tied to their account. |
| Generated code | A unique code is issued per taker. Code can be single-use or multi-use. Submission is tied to the code. Creator generates codes in bulk (e.g. for a class of 50). |
Attempt limits are configured per test, not per access type. A code can be used once or multiple times independently of whether the taker is registered.
| Type | Description |
|---|---|
multiple_choice |
One correct answer from a list of options |
multiple_select |
One or more correct answers from a list |
true_false |
Binary choice |
ordering |
(planned) Arrange items in correct sequence |
matching |
(planned) Match left-column items to right-column items |
fill_in_the_blank |
(planned) One or more blanks within a sentence or paragraph |
numeric |
(planned) Exact number or number within a tolerance range |
| Type | Description |
|---|---|
short_text |
Free-text answer, one line |
long_text |
Free-text answer, multi-line (essay) |
file_upload |
Taker uploads a file as their answer |
| Type | Description |
|---|---|
passage |
Rich text shown as reading material before related questions |
audio_prompt |
Audio clip played before related questions (e.g. listening comprehension) |
video_prompt |
Video shown before related questions |
divider |
Visual separator between sections |
All question prompts, answer options, and passage blocks support:
| Content Type | Notes |
|---|---|
| Rich text | Bold, italic, underline, lists, headings, inline code |
| Font size control | Set font size per block — for kanji, large-print, or accessibility needs |
| Formulas | LaTeX inline and block math ($...$ and $$...$$) rendered via KaTeX |
| Images | Upload or embed; with alt text |
| Audio | Upload MP3/M4A; inline player |
| Video | Upload MP4 or embed YouTube/Vimeo URL; inline player |
| Tables | Formatted data tables within prompts |
question:
id
type
prompt ← rich content block
options[] ← for choice types; each option is a rich content block
correct_answer ← optional; omit for open questions and hidden-answer tests
explanation ← shown after answer in practice mode (optional)
points ← default 1
tags[] ← for pool filtering
assets[] ← images/audio/video files attached to this question
test:
title
description
mode ← sync | async
access ← open | registered | code
allow_multiple_attempts ← bool (async only)
max_attempts ← int or null
time_limit_minutes ← null = untimed
time_per_question ← (planned) null = not per-question
show_score ← at_end | never | per_question
show_correct_answers ← at_end | never | per_question | after_review
passing_score_pct ← optional
randomize_questions ← bool
blocks[]:
title ← optional block heading
instructions ← rich text shown at block start
questions[] ← fixed list of questions
pool_id ← (planned) draw randomly from this pool
pool_draw_count ← (planned) how many to draw from the pool
Objective question types are scored automatically on submission. Score = sum of points for correct answers.
Open questions (short_text, long_text, file_upload) are flagged for manual review. A reviewer opens the submission, reads the answer, and assigns a score (0 to max points for that question). The session result is finalized only after all open questions are reviewed.
at_end — taker sees total score after submittingnever — score not shown to taker (reviewer/admin sees it)per_question — taker sees if each answer was correct as they go (practice-friendly)at_end — correct answers shown after submissionnever — answers not revealed to takerper_question — correct answer shown immediately after answering each questionafter_review — shown only after manual review is completePractice mode is a separate delivery context — not a graded session. Designed for self-study and exam preparation.
.json bundle + asset files| Mode | How it works |
|---|---|
| Flashcard | Question shown; taker taps to reveal answer. Self-rated (correct / incorrect). No input required. |
| Self-check | Taker answers; immediately told if correct. Explanation shown if configured. |
| Partner mode | Partner’s screen shows the correct answer as soon as the question appears. Taker answers verbally; partner confirms. Useful for language drills and oral exam prep. |
show_answer_in_practice — per question: always / never / only_if_availableshow_explanation_in_practice — boolFor administrators and reviewers:
| Requirement | Detail |
|---|---|
| Self-hosted | Deploys via Docker Compose; no external cloud dependency |
| Multi-tenancy | Multiple organizations on one instance, fully isolated |
| Data sovereignty | No candidate data leaves the host infrastructure |
| Asset storage | Images/audio/video stored in Docker volume, served locally |
| Concurrent sessions | Handle sync mode with many simultaneous takers |
| Mobile practice | React Native app for offline practice; QR download of test bundle |