Sauci/docs/quiz.md

Couples quiz

Maintained reference for the shareable "how well do you know each other?" quiz: a couple works through the same set of questions, each partner answers about themselves and guesses about the other, and the pair only sees a score once both have finished.

Ownership

Concern	Location
Schema and seed content	apps/api/drizzle/0019_quiz.sql, apps/api/drizzle/0020_quiz_question_pool.sql
HTTP contract	apps/api/src/domains/quiz/routes.ts
Session and scoring rules	apps/api/src/domains/quiz/repository.ts
Pure scoring function	apps/api/src/domains/quiz/service.ts (computeQuizScore)

Session lifecycle

POST /v1/quiz/sessions ──► active session (10 questions, question order fixed at creation)
   │
   ├── each partner submits a full answer set (self + guess per question)
   │
   └── once BOTH partners have a complete set ──► session completes, score is computed

Only one active session exists per couple at a time (quiz_sessions_one_active_per_couple_idx, a partial unique index on couple_id where status = 'active'). Starting a quiz while one is already active returns that same session (200) instead of creating a second one; two simultaneous starts race safely because the partial unique index, not application locking, is the source of truth.

When a new session is created, the 10 questions are chosen from the active pool with a couple-scoped preference order: questions this couple has never had in any prior session (completed or active) come first, then the least-recently-used ones, with a random tiebreak within each group. This keeps repeat quizzes varied instead of always drawing the same sort_order-first questions. The seeded pool (0019_quiz.sql plus 0020_quiz_question_pool.sql) has 36 active questions, so two consecutive sessions for the same couple are guaranteed not to overlap.

Answers are submitted as one complete batch per call (quiz_answers, upsert on (session_id, user_id, question_id)). A submission must cover every question in the session exactly once, with every index inside that question's option list, or it is rejected with 400 invalid_answers. A session that has already completed rejects further submissions with 409 session_completed.

Scoring

Each question contributes up to two hits: partner A's guess about B counts if it matches B's self-answer, and separately B's guess about A counts if it matches A's self-answer. score_percent = round(100 * hits / (2 * question_count)). computeQuizScore in service.ts is the pure, unit-tested implementation; the repository only assembles the per-question pairs and persists the result.

Couple isolation

Every session and result lookup is scoped to the caller's own couple. A session ID that belongs to another couple returns 404 session_not_found, never a hint that it exists elsewhere. Starting a quiz requires both a couple (409 no_couple) and a paired partner (409 partner_required).

HTTP contract

Method	Path	Notes
POST	/v1/quiz/sessions	201 on a new session, 200 when an active one already exists
GET	/v1/quiz/sessions/current	{ session: SessionPayload | null }, most recent session for the couple
POST	/v1/quiz/sessions/:sessionId/answers	{ answers: [{ question_id, self_index, guess_index }] }
GET	/v1/quiz/sessions/:sessionId/result	409 session_not_completed before both partners finish

SessionPayload never includes the partner's raw answers before completion; per-question partner detail (partner_self_index, partner_guess_index, partner_guessed_right) is only exposed by the /result endpoint of a completed session.

Tests

• apps/api/test/quiz.service.test.ts: unit tests for computeQuizScore
• apps/api/test/quiz.routes.test.ts: HTTP contract and error mapping
• apps/api/test/quiz.integration.test.ts: real PostgreSQL, covering the full happy path with a hand-computed score, idempotent session start, couple isolation, incomplete answer set rejection, result blocked before completion, no question overlap between a completed session and the next one for the same couple, and that selection is scoped per couple

Mobile client

Concern	Location
Feature screens, hooks, API client	apps/mobile/src/features/quiz/
Zustand store (generation-counter pattern, cleared on sign-out)	apps/mobile/src/store/quizStore.ts
Discovery entry point	apps/mobile/src/components/discovery/QuizTile.tsx
Route wrapper	apps/mobile/app/(app)/quiz.tsx

The screen walks not-paired, intro, answering (one question at a time, self then guess), waiting-on-partner, and results states off useQuizScreen. Answers are held client-side per question until every question in the session has both a self and a guess index, then submitted as the one batch the API expects; the store never calls the answers endpoint more than once per session. Results render a shareable card (QuizResultsShareCard / QuizShareModal, following the SharePreviewModal capture pattern) carrying only the match score and Sauci branding, never question text or answers, so a screenshot cannot leak either partner's content.

Not in this version

Question authoring tooling in the admin app is out of scope for this change.