# Implementation Report

## Built

Implemented the live in-lecture quiz portal per `SPEC.md`: FastAPI backend, SQLite schema with WAL, signed student and admin cookies, quiz pool validation, modular scoring, student/admin APIs, WebSocket state machine, auto-close, CSV export, vanilla student/admin frontends, example Week 9 question pool, docs, and tests.

File inventory and line counts:

```text
app/: 1400 lines
static/: 775 lines
tests/: 504 lines
examples/week9_pool.json: 127 lines
total across app, static, tests, examples: 2806 lines
```

## Test Results

`pytest -q`:

```text
31 passed, 33 warnings in 5.43s
```

`pytest --cov=app`:

```text
31 passed, 33 warnings in 5.48s
TOTAL 854 statements, 67 missed, 92.15% coverage
Required test coverage of 80.0% reached.
```

Smoke test:

```text
uvicorn app.main:app started successfully on 127.0.0.1:8001
GET /healthz returned {"ok":true,"version":"0.1.0","sessions_active":0,"ws_clients":0}
```

## Run Locally

```bash
python3 -m venv .venv
. .venv/bin/activate
pip install -e '.[dev]'
cp .env.example .env
uvicorn app.main:app --host 127.0.0.1 --port 8001 --reload
```

## Deviations and Notes

- Server-side QR SVG data URLs are used instead of a client-side QR library.
- `live_histogram` is pushed on every accepted submission, not throttled.
- Broadcast sends are queued so slow WebSocket clients do not block state changes.
- `static/observer.html` is a placeholder because the observer page is optional.
- FastAPI emits a non-fatal `on_event` deprecation warning with the installed package version.

## Open Issues

No known functional blockers. The admin UI is intentionally plain and should be reviewed with the instructor workflow in mind before classroom use.

## Review Carefully

- The late-join behavior and missed-submission rows.
- The session control flow from `lobby` through `finished`.
- CSV shape against the exact spreadsheet format wanted for class records.
- The generated example questions, because they are plausible placeholders.