How to Build a Quiz App

<context>
App: Quiz App
Difficulty: Beginner
Estimated build time: 1–3 days
Tech stack (intermediate): Next.js + Supabase + OpenTriviaDB API — dynamic questions with score storage

Data model:
  Quiz: id, creator_id, title, description, time_limit_seconds, shuffle_questions, published
  Question: id, quiz_id, text, type (multiple_choice/true_false/short_answer), position, explanation
  Answer: id, question_id, text, is_correct
  Attempt: id, quiz_id, user_id, score, total, started_at, completed_at
  Response: id, attempt_id, question_id, answer_id, time_taken_ms

FIRST RUN REQUIREMENT:
Seed one sample quiz (Web Dev Basics, 5 questions) on first launch so users can play immediately without needing to build a quiz first.

DONE WHEN — verify each before marking V1 complete:
  □ User completes a quiz and sees score, time taken, and per-question feedback
  □ Countdown timer auto-advances to the next question when it hits zero
  □ AI generates 5 valid multiple-choice questions from a topic input within 10 seconds
  □ Leaderboard shows top 10 scores and the user's rank if outside the top 10
  □ App opens with a pre-built sample quiz (5 questions) — playable immediately without setup

Recommended build order:
  1. Define API contract + schema + seed data (always first)
  2. Quiz player UI — Build the quiz-taking UI with hardcoded questions: show one question at a time, multiple-choice options, a next button. Track the selected answer in state. Show a results screen at the end.
  3. Scoring and feedback — After each answer (or at the end), show whether the answer was correct, the explanation, and the overall score. Calculate score as (correct / total) × 100.
  4. Timer per question — Add a countdown timer that decrements every second using setInterval. If it hits zero, auto-advance to the next question and mark the current question as unanswered.
  5. Quiz builder — Build an admin form to create quizzes: quiz title, then add questions one by one — question text, 4 answer options, mark the correct one. Save to Supabase. Preview before publishing.
  6. Leaderboard — Store each attempt with score and time taken. Build a leaderboard sorted by score DESC then time_taken ASC. Paginate to top 10. Show the user's rank if they're outside the top 10.
  7. Shareable result card — On quiz completion, generate a result summary card (score, time, rank, quiz title). Use html2canvas to convert it to a PNG. Add a share button that copies the image + a link to the quiz.
  8. AI question generation — Add a "Generate questions from topic" input. Send the topic to Claude Haiku with a prompt: "Generate 5 multiple-choice questions with 4 options and explanations. Return JSON." Parse and pre-fill the quiz builder.
  9. End-to-end verification — walk every Done When condition above (always last)

Known pitfalls to avoid:
  - Running the timer in the component instead of tracking start time — if the user switches tabs, setInterval pauses. Store the question start time as a timestamp and calculate elapsed time on return instead.
  - Sending the correct answer to the client — don't include is_correct in the API response until after the user submits. A user can open DevTools and find the answer before answering.
  - Not shuffling answers server-side — if option A is always correct, users learn the pattern. Shuffle answer options per-attempt, track the shuffled order, and validate against it on submit.
</context>

<role>
You are a Senior Full-Stack Engineer and product architect who has shipped production Quiz Apps before. You know exactly where developers get stuck and how to structure the project to avoid rewrites.
</role>

<task id="step-1-clarify">
Before writing any code or spec, ask me 3–5 clarifying questions that will meaningfully change the architecture. Focus on: scale expectations, auth requirements, platform (web / mobile / both), must-have vs nice-to-have features for the MVP, and any hard constraints (budget, deadline, existing infrastructure).

<example>
BAD: "What tech stack do you want to use?" — too broad, doesn't change architecture decisions.
GOOD: "Do you need real-time sync across devices, or is single-device with periodic refresh acceptable? This decides whether we use WebSockets or simple REST polling and significantly affects infrastructure complexity."
</example>

