Quizzer - Interactive Jeopardy Game System

A modern, multi-client Jeopardy game application with real-time synchronization, host mode, and support for custom hardware buzzers. Built with SvelteKit frontend and Django backend.

Also an experiment in AI-assisted coding, portions of the repository were bootstrapped or improved with the use of AI assistants (including this README).

Features

🎯 Core Game Features

• Classic Jeopardy gameplay with customizable boards and categories
• Multi-media questions supporting text, images, videos, and audio
• Special questions and Daily Double support
• Real-time scoring with team and individual player tracking
• Question state management (answered/unanswered tracking)

🌐 Multi-Client Architecture

• Real-time synchronization across all connected clients using WebSockets
• Host mode for game administration and control
• Player clients for team participation
• Spectator mode for viewing without participation
• Cross-platform compatibility - works on any device with a web browser

🔧 Hardware Integration

• Custom buzzer support via Raspberry Pi GPIO
• Buzzer system supporting up to 8 buzzers using a hardware multiplexer
• Real-time buzzer detection with hardware debouncing
• Buzzer LEDs via a second multiplexer
• Automatic reconnection and fault tolerance

🎨 Modern UI/UX

• Responsive design built with TailwindCSS and Skeleton UI
• Real-time audio feedback with configurable sound effects
• Color-coded teams for easy identification
• Smooth animations and transitions

Architecture

Frontend (/app)

• Framework: SvelteKit with TypeScript
• Styling: TailwindCSS + Skeleton UI components
• State Management: Svelte stores with reactive updates
• Real-time Communication: WebSocket integration
• Audio System: Built-in sound effects and feedback

Backend (/service)

• Framework: Django with Django REST Framework
• Real-time: Django Channels with WebSocket support
• Database: SQLite (configurable for PostgreSQL/MySQL)
• API: RESTful endpoints for game management
• Admin Interface: Django admin for content management

Hardware (/hardware)

• Platform: Raspberry Pi with GPIO control
• Buzzer System: Custom multiplexed buzzer controller
• Communication: WebSocket client for real-time integration

Quick Start

Prerequisites

• Node.js 18+ and Bun (for frontend)
• Python 3.9+ (for backend)
• Raspberry Pi with GPIO (for hardware buzzers, optional)

Backend Setup

cd service
# Install python packages
# TODO: Actually create a requirements.txt
pip install -r requirements.txt
python manage.py migrate
python manage.py createsuperuser
python manage.py runserver

Frontend Setup

cd app
bun install
bun run dev

Hardware Buzzers (Optional)

cd hardware
# On Raspberry Pi:
python buzzers.py <game_id>

Game Setup

1. Create a Game: Use Django admin at http://localhost:8000/admin/
2. Add Boards: Create one or more game boards
3. Add Categories: Set up categories for each board
4. Add Questions: Create questions with points, answers, and optional media
5. Create Teams: Set up teams with custom colors
6. Add Players: Assign players to teams with optional buzzer numbers

API Endpoints

Games

• GET /api/games/ - List all games
• POST /api/games/ - Create new game
• GET /api/games/{id}/ - Get game details

Teams & Players

• GET /api/games/{game_id}/teams/ - List teams for game
• POST /api/games/{game_id}/teams/ - Create team
• POST /api/teams/{team_id}/players/ - Add player to team

WebSocket Events

Connect to: ws://localhost:8000/ws/game/{game_id}/

Client → Server

{
  "type": "toggle_buzzers",
  "enabled": true
}

{
  "type": "buzzer_pressed", 
  "buzzerId": 3
}

{
  "type": "answer_question",
  "questionId": 123,
  "playerId": 456,
  "isCorrect": true,
  "points": 400
}

Server → Client

{
  "type": "game_state_update",
  "board": {...},
  "teams": [...],
  "currentQuestion": {...}
}

{
  "type": "buzzer_pressed",
  "buzzerId": 3,
  "playerId": 456
}

Development

Frontend Development

cd app
bun run dev          # Start dev server
bun run build        # Build for production
bun run preview      # Preview production build
bun run check        # Type checking
bun run lint         # Lint and format
bun run test         # Run tests

Backend Development

cd service
python manage.py runserver    # Start dev server
python manage.py shell        # Django shell
python manage.py test         # Run tests

Hardware Buzzer Wiring

For Raspberry Pi GPIO setup:

GPIO 23, 24, 25 → Multiplexer select pins (S0, S1, S2)
GPIO 16 → Enable pin (EN)
GPIO 18 → Input pin (SIG)

Connect up to 8 buzzers through a 74HC4051 multiplexer.

TODO: Add more details on the wiring and hardware setup.

License

This project is licensed under the MIT License - see the LICENSE file for details.