Bookdle Platform

A daily book guessing game with multi-user support, authentication, and administrative tools.

Repository Structure

bookdle-platform/
├── game/                       # Main bookdle game frontend
├── reviewer/                   # Book reviewer interface (public)
├── admin/                      # Admin panel (protected)
├── backend/                    # Go API server
├── database/                   # Database schemas and migrations
├── .github/workflows/          # CI/CD pipelines
└── docker-compose.yml          # Local development setup

Services

Game (game/)

• Description: Daily puzzle game where users guess books from their first sentence
• Tech: React 19, TypeScript, Vite
• Features: OIDC authentication, progressive hints, game history tracking
• Port: 3002 (development)

Reviewer (reviewer/)

• Description: Public interface for contributing book data
• Tech: React 18, TypeScript, Vite
• Features: Add book information, mark books as completed
• Port: 3000 (development)

Admin (admin/)

• Description: Administrative panel for managing puzzles and books
• Tech: React 18, TypeScript, Vite
• Features: Review pending puzzles, confirm and schedule puzzles, manage books
• Port: 3001 (development)

Backend (backend/)

• Description: API server for all services
• Tech: Go 1.23, Gorilla Mux, PostgreSQL
• Features: OIDC authentication, JWT tokens, game state management, book management
• Port: 8080

Database

• Type: PostgreSQL 18
• Port: 5432

Quick Start

Prerequisites

• Docker and Docker Compose
• Node.js 22+ (for local development)
• Go 1.23+ (for local development)
• PostgreSQL 18 (or use Docker)

Development Setup

1. Clone the repository:

git clone https://github.com/loganintech/bookdle-platform.git
cd bookdle-platform

2. Start all services with Docker Compose:

docker-compose up

3. Access the services:

• Game: http://localhost:3002
• Reviewer: http://localhost:3000
• Admin: http://localhost:3001
• API: http://localhost:8080

Environment Variables

Create a .env file in the root directory:

# Database
DB_HOST=localhost
DB_PORT=5432
DB_NAME=bookdle
DB_USER=postgres
DB_PASSWORD=your_password

# Backend
PORT=8080
JWT_SECRET=your_jwt_secret_key

# OAuth - Discord
DISCORD_CLIENT_ID=your_discord_client_id
DISCORD_CLIENT_SECRET=your_discord_client_secret
DISCORD_REDIRECT_URL=http://localhost:3002/auth/callback

# OAuth - Google
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
GOOGLE_REDIRECT_URL=http://localhost:3002/auth/callback

Development Workflow

Running Individual Services

Backend:

cd backend
go run main.go

Game:

cd game
npm install
npm run dev

Reviewer:

cd reviewer
npm install
npm run dev

Admin:

cd admin
npm install
npm run dev

Database Migrations

Run migrations manually:

psql -U postgres -d bookdle -f database/schema.sql
psql -U postgres -d bookdle -f database/migrations/001_add_hard_to_find.sql
psql -U postgres -d bookdle -f database/migrations/002_add_user_tables.sql

Deployment

CI/CD

GitHub Actions automatically builds and publishes Docker images on push to main:

• game/** → ghcr.io/loganintech/bookdle-game:latest
• reviewer/** → ghcr.io/loganintech/bookdle-reviewer:latest
• admin/** → ghcr.io/loganintech/bookdle-admin:latest
• backend/** → ghcr.io/loganintech/bookdle-backend:latest

Production Deployment

Pull and run the latest images:

docker-compose -f docker-compose.prod.yml up -d

Architecture

┌─────────────────────────────────────────────────────┐
│                 User's Browser                      │
│                                                     │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐        │
│  │  Game    │  │ Reviewer │  │  Admin   │        │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘        │
└───────┼─────────────┼─────────────┼───────────────┘
        │             │             │
        └─────────────┴─────────────┘
                      │
              ┌───────▼────────┐
              │  Go Backend    │
              │  (Port 8080)   │
              └───────┬────────┘
                      │
              ┌───────▼────────┐
              │   PostgreSQL   │
              └────────────────┘

Tech Stack

• Frontend: React 18/19, TypeScript, Vite
• Backend: Go 1.23, Gorilla Mux
• Database: PostgreSQL 18
• Auth: OIDC (Discord, Google)
• Deployment: Docker, GitHub Actions, Kubernetes

License

MIT