⚠️ Do NOT start planning or writing code until I answer. Present the questions, then stop and wait.
</task>

<task id="step-2-architect">
After I answer your questions, produce the following in order:

1. TECHNICAL SPECIFICATION
   - System architecture using → to show data and event flow
   - Core data model (refer to data model in <context>)
   - API contract — list ALL routes with request/response shapes BEFORE any implementation
     WHY: agreeing on contracts first prevents rewrites when frontend and backend shapes diverge
   - External APIs and integration points

2. MVP PLAN in three phases:

   SETUP   ✦ Step 1 (always): API contract + schema migration + seed data
     Done when: schema is migrated, seed script runs, app starts with demo data, zero manual setup.

   CORE FEATURES — build in this exact order:
   2. Quiz player UI
   3. Scoring and feedback
   4. Timer per question
   5. Quiz builder
   6. Leaderboard
   7. Shareable result card
   8. AI question generation

   DONE WHEN — one observable condition per feature:
   □ User completes a quiz and sees score, time taken, and per-question feedback
   □ Countdown timer auto-advances to the next question when it hits zero
   □ AI generates 5 valid multiple-choice questions from a topic input within 10 seconds
   □ Leaderboard shows top 10 scores and the user's rank if outside the top 10
   □ App opens with a pre-built sample quiz (5 questions) — playable immediately without setup

   STRETCH GOALS — post-launch additions that are explicitly out of V1 scope.

3. BLOCKER ANALYSIS
   Flag: API rate limits, auth complexity, scope risks, cold-start problems, top 2–3 failure modes.

   FIRST RUN REQUIREMENT: Seed one sample quiz (Web Dev Basics, 5 questions) on first launch so users can play immediately without needing to build a quiz first.
   ✓ Done when: app launches with seed data and the full user journey works without any manual setup.

<self_check>
Before presenting your output, verify:
□ Every answer I gave to clarifying questions is reflected in the spec
□ Step 1 is ALWAYS: API contract + schema + seed — never UI first
□ Done When criteria are observable user behaviors, not internal states
□ The plan is realistic for one person to ship within 1–3 days
□ All known pitfalls from <context> are addressed in the spec
</self_check>
</task>

<task id="step-2.5-agents-md">
Generate an AGENTS.md file at the project root. This file is read automatically by Claude Code, Cursor, Windsurf, and all major AI coding tools at the start of every session.

Include:
- Project overview (2–3 sentences)
- Tech stack with exact version numbers
- Folder structure with one-line descriptions per directory
- Key architectural decisions and the WHY behind each
- Coding conventions: camelCase components, kebab-case files, max 200 lines per file, one concern per file
- Available commands: dev, build, test, lint, db:migrate, db:seed
- MVP scope boundaries — features explicitly out of V1

Note in the file: "Cursor users: symlink .cursorrules → AGENTS.md. Claude Code users: symlink CLAUDE.md → AGENTS.md."
</task>

<task id="step-3-implement">
Implement the full project in the exact order from step 2. For each step:
- Write complete code (no placeholders or TODOs)
- Confirm the step works before moving to the next

<constraints>
- Step 1 is ALWAYS: define all API routes + TypeScript request/response interfaces + run schema migration
  WHY: agreeing on contracts before writing a single component prevents shape mismatches that require rewrites
- Final step is ALWAYS: start the app and walk every Done When condition from <context> end-to-end
  WHY: a spec that passes unit tests but breaks the core user journey is not done
- Max 200 lines per file. WHY: every file must fit in one AI context window for complete reasoning
- One concern per file. WHY: mixing auth logic into API routes makes it impossible to reuse — extract to lib/auth.ts
- TypeScript strict mode, no `any` types. WHY: catches data shape mismatches at compile time, not in production
- All database queries in server components or API routes only. WHY: keeps credentials server-side
- All environment variables documented in .env.example. WHY: next developer sets up in under 5 minutes
</constraints>
</task>