406 lines
12 KiB
Markdown
406 lines
12 KiB
Markdown
# Jackbox Party Pack Game Picker
|
|
|
|
A full-stack web application that helps groups pick games to play from various Jackbox Party Packs. Features include random game selection with filters, session tracking, game management, and popularity scoring through chat log imports.
|
|
|
|
## Features
|
|
|
|
### Progressive Web App (PWA)
|
|
- **Installable**: Add to home screen on mobile and desktop devices
|
|
- **Offline Support**: Service worker provides offline functionality
|
|
- **Native Experience**: Runs like a native app when installed
|
|
- **Auto-updates**: Seamlessly updates to new versions
|
|
|
|
### Admin Features
|
|
- **Game Picker**: Randomly select games with intelligent filters
|
|
- Filter by player count, drawing games, game length, and family-friendly status
|
|
- Automatic repeat avoidance (prevents same game or alternating pattern)
|
|
- Manual game selection option
|
|
- Real-time session tracking
|
|
|
|
- **Game Manager**: Complete CRUD operations for games and packs
|
|
- Enable/disable individual games or entire packs
|
|
- Import/export games via CSV
|
|
- View statistics (play counts, popularity scores)
|
|
- Add, edit, and delete games
|
|
|
|
- **Session Management**: Track gaming sessions over time
|
|
- Create and close sessions
|
|
- View session history
|
|
- Import chat logs to calculate game popularity
|
|
- Track which games were played when
|
|
|
|
- **Chat Log Import**: Process chat messages to assess game popularity
|
|
- Supports "thisgame++" and "thisgame--" voting
|
|
- Automatically matches votes to games based on timestamps
|
|
- Updates popularity scores across sessions
|
|
|
|
### Public Features
|
|
- View active session and games currently being played
|
|
- Browse session history
|
|
- See game statistics and popularity
|
|
|
|
## Tech Stack
|
|
|
|
- **Frontend**: React 18 with Vite, Tailwind CSS, React Router
|
|
- **Backend**: Node.js with Express
|
|
- **Database**: SQLite with better-sqlite3
|
|
- **Authentication**: JWT-based admin authentication
|
|
- **Deployment**: Docker with docker-compose
|
|
|
|
## Prerequisites
|
|
|
|
- Docker and Docker Compose (recommended)
|
|
- OR Node.js 18+ and npm (for local development)
|
|
|
|
## Quick Start with Docker
|
|
|
|
1. **Clone the repository**
|
|
```bash
|
|
git clone <repository-url>
|
|
cd jackboxpartypack-gamepicker
|
|
```
|
|
|
|
2. **Create environment file**
|
|
|
|
Create a `.env` file in the root directory:
|
|
```env
|
|
PORT=5000
|
|
NODE_ENV=production
|
|
DB_PATH=/app/data/jackbox.db
|
|
JWT_SECRET=your-secret-jwt-key-change-this
|
|
ADMIN_KEY=your-admin-key-here
|
|
```
|
|
|
|
3. **Build and start the containers**
|
|
```bash
|
|
docker-compose up -d
|
|
```
|
|
|
|
4. **Access the application**
|
|
- Frontend: http://localhost:3000
|
|
- Backend API: http://localhost:5000
|
|
|
|
5. **Login as admin**
|
|
- Navigate to the login page
|
|
- Enter your `ADMIN_KEY` from the `.env` file
|
|
|
|
The database will be automatically initialized and populated with games from `games-list.csv` on first run.
|
|
|
|
## Local Development Setup
|
|
|
|
### Backend Setup
|
|
|
|
1. **Navigate to backend directory**
|
|
```bash
|
|
cd backend
|
|
```
|
|
|
|
2. **Install dependencies**
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
3. **Create environment file**
|
|
|
|
Create `backend/.env`:
|
|
```env
|
|
PORT=5000
|
|
DB_PATH=./data/jackbox.db
|
|
JWT_SECRET=your-secret-jwt-key
|
|
ADMIN_KEY=admin123
|
|
```
|
|
|
|
4. **Start the backend server**
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
The backend will run on http://localhost:5000
|
|
|
|
### Frontend Setup
|
|
|
|
1. **Navigate to frontend directory**
|
|
```bash
|
|
cd frontend
|
|
```
|
|
|
|
2. **Install dependencies**
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
3. **Start the development server**
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
The frontend will run on http://localhost:3000 and proxy API requests to the backend.
|
|
|
|
## Configuration
|
|
|
|
### Branding and Metadata
|
|
|
|
All app branding, metadata, and PWA configuration is centralized in `frontend/src/config/branding.js`. Edit this file to customize:
|
|
|
|
- **App Name** and **Short Name** - Displayed in UI and when installed as PWA
|
|
- **Description** - Shown in search engines and app stores
|
|
- **Version** - Current app version
|
|
- **Theme Color** - Primary color for browser chrome and PWA theme
|
|
- **Keywords** - SEO metadata
|
|
- **Author** - Creator/maintainer information
|
|
- **Links** - GitHub repo, support contact, etc.
|
|
|
|
When you update `branding.js`, the following are automatically synchronized:
|
|
|
|
1. **PWA Manifest** (`manifest.json`) - Generated at build time via `generate-manifest.js`
|
|
2. **HTML Meta Tags** - Updated via Vite HTML transformation plugin
|
|
3. **App UI** - Components import branding directly
|
|
|
|
To regenerate the manifest manually:
|
|
```bash
|
|
cd frontend
|
|
npm run generate-manifest
|
|
```
|
|
|
|
The manifest is automatically generated during the build process, so you don't need to edit it directly.
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
/
|
|
├── backend/
|
|
│ ├── routes/ # API route handlers
|
|
│ │ ├── auth.js # Authentication endpoints
|
|
│ │ ├── games.js # Game CRUD and management
|
|
│ │ ├── sessions.js # Session management
|
|
│ │ ├── picker.js # Game picker algorithm
|
|
│ │ └── stats.js # Statistics endpoints
|
|
│ ├── middleware/ # Express middleware
|
|
│ │ └── auth.js # JWT authentication
|
|
│ ├── database.js # SQLite database setup
|
|
│ ├── bootstrap.js # Database initialization
|
|
│ ├── server.js # Express app entry point
|
|
│ ├── package.json
|
|
│ └── Dockerfile
|
|
├── frontend/
|
|
│ ├── src/
|
|
│ │ ├── pages/ # React page components
|
|
│ │ │ ├── Home.jsx
|
|
│ │ │ ├── Login.jsx
|
|
│ │ │ ├── Picker.jsx
|
|
│ │ │ ├── Manager.jsx
|
|
│ │ │ └── History.jsx
|
|
│ │ ├── context/ # React context providers
|
|
│ │ │ └── AuthContext.jsx
|
|
│ │ ├── api/ # API client
|
|
│ │ │ └── axios.js
|
|
│ │ ├── App.jsx
|
|
│ │ ├── main.jsx
|
|
│ │ └── index.css
|
|
│ ├── index.html
|
|
│ ├── vite.config.js
|
|
│ ├── tailwind.config.js
|
|
│ ├── package.json
|
|
│ ├── nginx.conf # Nginx config for Docker
|
|
│ └── Dockerfile
|
|
├── docker-compose.yml
|
|
├── games-list.csv # Initial game data
|
|
└── README.md
|
|
```
|
|
|
|
## API Endpoints
|
|
|
|
### Authentication
|
|
- `POST /api/auth/login` - Login with admin key
|
|
- `POST /api/auth/verify` - Verify JWT token
|
|
|
|
### Games
|
|
- `GET /api/games` - List all games (with filters)
|
|
- `GET /api/games/:id` - Get single game
|
|
- `POST /api/games` - Create game (admin)
|
|
- `PUT /api/games/:id` - Update game (admin)
|
|
- `DELETE /api/games/:id` - Delete game (admin)
|
|
- `PATCH /api/games/:id/toggle` - Toggle game enabled status (admin)
|
|
- `GET /api/games/meta/packs` - Get pack list with stats
|
|
- `PATCH /api/games/packs/:name/toggle` - Toggle entire pack (admin)
|
|
- `GET /api/games/export/csv` - Export games to CSV (admin)
|
|
- `POST /api/games/import/csv` - Import games from CSV (admin)
|
|
|
|
### Sessions
|
|
- `GET /api/sessions` - List all sessions
|
|
- `GET /api/sessions/active` - Get active session
|
|
- `GET /api/sessions/:id` - Get single session
|
|
- `POST /api/sessions` - Create new session (admin)
|
|
- `POST /api/sessions/:id/close` - Close session (admin)
|
|
- `GET /api/sessions/:id/games` - Get games in session
|
|
- `POST /api/sessions/:id/games` - Add game to session (admin)
|
|
- `POST /api/sessions/:id/chat-import` - Import chat log (admin)
|
|
|
|
### Game Picker
|
|
- `POST /api/pick` - Pick random game with filters
|
|
|
|
### Statistics
|
|
- `GET /api/stats` - Get overall statistics
|
|
|
|
## Usage Guide
|
|
|
|
### Starting a Game Session
|
|
|
|
1. Login as admin
|
|
2. Navigate to the Picker page
|
|
3. A new session will be created automatically if none exists
|
|
4. Set filters (player count, drawing preference, length, family-friendly)
|
|
5. Click "Roll the Dice" to get a random game
|
|
6. Review the suggested game and either:
|
|
- Click "Play This Game" to accept
|
|
- Click "Re-roll" to get a different game
|
|
7. The game is added to the session and play count is incremented
|
|
|
|
### Managing Games
|
|
|
|
1. Login as admin
|
|
2. Navigate to the Manager page
|
|
3. View statistics and pack information
|
|
4. Toggle individual games or entire packs on/off
|
|
5. Add new games with the "+ Add Game" button
|
|
6. Edit or delete existing games
|
|
7. Import/Export games via CSV
|
|
|
|
### Closing a Session and Importing Chat Logs
|
|
|
|
1. Navigate to the History page
|
|
2. Select the active session
|
|
3. Click "Import Chat Log"
|
|
4. Paste JSON array of chat messages with format:
|
|
```json
|
|
[
|
|
{
|
|
"username": "Alice",
|
|
"message": "thisgame++",
|
|
"timestamp": "2024-10-30T20:15:00Z"
|
|
},
|
|
{
|
|
"username": "Bob",
|
|
"message": "This is fun! thisgame++",
|
|
"timestamp": "2024-10-30T20:16:30Z"
|
|
}
|
|
]
|
|
```
|
|
5. The system will match votes to games based on timestamps
|
|
6. Click "Close Session" to finalize
|
|
7. Add optional notes about the session
|
|
|
|
## Chat Log Format
|
|
|
|
The chat import feature expects a JSON array where each message has:
|
|
- `username`: String - Name of the chatter
|
|
- `message`: String - The chat message (may contain "thisgame++" or "thisgame--")
|
|
- `timestamp`: String - ISO 8601 timestamp
|
|
|
|
The system will:
|
|
1. Parse each message for vote patterns
|
|
2. Match the timestamp to the game being played at that time
|
|
3. Update the game's popularity score (+1 for ++, -1 for --)
|
|
4. Store the chat log in the database
|
|
|
|
## Database Schema
|
|
|
|
### games
|
|
- id, pack_name, title, min_players, max_players, length_minutes
|
|
- has_audience, family_friendly, game_type, secondary_type
|
|
- play_count, popularity_score, enabled, created_at
|
|
|
|
### sessions
|
|
- id, created_at, closed_at, is_active, notes
|
|
|
|
### session_games
|
|
- id, session_id, game_id, played_at, manually_added
|
|
|
|
### chat_logs
|
|
- id, session_id, chatter_name, message, timestamp, parsed_vote
|
|
|
|
## Game Selection Algorithm
|
|
|
|
The picker uses the following logic:
|
|
|
|
1. **Filter eligible games**:
|
|
- Only enabled games
|
|
- Match player count range (if specified)
|
|
- Filter by drawing type (if specified)
|
|
- Filter by length range (if specified)
|
|
- Filter by family-friendly status (if specified)
|
|
|
|
2. **Apply repeat avoidance**:
|
|
- Get last 2 games from current session
|
|
- Exclude those games from selection pool
|
|
- This prevents immediate repeats and alternating patterns
|
|
|
|
3. **Random selection**:
|
|
- Pick a random game from remaining eligible games
|
|
- Return game details and pool size
|
|
|
|
## Docker Deployment
|
|
|
|
### Using Docker Compose
|
|
|
|
The provided `docker-compose.yml` sets up both frontend and backend services:
|
|
|
|
```bash
|
|
# Build and start
|
|
docker-compose up -d
|
|
|
|
# View logs
|
|
docker-compose logs -f
|
|
|
|
# Stop services
|
|
docker-compose down
|
|
|
|
# Rebuild after changes
|
|
docker-compose up -d --build
|
|
```
|
|
|
|
### Environment Variables
|
|
|
|
Set these in your `.env` file or docker-compose environment:
|
|
|
|
- `PORT` - Backend server port (default: 5000)
|
|
- `NODE_ENV` - Environment (production/development)
|
|
- `DB_PATH` - Path to SQLite database file
|
|
- `JWT_SECRET` - Secret key for JWT tokens
|
|
- `ADMIN_KEY` - Admin authentication key
|
|
|
|
### Data Persistence
|
|
|
|
The SQLite database is stored in `backend/data/` and is persisted via Docker volumes. To backup your data, copy the `backend/data/` directory.
|
|
|
|
## Troubleshooting
|
|
|
|
### Database not initializing
|
|
- Ensure `games-list.csv` is in the root directory
|
|
- Check backend logs: `docker-compose logs backend`
|
|
- Manually delete `backend/data/jackbox.db` to force re-initialization
|
|
|
|
### Can't login as admin
|
|
- Verify your `ADMIN_KEY` environment variable is set
|
|
- Check that the `.env` file is loaded correctly
|
|
- Try restarting the backend service
|
|
|
|
### Frontend can't reach backend
|
|
- Verify both containers are running: `docker-compose ps`
|
|
- Check network connectivity: `docker-compose logs frontend`
|
|
- Ensure nginx.conf proxy settings are correct
|
|
|
|
### Games not showing up
|
|
- Check if games are enabled in the Manager
|
|
- Verify filters aren't excluding all games
|
|
- Check database has games: View in Manager page
|
|
|
|
## License
|
|
|
|
MIT
|
|
|
|
## Contributing
|
|
|
|
Feel free to submit issues and pull requests!
|
|
|