A real-time poker game is a distributed system that handles real money and has strict turn timers. The card logic is the easy part. Most of the hard work goes into making every table survive crashes, retries, reconnects and scaling without paying a pot twice or freezing a hand.
This post walks through the decisions that mattered most while we built poker-cloud, the PokerInfra multiplayer platform. It also covers what we would tell any developer starting from scratch.
Why it is harder than it looks
A casual game can survive a dropped message or a lost timer. A poker table cannot:
- Money moves on every hand. A duplicated message can mean a double payout. A lost one can mean a stuck pot.
- Every action has a deadline. If a turn timer is lost during a restart, the table hangs and nine players wait for nothing.
- Each player sees a different game. Hole cards must never leave the server for anyone except their owner.
- Players drop all the time. Mobile networks flap, so disconnect handling is a core feature, not an edge case.
- Load is bursty. Tournaments start hundreds of tables in the same minute.
The big picture
Any game server can run any table: state lives outside the process
poker-cloud is a set of small services. Each one has a single job, and they talk over two channels: REST for account-style requests and MQTT for live table traffic.
Players reach the platform through REST (via the gateway) and MQTT (via the broker). Both check identity with the auth service. Game servers hold no table in memory: they take commands from the broker, load the table from Redis, apply the engine and publish what changed. Extensions only listen to the events.
The design decisions that matter most
1. Keep the rules in a pure engine library
The poker rules live in their own library, separate from any server, socket or database. The engine takes a game state and a player action, and returns the new state plus a list of state-change events (HandStarted, PlayerActed, PotAwarded and so on).
- Why: the same engine runs in the cloud servers, in tests and in replay tools. You can test thousands of seeded hands without starting any infrastructure.
- Inside the engine we use a state machine for the hand stages, the Strategy pattern for betting (no-limit, pot-limit) and showdown (standard, run-it-twice), and chained validators for each action.
- Hand evaluation sits behind an interface. That let us swap in our own evaluator later without touching the rules.
2. The server is the only source of truth
Clients send intentions (“I raise to $400”). The server checks them, applies them and broadcasts the result. A client never decides anything that affects money or cards.
- Two views of the same state: a private view for the server and each seat’s own cards, and a public view for everyone else. Opponents’ hole cards are not in any message until showdown.
- The server tells the client what it may do. It sends the list of valid actions with min and max amounts, so the client never re-implements betting rules.
- Shuffle on the server with a cryptographic random source. Never with
Math.random(), and never on the client.
3. Use a message broker for real-time, REST for everything else
We split the platform into two kinds of traffic:
- REST APIs for accounts, wallets, lobby lists and settings. They sit behind an API gateway that checks every request with the auth service first (an Nginx auth_request sub-request).
- MQTT for live game traffic, on a RabbitMQ cluster. Players subscribe to their table’s topic and to a private topic for their own cards. The broker checks topic permissions against the same auth service, so a player cannot subscribe to someone else’s cards.
A broker gives you fan-out, reconnects, retained messages and topic-level security out of the box. Writing your own WebSocket hub means rebuilding all of that.
4. Keep game servers stateless and the table state shared
No table lives in the memory of one process. Live table state sits in Redis, and every command loads it, applies the engine, saves it and publishes the events. Long-term records (players, wallets, hands, tournaments) go to PostgreSQL, behind its own DB service.
- Why: any game server can handle any table, so a crash does not take tables down with it. You scale by adding servers.
- Commands arrive through a shared work queue per game type (cash, tournament). Servers compete for messages, so load spreads by itself.
- A follow-up step is its own queue message. For example, “hand ended, start the next hand” is published as a new command before the current one is acknowledged. A crash between the two steps loses nothing.
5. Make every command safe to run twice
Message queues deliver at least once. Sooner or later a command will arrive twice, so double processing has to be harmless.
- One lock per table so two commands never change the same table at the same time.
- Compare-and-set saves with a version number, so a stale writer cannot overwrite newer state.
- A command ID on every message, recorded in the same atomic save, so a repeat is spotted and skipped.
- Check money paths first. In our audit, the double-payout risks were all in the same few shapes: crediting a wallet before the state is committed, toggles, and writes that span several keys.
6. Timers must be durable
Turn timers, time banks, disconnect grace periods and tournament blind levels drive the game. Our first version used Redis key-expiry notifications. These are fire-and-forget: a timer that expired while a server was restarting was simply gone, and the table hung.
We replaced them with a durable due-queue: a sorted set where the score is the fire time.
- Servers poll every few hundred milliseconds for due timers.
- A server claims a timer by pushing its time forward (a lease) and deletes it only after the work succeeds. If the server dies mid-way, the timer becomes due again and another server runs it.
- Recovery after a restart is just the first poll. No special resume code is needed.
If you take one thing from this post, take this one. Lost timers are the most common cause of hung tables.
7. Treat connection state as a separate service
A heartbeat service tracks ping and pong for each client and decides when a player is online, disconnected or gone. Game servers react to its events (sit the player out, start the disconnect time bank) instead of guessing from socket errors.
On reconnect, the client should rebuild from the current table state, not from the events it remembers. Never rely on a client having seen every message.
8. Put non-game features in extensions
Hand history, real-time results, chat and live streaming are not part of the game loop. They are extensions that listen to the game’s domain events and do their own work.
- Why: the core stays small and well tested. A slow history writer can never delay a player’s turn.
- Order matters for listeners too. Each event carries a sequence number per table, so an extension can detect gaps and out-of-order delivery.
9. One service, one job
Each service does one thing: auth, database access, lobby, game, heartbeat, gateway. Every external dependency (Redis, the broker, the evaluator) sits behind an interface and is injected through the constructor. That is what made it possible to swap the timer store or the hand evaluator without rewriting the game.
We also share one types package across all services and the client. When an event shape changes, the compiler finds every place that breaks.
10. Be able to replay any hand
Every log line carries the table ID and hand ID, and the logs are collected centrally. When a player disputes a pot, we can replay that exact hand, step by step, in Grafana. Build this before launch, not after the first support ticket.
Advice if you are starting from scratch
- Write the engine first, with no network at all. Get no-limit hold’em right, including side pots, all-ins, split pots and odd chips, with hundreds of tests. Then add a second variant to prove your abstractions.
- Store chips as integers. Use the smallest unit (cents, or chips) everywhere. Decide early who gets the odd chip in a split pot, and write it down.
- Do not write your own hand evaluator unless you have to. Use a proven library behind an interface. Test showdowns against known results, especially Omaha’s two-plus-three rule.
- Make the server authoritative from the first line of code. Retrofitting authority onto a client-driven prototype is a rewrite.
- Assume every message arrives twice, late or never. Design commands to be safe to repeat before you add a second server, not after.
- Make timers durable on day one. It costs little at the start and is painful to change later.
- Use a real broker for real-time traffic. MQTT or a similar protocol gives you topics, permissions and reconnect handling for free.
- Start as a single box, but stay stateless. One machine with Docker Compose is enough for your first few hundred players. Keep state out of process memory, and scaling out later is a config change.
- Kill your servers on purpose. Restart a game server in the middle of a hand, drop a player’s network during their turn, and run two servers on the same table. Each of these tests found real bugs for us.
- Log and replay from the start. Tag every log line with table and hand IDs. Disputes and bug reports become a lookup instead of a guess.
- Keep extras out of the game loop. Chat, history, stats and leaderboards should listen to events, not sit inside the turn path.
- Plan for compliance as a setting. Rake, limits, geo rules and audit needs differ by market. Make them configuration, not code branches.
Closing
The shape that works is simple to describe: a pure rules engine, an authoritative and stateless server fleet, shared state with locks, durable timers, a broker for live traffic, and extensions for everything else. The hard part is being strict about it on every code path that touches money or time.
PokerInfra builds poker-cloud on this design for operators who want a white-label or source-code platform. If you are building your own, we hope these notes save you a few rewrites. Questions are welcome at pokerinfra.com.