Add documentation and implementation report

README.md

@@ -1,3 +1,45 @@
 # Live In-Lecture Quiz Portal
 
-Development notes will be filled in as the implementation lands.
+FastAPI, SQLite, WebSocket, and vanilla frontend implementation for a live classroom quiz.
+
+## Install
+
+```bash
+cd /home/ameer/RD/Projects/Apps/quiz
+python3 -m venv .venv
+. .venv/bin/activate
+pip install -e '.[dev]'
+cp .env.example .env
+```
+
+Edit `.env` and set real values for `QUIZ_SECRET_KEY` and `QUIZ_ADMIN_PASSWORD`.
+
+## Run
+
+```bash
+. .venv/bin/activate
+uvicorn app.main:app --host 127.0.0.1 --port 8001 --reload
+```
+
+Open `http://127.0.0.1:8001/admin/`, log in, create a quiz pool, then create a session. Use the displayed join URL in another browser or private window for the student view.
+
+## Test
+
+```bash
+. .venv/bin/activate
+pytest -q
+pytest --cov=app
+```
+
+The load simulation test creates 50 student WebSocket clients and runs a 5-question quiz.
+
+## Manual Smoke Test
+
+```bash
+export QUIZ_DB_PATH=/tmp/quiz-smoke.db QUIZ_SECRET_KEY=smoke-secret QUIZ_ADMIN_PASSWORD=smoke-pass QUIZ_PUBLIC_URL=http://127.0.0.1:8001
+. .venv/bin/activate
+uvicorn app.main:app --host 127.0.0.1 --port 8001
+curl http://127.0.0.1:8001/healthz
+```
+
+Expected health response starts with `{"ok":true`.