A server-authoritative No-Limit Texas Hold'em platform and C++ poker-AI research lab.

PokerArena combines a real-time multiplayer poker application with an experimental MCCFR engine. The web and iOS clients send player intent; the backend owns cards, legal actions, pots, showdown, persistence, and AI orchestration.

• 2–6 seat No-Limit Texas Hold'em rooms
• Account authentication and room-scoped WebSocket tickets
• Server-authoritative dealing, betting, side pots, showdown, and settlement
• Human players, AI seats, spectators, chat, reconnect, and control handoff
• Per-viewer hole-card privacy
• Raw hand histories plus derived VPIP, PFR, BB/100, and decision events
• Run-it-multiple support in the game engine
• React/TypeScript web table with responsive desktop and mobile layouts
• Optional iOS client/reference implementation

• C++20 MCCFR trainer and blueprint format
• Persistent C++ JSON decision server
• Hand-strength abstraction and public-state tooling
• Opponent profiling and guarded exploit experiments
• Bounded local-solving research code
• Reproducible training seeds, checkpoints, resource profiling, and artifact metadata
• Paired, rake-aware evaluation across multiple opponent profiles and seeds
• Exact Kuhn-poker convergence tests and runtime protocol tests

PokerArena deliberately separates working software from unproven poker strength.

• No trained model is committed to this repository.
• Without a compatible blueprint, the backend falls back to heuristic AI.
• A blueprint must match the engine version, public-state model, action abstraction, stack configuration, and adjacent metadata used to create it.
• Historical candidates that improved one opponent type while regressing others were rejected rather than promoted.
• Internal self-play is treated as diagnostic evidence, not proof that a model beats real NL50 players.

The detailed research record is in:

• doc/nl50-training-status.md — candidate results and promotion decisions
• doc/structural-diagnosis-2026-07-14.md — model/runtime mismatch investigation
• doc/external-decision-benchmark.md — requirements for independent evidence

                    HTTPS / WebSocket
┌────────────────┐                     ┌──────────────────────────┐
│ Web / iOS      │ ◄─────────────────► │ FastAPI backend          │
│ clients        │                     │                          │
└────────────────┘                     │ • auth and rooms         │
                                       │ • authoritative game     │
                                       │ • persistence and stats  │
                                       │ • AI orchestration       │
                                       └────────────┬─────────────┘
                                                    │ line-delimited JSON
                                                    ▼
                                       ┌──────────────────────────┐
                                       │ C++20 engine             │
                                       │                          │
                                       │ • blueprint lookup       │
                                       │ • MCCFR training         │
                                       │ • profiling / research   │
                                       │ • decision server        │
                                       └──────────────────────────┘

The backend is always authoritative. Clients never decide card order, action legality, pot distribution, or winners.

PokerArena/
├── backend/                 FastAPI, rooms, game engine, auth, stats, AI glue
│   ├── api/                 HTTP and WebSocket routes
│   ├── application/         Room and hand orchestration
│   ├── domain/              Transport-independent room rules
│   ├── game/                Hold'em state machine and settlement
│   ├── infrastructure/ai/   Persistent C++ decision client
│   └── tests/               Backend regression suite
├── frontend/                React 19 + TypeScript + Vite client
├── engine/                  C++20 trainer, runtime, probes, and tests
├── clients/ios/             iOS client/reference code
├── scripts/                 Training, evaluation, and diagnostic tools
├── doc/                     Architecture and research documentation
└── start.sh                 Local backend/frontend launcher

• Python 3.12 or newer
• Node.js 20 or newer
• CMake 3.20+ and a C++20 compiler only if building the native engine

git clone https://github.com/nullptr0807/PokerArena.git
cd PokerArena

python3 -m venv backend/.venv
source backend/.venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r backend/requirements.txt

cd frontend
npm ci
cd ..

source backend/.venv/bin/activate
cd backend
python -m uvicorn api.server:app --host 127.0.0.1 --port 8000 --reload

Check it:

curl http://127.0.0.1:8000/health

API documentation is available at http://127.0.0.1:8000/docs.

In a second terminal:

cd frontend
npm run dev -- --host 127.0.0.1 --port 3000

Open http://127.0.0.1:3000.

After installing both backend and frontend dependencies:

./start.sh

For a deployment mounted below /poker/ instead of /, set:

VITE_BASE_PATH=/poker/ ./start.sh

The development defaults use SQLite and an in-memory room registry.

cmake -S engine -B engine/build -DCMAKE_BUILD_TYPE=Release
cmake --build engine/build -j
ctest --test-dir engine/build --output-on-failure

Main binaries:

A model run normally contains:

engine/runs/<run-id>/
├── blueprint.bin
├── abstraction.bin
├── metadata.json
├── checkpoint_*.bin
└── training.log

engine/runs/ and *.bin are intentionally ignored. Do not copy an arbitrary blueprint into the runtime and assume compatibility; validate its metadata and run a decision/evaluation smoke first.

source backend/.venv/bin/activate
cd backend
python -m pip install pytest
python -m pytest -q

Current verified result: 272 passed, 16 skipped.

cd frontend
node --test tests/*.test.ts
npm audit --audit-level=high
npm run build

Current verified result: 24 tests passed, 0 known npm vulnerabilities, production build succeeded.

cmake --build engine/build -j
ctest --test-dir engine/build --output-on-failure

Current verified result: 3/3 CTest targets passed.

A higher average score is not enough. A candidate must be compared with the current baseline using:

1. the same cards, seats, opponent randomness, and rake;
2. all calibrated opponent profiles, not one favorable matchup;
3. multiple evaluation seeds;
4. multiple training seeds for newly trained strategies;
5. per-profile regression checks, not only an overall mean;
6. untouched holdout evaluation after development is complete;
7. runtime correctness, latency, memory, and strategy-sanity gates.

A candidate that improves one matchup by weakening another is recorded as an experiment, not promoted.

Generated and local-only data must stay out of Git:

• trained blueprints and checkpoints;
• engine/runs/ evaluation output;
• SQLite databases;
• hand logs;
• virtual environments and node_modules;
• CMake output and frontend dist;
• secrets and .env files.

If a model must be distributed, publish it through a separate artifact store with its metadata, engine revision, checksums, and evaluation report.

• doc/design.md — original product design and roadmap
• doc/multi-human-realtime-room-architecture.md — room, privacy, and realtime architecture
• doc/nl50-training-status.md — complete AI experiment log
• doc/structural-diagnosis-2026-07-14.md — structural training/runtime diagnosis
• doc/external-decision-benchmark.md — external benchmark contract

No open-source license is currently granted. Public source availability does not by itself grant permission to copy, modify, or redistribute the code.