# 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.