triviathang/README.md

Trivia Game Web App

A real-time trivia game application with Flask backend and React frontend, featuring WebSocket support for live score updates and question displays.

Features

• Question Bank Management: Create and manage text and image-based trivia questions
• Game Setup: Create games with selected questions and teams
• Contestant View: Full-screen TV display showing current question and live scoreboard
• Admin Control Panel: Control game flow, navigate questions, and award points
• Real-time Updates: WebSocket-powered instant updates across all views
• Multiple Game Support: Database supports multiple games with independent question sets

Architecture

• Backend: Flask + Flask-SocketIO + SQLAlchemy + SQLite
• Frontend: React + React Router + Socket.IO Client + Axios
• Real-time: WebSocket with room-based architecture (contestant/admin rooms)
• Dev Setup: Separate dev servers with Vite proxy
• Production: React builds to Flask static folder for single deployment unit

Project Structure

trivia-thang/
 backend/
    app.py                    # Flask application factory
    config.py                 # Configuration
    models.py                 # SQLAlchemy models
    routes/                   # API endpoints
       questions.py          # Question CRUD
       games.py              # Game management
       teams.py              # Team management
       admin.py              # Game control
    sockets/
       events.py             # WebSocket handlers
    services/
       game_service.py       # Game logic
       image_service.py      # Image uploads
    static/images/            # Uploaded question images
    instance/trivia.db        # SQLite database
 frontend/
    src/
       components/
          contestant/       # TV display components
          admin/            # Admin control panel
          questionbank/     # Question management
       hooks/
          useSocket.js      # WebSocket hook
       services/api.js       # API client
    vite.config.js
 main.py                       # Application entry point
 pyproject.toml               # Python dependencies

Prerequisites

• Python 3.14+
• Node.js 18+
• npm or yarn
• uv (Python package manager)

Installation

1. Clone the repository

git clone <repository-url>
cd trivia-thang

2. Install Python dependencies

uv sync

3. Initialize the database

export FLASK_APP=backend.app:create_app
uv run flask db init      # Only needed once
uv run flask db migrate
uv run flask db upgrade

4. Install Frontend dependencies

cd frontend
npm install
cd ..

Development Workflow

Running in Development

You need to run both the backend and frontend servers:

Terminal 1 - Backend (Flask + WebSocket):

PORT=5001 uv run python main.py

This starts the Flask server on port 5001.

Terminal 2 - Frontend (React):

cd frontend
npm run dev

This starts the Vite dev server on port 3000 with proxy to backend.

Access the Application

• Frontend: http://localhost:3000
• Backend API: http://localhost:5001/api
• Health Check: http://localhost:5001/api/health

Usage Guide

1. Create Questions

1. Navigate to "Question Bank Management"
2. Click "Add Question"
3. Choose question type (Text or Image)
4. Enter question content, upload image (if applicable), and provide answer
5. Click "Create Question"

2. Set Up a Game

1. Navigate to "Create New Game"
2. Enter a game name
3. Select questions to include (click to select/deselect)
4. Add team names
5. Click "Create Game & Go to Admin View"

3. Run the Game

On TV (Contestant View):

• Click "Open Contestant View" from admin panel
• Or navigate to: http://localhost:3000/games/{gameId}/contestant
• This displays questions and scores in real-time

On Admin Laptop:

• Use the admin view to control the game
• Click "Start Game" to begin
• Use "Next" / "Previous" to navigate questions
• Award points to teams using the +1, +2, +3, +5, +10, or -1 buttons
• Current question displays with the answer visible only to admin

4. Real-time Features

• Question changes appear instantly on contestant view
• Score updates broadcast immediately to all connected clients
• WebSocket connection status shown in both views

API Endpoints

Questions

• GET /api/questions - List all questions
• POST /api/questions - Create question (supports multipart/form-data for images)
• GET /api/questions/<id> - Get single question
• PUT /api/questions/<id> - Update question
• DELETE /api/questions/<id> - Delete question

Games

• GET /api/games - List all games
• POST /api/games - Create game
• GET /api/games/<id> - Get game details
• POST /api/games/<id>/questions - Add questions to game
• POST /api/games/<id>/teams - Add team to game
• DELETE /api/games/<id> - Delete game

Admin Controls

• POST /api/admin/game/<id>/start - Start/activate game
• POST /api/admin/game/<id>/next - Next question
• POST /api/admin/game/<id>/prev - Previous question
• POST /api/admin/game/<id>/award - Award points to team
• GET /api/admin/game/<id>/current - Get current game state with answer

Teams

• DELETE /api/teams/<id> - Delete team

WebSocket Events

Server ’ Client

• connected - Client connected successfully
• joined - Joined game room
• game_started - Game has started
• question_changed - New question (without answer, for contestants)
• question_with_answer - New question with answer (for admin)
• score_updated - Team score updated

Client ’ Server

• join_game - Join a game room with role (contestant/admin)
• leave_game - Leave a game room

Database Schema

• Question: id, type, question_content, answer, image_path, created_at
• Game: id, name, is_active, current_question_index, created_at
• GameQuestion: Links questions to games with ordering
• Team: id, name, game_id, created_at
• Score: team_id, game_id, question_index, points, awarded_at

Production Build

Build the Frontend

cd frontend
npm run build

This builds the React app to backend/static/.

Run in Production

FLASK_ENV=production PORT=5001 uv run python main.py

Flask will serve the built React app from the static folder.

Environment Variables

Create a .env file in the project root:

FLASK_ENV=development
SECRET_KEY=your-secret-key-here
PORT=5001
DATABASE_URI=sqlite:///instance/trivia.db
CORS_ORIGINS=*

Troubleshooting

Port 5000 Already in Use

The default port is 5000, but macOS AirPlay Receiver uses this port. Use PORT=5001 instead:

PORT=5001 uv run python main.py

WebSocket Connection Issues

• Ensure both Flask and React servers are running
• Check that Vite proxy is configured correctly in vite.config.js
• Verify firewall settings aren't blocking WebSocket connections

Database Migrations

If you modify models, create and apply migrations:

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

Frontend Not Loading

• Clear browser cache
• Check console for errors
• Verify all dependencies are installed: cd frontend && npm install

Future Enhancements

• Digital answer submission (architecture already supports it)
• Keyboard shortcuts for admin navigation (arrow keys)
• Audio/video question types
• Timer for questions
• Question categories and difficulty levels
• Game templates and presets
• Score history and analytics
• Authentication for admin access
• Multiple simultaneous games

Tech Stack Details

Backend

• Flask 3.0+: Web framework
• Flask-SocketIO 5.3+: WebSocket support
• Flask-SQLAlchemy 3.1+: ORM
• Flask-Migrate 4.0+: Database migrations
• Flask-CORS 4.0+: Cross-origin support
• Pillow 10.0+: Image processing
• Eventlet 0.36+: WebSocket server

Frontend

• React 19: UI library
• React Router 7: Client-side routing
• Socket.IO Client 4.8+: WebSocket client
• Axios 1.13+: HTTP client
• Vite 7: Build tool and dev server

License

MIT

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

Support

For issues or questions, please open an issue on the GitHub repository.