316 lines
8.3 KiB
Markdown
316 lines
8.3 KiB
Markdown
# 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
|
||
|
||
```bash
|
||
git clone <repository-url>
|
||
cd trivia-thang
|
||
```
|
||
|
||
### 2. Install Python dependencies
|
||
|
||
```bash
|
||
uv sync
|
||
```
|
||
|
||
### 3. Initialize the database
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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):**
|
||
```bash
|
||
PORT=5001 uv run python main.py
|
||
```
|
||
This starts the Flask server on port 5001.
|
||
|
||
**Terminal 2 - Frontend (React):**
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
cd frontend
|
||
npm run build
|
||
```
|
||
|
||
This builds the React app to `backend/static/`.
|
||
|
||
### Run in Production
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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.
|