quiz/CODEX_PROMPT.md

Codex implementation brief — Live In-Lecture Quiz Portal

You are implementing a complete, production-quality web application from a detailed specification. The user (Prof. Ameer H. Khan) wants to use this for an in-lecture engagement quiz with his students next week.

Required reading

Read SPEC.md in full before writing any code. It is the authoritative specification. Sections 1-18 cover everything: routes, data model, state machine, WebSocket protocol, frontend pages, security, project layout, and acceptance criteria. Implement exactly what the spec says.

Working directory

You are at /home/ameer/RD/Projects/Apps/quiz/. This is your workspace root. The spec, a baseline git commit, and .git/ are already in place.

Your responsibilities, end-to-end

1. Implement the full application per SPEC.md — backend (FastAPI + websockets + aiosqlite), frontend (vanilla HTML/CSS/JS), data model, scoring, state machine, all routes.
2. Set up the project structure exactly as specified in §12 (pyproject.toml, .env.example, .gitignore, app/, static/, tests/, examples/).
3. Author an example question pool at examples/week9_pool.json with 10 plausible MCQs about Computer Organization Week 9 recap topics (CPU structure, multi-cycle datapath, hardwired control unit, FSM, microprogrammed control, hardwired vs microprogrammed tradeoffs). It is fine to generate plausible technical content; the user will replace with his real questions later.
4. Write tests as listed in §14 — unit, API, WebSocket, edge-case, and the load-simulation test.
5. Run tests iteratively until all pass: pytest -q green, pytest --cov=app at least 80% line coverage on app/. Fix bugs as they surface. Iterate until clean.
6. Smoke test by starting uvicorn app.main:app with a test .env, verify it boots without errors and GET /healthz responds.
7. Document in README.md (install + run + test + manual smoke test) and NOTES.md (any non-obvious choices or deviations from the spec, per §17).
8. Commit incrementally to git as you go — separate commits for "scaffold project", "data model + db", "scoring + pool validation", "auth + cookies", "student API + WS", "admin API + WS", "frontend student", "frontend admin", "tests", "fixes from test runs". This makes the human review tractable.

Operational rules

• Use python3.11 or newer (system has python3 available; check version; if <3.11, document fallback in NOTES).
• Create a .venv inside the project dir, install deps via pip install -e '.[dev]'. Do NOT use conda or shared envs.
• Pin dependencies with compatible-release operators (e.g. fastapi~=0.115).
• Do not invent new features beyond the spec. Where the spec is silent, pick the simplest reasonable option and document in NOTES.md.
• Do not add Docker, systemd, Caddy, DNS, or any deployment config. §15 explicitly defers these to the human.
• Do not commit .env, quiz.db, __pycache__, or .venv (.gitignore handles this).
• Do not add em-dashes (— or ---) in user-visible text (frontend strings, README, error messages). Use commas, semicolons, periods, parens, or colons. (User preference; internal scratch is unconstrained.)

When you are done

Write a final summary to IMPLEMENTATION_REPORT.md in the project root covering:

• What was built (file inventory + LoC counts).
• Test results: full pytest -q output, coverage percentage.
• Any deviations from the spec (with rationale).
• How to run locally (3-5 lines of shell).
• Any open issues, known bugs, or things you noticed but couldn't fix.
• Anything you'd recommend the human review carefully.

Then stop. Do not deploy, do not push to remote, do not modify anything outside /home/ameer/RD/Projects/Apps/quiz/.

Acceptance bar

The implementation is acceptable when:

• All test categories from SPEC §14 are present.
• pytest -q is fully green.
• Line coverage on app/ is ≥ 80%.
• The load simulation test passes with 50 simulated students.
• uvicorn app.main:app boots without errors.
• README.md and NOTES.md are present and informative.
• Git history shows incremental commits.

If you hit a blocker you genuinely cannot resolve, document it clearly in IMPLEMENTATION_REPORT.md under "Open issues" and continue with the rest of the work; do not halt the whole job for a single recoverable issue.