jackboxpartypack-gamepicker/README.md

# 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

- **Live Voting API**: Real-time vote processing from external bots
  - Accept live votes via REST API
  - Real-time `vote.received` WebSocket event for stream overlays
  - Per-session vote breakdown and paginated global vote history
  - Automatic deduplication (1-second window)
  - Timestamp-based game matching
  - JWT authentication for security

- **Webhook System**: Notify external services of events
  - Send notifications when games are added to sessions
  - HMAC-SHA256 signature verification
  - Webhook management (CRUD operations)
  - Delivery logging and testing

### 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
│   │   ├── votes.js      # Live voting endpoint
│   │   └── webhooks.js   # Webhook management
│   ├── middleware/       # Express middleware
│   │   └── auth.js       # JWT authentication
│   ├── utils/            # Utility functions
│   │   └── webhooks.js   # Webhook trigger and signature
│   ├── 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
- `GET /api/sessions/:id/votes` - Get per-game vote breakdown for a 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

### Votes
- `GET /api/votes` - Paginated vote history with filtering
- `POST /api/votes/live` - Submit real-time vote (admin)

### Webhooks
- `GET /api/webhooks` - List all webhooks (admin)
- `GET /api/webhooks/:id` - Get single webhook (admin)
- `POST /api/webhooks` - Create webhook (admin)
- `PATCH /api/webhooks/:id` - Update webhook (admin)
- `DELETE /api/webhooks/:id` - Delete webhook (admin)
- `POST /api/webhooks/test/:id` - Test webhook (admin)
- `GET /api/webhooks/:id/logs` - Get webhook logs (admin)

## 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

## Bot Integration

For integrating external bots (e.g., for live voting and game notifications), see **[BOT_INTEGRATION.md](docs/BOT_INTEGRATION.md)** for detailed documentation including:

- Live voting API usage
- **WebSocket integration (recommended)** for real-time game notifications
- Webhook setup and verification (alternative to WebSocket)
- Example implementations in Node.js and Go
- Security best practices

## Jackbox Player Count Fetcher

The `scripts/` directory contains utilities for inspecting Jackbox game lobbies:

- **[get-player-count.go](scripts/get-player-count.go)** - Go + chromedp script (recommended, most reliable)
- **[get-player-count.html](scripts/get-player-count.html)** - Browser-based tool (no installation required!)
- **[get-jackbox-player-count.js](scripts/get-jackbox-player-count.js)** - Node.js script (limited, may not work)

See **[scripts/README.md](scripts/README.md)** for detailed usage instructions.

### Quick Start

**Go version (recommended for automation):**
```bash
cd scripts
go run get-player-count.go JYET
```

**Browser version (easiest for manual testing):**
1. Open `scripts/get-player-count.html` in any browser
2. Enter a 4-letter room code
3. View real-time player count and lobby status

**How it works:**
- Automates joining jackbox.tv through Chrome/Chromium
- Captures WebSocket messages containing player data
- Extracts actual player count from lobby state

These tools retrieve:
- ✅ Actual player count (not just max capacity)
- ✅ List of current players and their roles (host/player)
- ✅ Game state and lobby status  
- ✅ Audience count

**Note:** Direct WebSocket connection is not possible without authentication, so the tools join through jackbox.tv to capture the data.

## 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, upvotes, downvotes, enabled, created_at

### sessions
- id, created_at, closed_at, is_active, notes

### session_games
- id, session_id, game_id, played_at, manually_added, status

### chat_logs
- id, session_id, chatter_name, message, timestamp, parsed_vote, message_hash

### live_votes
- id, session_id, game_id, username, vote_type, timestamp, created_at

### webhooks
- id, name, url, secret, events, enabled, created_at

### webhook_logs
- id, webhook_id, event_type, payload, response_status, error_message, created_at

## 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!