PokerTools is an enterprise-grade platform for building, deploying, and managing real-time Texas Hold'em poker applications. This monorepo contains the complete ecosystem, from the core game engine and hand evaluator to a full-featured API, Admin dashboard service, and client-side SDK.
The repository is organized into workspaces managed by NPM.
| Package | Description | Version |
|---|---|---|
| @pokertools/engine | The immutable core logic for Texas Hold'em state management. | 1.0.2 |
| @pokertools/evaluator | High-performance hand evaluation and win frequency calculation. | 1.0.2 |
| @pokertools/api | Scalable REST & WebSocket API built with Fastify, Redis, and PostgreSQL. | 1.0.2 |
| @pokertools/sdk | TypeScript SDK with React hooks and real-time socket management. | 1.0.2 |
| @pokertools/admin | Financial sweeper service, withdrawal processing, and Telegram bot. | 1.0.2 |
| @pokertools/types | Shared TypeScript definitions, Zod schemas, and DTOs. | 1.0.2 |
| @pokertools/bench | Performance benchmarking suite for the engine and evaluator. | 1.0.2 |
- Robust Game Engine: Handles complex side pots, all-in scenarios, and exact rake calculations. Verified with property-based testing.
- High Performance: Evaluator can process millions of hands per second.
- Scalable Infrastructure: API designed for horizontal scaling with Redis Pub/Sub and atomic database transactions.
- Financial Integrity: Double-entry ledger system for all chip movements.
- Blockchain Integration: Built-in support for crypto deposits and withdrawals (USDC/ETH) with automatic sweeping (admin service).
- Developer Experience: Fully typed SDK for rapid frontend development.
- Node.js: v20+
- NPM: v10+
- Docker (optional, for running Redis/Postgres locally)
-
Clone the repository:
git clone https://github.com/aaurelions/pokertools.git cd pokertools -
Install dependencies:
npm install
-
Build all packages:
npm run build
The monorepo provides root-level scripts to manage the lifecycle of all packages.
- Start API (Dev Mode):
npm run dev:api
- Run All Tests:
npm test - Run Benchmarks:
npm run bench
- Typecheck Entire Repo:
npm run typecheck
- Format Code:
npm run format
Most packages rely on environment variables. Copy the example files in each package to get started:
cp packages/api/.env.example packages/api/.env
cp packages/admin/.env.example packages/admin/.envSee individual package READMEs for specific configuration details.
We welcome contributions! Please see CONTRIBUTING.md for guidelines on how to submit pull requests, report issues, and setup your development environment.
Security is a top priority.
- Financials: All transfers are atomic and recorded in a ledger.
- Game Integrity: The engine is tested against millions of random scenarios.
- Vulnerabilities: Please report security issues via SECURITY.md.
This project is licensed under the MIT License - see the LICENSE file for details.