lila/documentation/ai-context/99-current-task.md

99 — Current Task

Task Description

Implement guest play flow so users can try a 3-round singleplayer quiz without creating an account. After completing the quiz, optionally prompt them to sign up to save progress.

Context

Which parts of the codebase does this touch?

• Frontend (apps/web/)
• Backend API (apps/api/)
• Database schema (packages/db/) — no schema changes needed
• Shared schemas (packages/shared/) — may need GuestGameRequestSchema
• WebSocket protocol (apps/api/src/ws/) — not touched (guest play is singleplayer only)
• Data pipeline (data-pipeline/)
• Infrastructure / deployment (docker-compose.yml, Caddyfile, etc.)
• Documentation

Relevant files I already know about:

• apps/api/src/middleware/authMiddleware.ts — needs optional auth path
• apps/api/src/controllers/gameController.ts — needs guest variant of start/answer
• apps/api/src/services/gameService.ts — may need guest session logic
• apps/api/src/routes/gameRouter.ts — route definitions
• apps/web/src/routes/play.tsx — singleplayer route
• apps/web/src/components/game/GameSetup.tsx — start quiz UI
• packages/shared/src/schemas/game.ts — request/response schemas
• apps/web/src/components/auth/AuthModal.tsx — post-game auth prompt

Constraints & Requirements

Must have:

• Guest users can start and complete a singleplayer quiz (3 or 10 rounds)
• No login required to reach /play or call POST /api/v1/game/start
• Server-side answer evaluation still works (correct answer never sent to frontend)
• Guest sessions are ephemeral (no database storage of guest progress)
• After quiz completion, show a friendly "Save your progress?" prompt with auth options

Nice to have:

• Guest sessions stored in-memory with a TTL (e.g., 24h) so refreshing the page doesn't lose the current quiz
• Post-game prompt includes a "Continue as guest" option to play again without signing up

Must NOT break:

• Existing auth flow (logged-in users still work normally)
• WebSocket protocol (if applicable)
• Database schema (additive changes only unless migration planned)
• Zod schemas in packages/shared (no silent drift)

Known blockers or open questions:

• Should guest sessions use the same GameSessionStore interface with a guest flag, or a separate store?
• Should the post-game auth prompt be a modal or a redirect to a dedicated page?

Definition of Done

• Code implemented and tested
• No TypeScript errors (pnpm typecheck passes)
• Tests pass (pnpm test)
• Manual verification in dev environment (both logged-in and guest flows)
• Commit message follows convention
• Feature branch merged to main

Post-Work Checklist

After the task is complete, ask the LLM:

> "Review the post-work checklist in prompts/meta.md. Which documentation files need updates based on what we just changed?"

Expected doc updates:

• documentation/STATUS.md — Guest play is now live
• documentation/ai-context/03-api-contract.md — New guest endpoint or schema changes
• packages/shared/src/schemas/game.ts — If GuestGameRequestSchema added
• README.md — Quickstart may mention guest play