How to Build a Quiz App

<context>
App: Quiz App
Difficulty: Beginner
Estimated build time: 1–3 days

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

Recommended build order:
  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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.
  7. 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.

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.

Tech stack (intermediate): Next.js + Supabase + OpenTriviaDB API — dynamic questions with score storage
</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>
</task>

<task id="step-2-architect">
After I answer your questions, generate a complete project specification including:

1. Final tech stack with version numbers
2. Full file and folder structure
3. Complete database schema — every table, column, type, index, and foreign key
4. All API routes with request/response shapes and auth requirements
5. Component tree with TypeScript props interfaces
6. Auth and authorisation flow (who can do what)
7. Step-by-step implementation plan in the exact build order from <context> above
8. All environment variables with descriptions

<self_check>
Before presenting the spec, verify:
□ Every answer I gave in step 1 is reflected in the spec
□ The database schema matches the data model in <context>
□ The implementation plan follows the build order from <context>
□ No circular dependencies in the component tree
□ Auth is wired up before any protected routes are built
□ 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, Sourcegraph Cody, and all major AI coding tools at the start of every session.

Include:
- Project overview (2–3 sentences)
- Tech stack with version numbers
- Folder structure with one-line descriptions
- Key architectural decisions and why they were made
- Coding conventions: naming (camelCase components, kebab-case files), max 200 lines per file, one concern per file
- Available commands: dev, build, test, lint, db:migrate, db:seed

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

<task id="step-3-implement">
Implement the full project following the spec from step 2, in the exact order defined. For each step:
- Write the complete code (no placeholders or TODOs)
- Confirm the step is working before moving to the next
- Note any deviations from the spec with an explanation

<constraints>
- Max 200 lines per file. WHY: every file must fit in one AI context window for easy review and editing.
- 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 at 2am.
- All database queries in server components or API routes only. WHY: keeps credentials server-side, prevents accidental client-side exposure.
- All environment variables documented in .env.example. WHY: the next developer (or your future self) should be able to set up the project in under 5 minutes.
- Comment every non-obvious decision. WHY: AI tools read your comments to understand intent — without them, the next edit will break the pattern you established.
</constraints>
</task>