triviathang/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

A real-time trivia game web application with Flask backend and React frontend, featuring WebSocket support for live score updates and question displays. The app supports creating question banks, setting up games with teams, and running live trivia games with separate contestant (TV display) and admin control views.

Tech Stack

Backend:

• Flask 3.0+ with Flask-SocketIO for WebSocket support
• SQLAlchemy ORM with Flask-Migrate for database migrations
• SQLite database (located at backend/instance/trivia.db)
• Eventlet for async/WebSocket server

Frontend:

• React 19 with React Router 7
• Vite for build tooling and dev server
• Socket.IO client for WebSocket communication
• Axios for HTTP requests
• Note: Frontend source is nested at frontend/frontend/ (double directory structure)

Development Commands

Backend Setup and Running

# Install Python dependencies
uv sync

# Initialize database (first time only)
export FLASK_APP=backend.app:create_app
uv run flask db init

# Create and apply migrations
uv run flask db migrate -m "Description of changes"
uv run flask db upgrade

# Run backend server (use PORT=5001 to avoid macOS AirPlay conflict on 5000)
PORT=5001 uv run python main.py

Frontend Setup and Running

# Install frontend dependencies
cd frontend/frontend  # Note the nested directory
npm install

# Run frontend dev server (with proxy to backend)
npm run dev  # Runs on port 3000

# Build for production (outputs to backend/static/)
npm run build

Database Migrations

When you modify models in backend/models.py:

export FLASK_APP=backend.app:create_app
uv run flask db migrate -m "Description of changes"
uv run flask db upgrade

Docker Development (Recommended)

Docker Compose provides the easiest development setup with automatic hot reload for both frontend and backend:

# Start all services (backend + frontend with hot reload)
docker compose up

# Start in detached mode
docker compose up -d

# View logs
docker compose logs -f

# Stop all services
docker compose down

# Rebuild images after dependency changes
docker compose up --build

# Run database migrations inside container
docker compose exec backend uv run flask db migrate -m "Description"
docker compose exec backend uv run flask db upgrade

Services:

• Backend: http://localhost:5001 (Flask + SocketIO)
• Frontend: http://localhost:3000 (Vite dev server)

Hot Reload:

• Backend: Changes to backend/, main.py, and migrations/ automatically reload Flask
• Frontend: Changes to src/, public/, and config files automatically reload Vite
• Database and uploaded images persist in volumes

Architecture:

• Dockerfile.backend: Python 3.14 with uv, Flask in debug mode
• Dockerfile.frontend: Node 18 with Vite dev server
• docker-compose.yml: Orchestrates both services with volume mounts for hot reload
• Named volume for node_modules to avoid host/container conflicts
• Health check on backend before starting frontend

Architecture

Application Factory Pattern

The Flask app uses an application factory (backend/app.py:create_app()) which:

• Initializes extensions (SQLAlchemy, Flask-Migrate, Flask-SocketIO, CORS)
• Registers blueprints for routes
• Serves React frontend in production from backend/static/
• Configured via backend/config.py with environment-based settings

Database Models (backend/models.py)

Core entities:

• Question: Stores trivia questions (text or image type) with answers and optional categories
• Game: Represents a trivia game session with is_active flag and current_question_index
• GameQuestion: Junction table linking questions to games with ordering
• Team: Teams participating in a game
• Score: Tracks points awarded per team per question (composite unique constraint on team_id + question_index)
• Category: Optional categorization for questions

Key relationships:

• Games can only be active one at a time (Game.get_active() class method)
• Teams calculate total_score as a property by summing all Score records
• Questions can be reused across multiple games via GameQuestion junction table

WebSocket Architecture (backend/sockets/events.py, backend/services/game_service.py)

Room-based design:

• Each game has two rooms: game_{id}_contestant and game_{id}_admin
• Contestants join the contestant room and see questions WITHOUT answers
• Admin joins the admin room and sees questions WITH answers
• Score updates broadcast to both rooms

Key events:

• join_game / leave_game: Client joins/leaves game rooms with role (contestant/admin)
• game_started: Emitted when game starts
• question_changed: Sent to contestant room (no answer)
• question_with_answer: Sent to admin room (with answer)
• score_updated: Broadcasts score changes to both rooms
• answer_visibility_changed: Toggles answer display on contestant screen

Game flow:

• Admin starts game via /api/admin/game/<id>/start → broadcasts first question
• Admin navigates questions with /next and /prev → broadcasts to all clients
• Admin awards points via /award → creates/updates Score records → broadcasts to all
• Optional answer reveal to contestants via /toggle-answer

API Routes

Routes are organized into blueprints:

• backend/routes/questions.py: Question CRUD (/api/questions)
• backend/routes/games.py: Game management (/api/games)
• backend/routes/teams.py: Team management (/api/teams)
• backend/routes/admin.py: Game control endpoints (/api/admin/game/<id>/...)
• backend/routes/categories.py: Category management (/api/categories)

Admin endpoints use game_service.py functions which handle both database updates AND WebSocket broadcasts.

Frontend Build Configuration

Development:

• Vite dev server runs on port 3000
• Proxies /api and /socket.io requests to Flask backend on port 5001
• Configuration in frontend/frontend/vite.config.js

Production:

• npm run build outputs to backend/static/ (configured via build.outDir)
• Flask serves the built React app and handles client-side routing
• All non-API routes return index.html for React Router

Image Handling

• Images uploaded to backend/static/images/ via backend/services/image_service.py
• Image questions store image_path in the Question model
• Images served as static files by Flask in production

Common Development Patterns

Adding a New Model Field

1. Modify the model in backend/models.py
2. Update the model's to_dict() method if the field should be serialized
3. Create migration: uv run flask db migrate -m "Add field_name to Model"
4. Apply migration: uv run flask db upgrade

Adding a New WebSocket Event

1. Define event handler in backend/sockets/events.py using @socketio.on('event_name')
2. Use emit() to send responses or join_room()/leave_room() for room management
3. To broadcast to specific rooms, use emit('event', data, room='room_name')
4. Update frontend Socket.IO hook to listen for the new event

Adding a New API Endpoint

1. Add route function to appropriate blueprint in backend/routes/
2. Use db.session.commit() for database changes with try/except for rollback
3. Return JSON responses with appropriate status codes
4. For admin actions affecting game state, use functions from game_service.py to ensure WebSocket broadcasts

Important Notes

• Port 5000 conflict: macOS AirPlay Receiver uses port 5000 by default. Use PORT=5001 when running the backend.
• Nested frontend directory: Frontend source code is at frontend/frontend/, not frontend/src/
• Single active game: Only one game can be active at a time (enforced in start_game())
• Score uniqueness: A team can only have one score per question (enforced by database constraint)
• WebSocket server: Must use socketio.run(app) not app.run() for WebSocket support (configured in main.py)
• CORS: Configured to allow all origins in development via CORS_ORIGINS=*