Lightweight, terminal‑friendly quiz service inspired by Kahoot. Built as a set of small, focused Python projects.

• Real‑time WebSocket quiz flow via FastAPI and websockets
• Multiple player support with simple connection management
• Admin‑driven progression through quiz questions
• YAML‑defined quizzes validated against shared data models
• Terminal‑based UX for both admin and players
• Clean, typed Python code with ruff, ty and managed by uv tooling

This GitHub organization currently contains these repositories:

• Server – FastAPI WebSocket backend: see quiz-server README

  • FastAPI app exposing WebSocket endpoints:
    • /admin – managed by the admin client
    • /connect/{player_name} – used by player clients
  • Manages connected players and their permissions via:
    • models.Player
    • models.Players
    • models.Results
  • Drives quiz progression using quiz_common.models.Quiz.

• Player client – CLI quiz participant: see quiz-client README

  • Simple CLI application for quiz participants.
  • Connects to the server over WebSocket, receives questions, and sends answers.
  • Entry point: quiz_client.__main__.main.

• Admin client – CLI quiz controller: see quiz-admin README

  • CLI tool for lecturers / hosts to:
    • Load quizzes from YAML files.
    • Validate them with quiz_common.models.Quiz.
    • Send the quiz to the server.
    • Step through questions interactively via WebSocket.
  • Entry point: quiz_admin.__main__.main.
  • Example quiz files: quiz_example.yaml

• Shared models – common data models for quizzes: see quiz-common README

  • Defines data models for quiz structure:
    • quiz_common.models.Quiz
    • quiz_common.models.Question
    • quiz_common.models.Option
  • Used by server and both clients to ensure a consistent quiz format (YAML / JSON).

• Python >=3.13

• Code style and linting via ruff (ruff format, ruff check)

• Type checking enforced via ty (ty check)

• Modern packaging (pyproject.toml) and dependency management (uv)

• All development artifacts must be in English

  • Source code (variable names, function names, class names)
  • Comments and docstrings
  • Commit messages
  • Issues and pull requests
  • Code review comments and discussions

  This ensures consistency and accessibility for all contributors.

• Branch naming convention for developers with write access:

  • Format: <initials>-<issue-number>-<short-description>
  • Example: mz-1-short-desc