Developer Overview

Welcome to the Poker Engine developer guide. This documentation is for developers who want to understand, extend, or contribute to the codebase.

Prerequisites

Software	Version	Purpose
Node.js	20.19+	Runtime
npm	10.x+	Package manager
Docker	24.x+	PostgreSQL container
Git	2.x+	Version control

Quick Start

# 1. Clone and install
git clone <repository-url>
cd poker-engine
npm install          # Root install covers the client and packages/* workspaces

# 2. Start PostgreSQL
docker compose up -d postgres

# 3. Configure environment
cp .env.example .env
# Edit .env — the placeholder secrets are rejected at startup; see setup.md

# 4. Set up the database
npm run db:generate
npm run db:migrate
npm run db:seed

# 5. Start development servers
npm run dev          # Backend: http://localhost:3000
npm run dev:client   # Frontend: http://localhost:5173

Verify Installation

curl http://localhost:3000/health   # "status" is "ok" when healthy
npm test                            # Run the test suite
npm run typecheck                   # Type-check backend, scripts and workspaces

Guide Index

Core Development

Guide	Contents
Setup	Docker, environment variables, database, IDE config
Architecture	Layer overview, tech stack, data flow, directory structure
Game Engine	Cards, hand evaluation, state machine, pot management, all variants
API Development	REST routes, Zod validation, response format, error handling, middleware
WebSocket Development	Connection lifecycle, typed events, pipeline, broadcasting, client hooks
Database	Prisma operations, migrations, transactions, schema conventions, seeding
Testing	Vitest, unit/integration tests, property-based testing, mocking

Feature Systems

Guide	Contents
Tournament Engine	MTT, Sit & Go, Satellite, rule profiles, audits, compliance scenarios
Bot System	Bot architecture, strategy profiles, identity pool, scheduler
Frontend	React components, Zustand store, WebSocket hooks, Vite config
Integration API	Developer API, external user sync, JWT authentication
Player Sessions	Session lifecycle, table tracking, stats, orphan healing
Payment Providers	Stripe, CoinPayments, BTCPay Server, PayPal, Skrill, Neteller, MuchBetter, ecoPayz, bank transfer

Infrastructure & Ops

Guide	Contents
Security	Authentication, CSRF, rate limiting, KYC, 2FA
Configuration	Admin Panel settings, DB-backed config, feature flags
Extension Guide	Adding variants, payment providers, bot strategies
Monorepo	Shared packages, workspace structure, mobile app
CI/CD & Releases	GitHub Actions, Docker, release workflow, versioning

Key Concepts

• Game settings are in the database, not env vars. SMTP, rake, buy-in limits, feature flags — all managed via the Admin Panel.
• Environment variables are validated at startup via Zod (src/config/env-schema.ts, loaded by src/config/env.ts). Missing required vars will crash on startup.
• WebSocket events flow through a typed pipeline (validation → authorization → rate limiting → idempotency, then the event handler and its broadcasts).
• Poker variants each have a dedicated evaluator registered in HandEvaluatorFactory. To add a new variant, register a new evaluator there.
• Tournament procedure claims must match the active rule profiles and the deterministic compliance matrix in src/game/verification/tournament-compliance.ts. See Tournament Engine and Gameplay Verification Suite.

---

Last Updated: October 2026