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:

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:

31 passed, 33 warnings in 5.43s

pytest --cov=app:

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

Smoke test:

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

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.

2.0 KiB Raw Blame History