README.md

ELSA Tech Challenge: Real-Time Vocabulary Quiz

What’s in this repo

• docs/: PRD + system design + diagrams + AI collaboration template
• server/: the implemented component (FastAPI WebSocket server for join/submit/score/leaderboard over WebSocket)

Read first (assessment shortcuts)

• docs/prd.md
• docs/system-design.md
• docs/ai-collaboration.md
• server/README.md (how to run + how to demo)

Quickstart (1 minute)

cd server
docker compose up -d
python -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -e ".[dev]"
uvicorn quiz_server.main:app --reload --port 8000

Health check:

curl -s http://localhost:8000/health

Quick demo (WebSocket)

The WebSocket protocol uses a {type, data} envelope and snake_case keys inside data (e.g., quiz_id, not quizId). See server/README.md for copy/paste examples.

Run tests

cd server
source .venv/bin/activate
pytest -q