# zocketzero/poker-game-backend architecture

> Architecture diagram of the GitHub repository zocketzero/poker-game-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zocketzero/poker-game-backend
- Repository: https://github.com/zocketzero/poker-game-backend

## Overview

Poker Backend is a real-time Texas Hold’em server. Clients register or log in over REST, then authenticate a WebSocket session to browse/create tables, join seats, and play hands; game updates return over the socket. The lobby coordinates table actors, which wrap poker_engine and deliver private cards and public events. MongoDB persists users, chip balances, and hand histories. The README documents tournaments and full NLHE support; sampled excerpts show key session, lobby, table, and persistence paths, but not every route or game operation.

Main entry points: [`src/ws/handler.rs`](https://github.com/zocketzero/poker-game-backend/blob/main/src/ws/handler.rs) (Socket sessions), [`src/auth/auth_handlers.rs`](https://github.com/zocketzero/poker-game-backend/blob/main/src/auth/auth_handlers.rs) (Register and login), [`src/repositories/user_repository.rs`](https://github.com/zocketzero/poker-game-backend/blob/main/src/repositories/user_repository.rs) (User repository), [`src/game/table_actor.rs`](https://github.com/zocketzero/poker-game-backend/blob/main/src/game/table_actor.rs) (Game table actor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP and sessions"]
  node_server["HTTP server<br/>[main.rs]"]
  node_auth_route["Auth routes<br/>[auth_route.rs]"]
  node_ws_route["WebSocket route<br/>[ws_route.rs]"]
  node_ws_handler["Socket sessions<br/>[handler.rs]"]
  node_protocol["Socket protocol<br/>[messages.rs]"]
end

subgraph group_identity["Identity"]
  node_auth_handlers["Register and login<br/>[auth_handlers.rs]"]
  node_auth_dtos["Auth request types<br/>[auth_dtos.rs]"]
  node_username_rules["Username rules<br/>[regex.rs]"]
  node_jwt["JWT tokens<br/>[jwt_manager.rs]"]
  node_config["Configuration<br/>[config.rs]"]
end

subgraph group_play["Lobby and gameplay"]
  node_lobby["Table lobby<br/>[lobby.rs]"]
  node_table_actor["Game table actor<br/>[table_actor.rs]"]
  node_engine["poker_engine"]
end

subgraph group_persistence["Persistence"]
  node_repository["User repository<br/>[user_repository.rs]"]
  node_models["User and hand models<br/>[models.rs]"]
  node_collections["Collection names<br/>[collections.rs]"]
  node_connection["Mongo connection<br/>[connection.rs]"]
end

node_clients(("Players"))
node_mongodb[("MongoDB")]

node_clients -->|"HTTP requests"| node_server
node_server -->|"serves REST"| node_auth_route
node_server -->|"serves socket"| node_ws_route
node_auth_route -->|"routes auth"| node_auth_handlers
node_clients -->|"registers or logs in"| node_auth_handlers
node_auth_handlers -->|"accepts"| node_auth_dtos
node_auth_handlers -->|"validates names"| node_username_rules
node_auth_handlers -->|"creates or finds users"| node_repository
node_auth_handlers -->|"creates token"| node_jwt
node_ws_route -->|"upgrades connection"| node_ws_handler
node_clients -->|"connects with token"| node_ws_handler
node_ws_handler -->|"validates token"| node_jwt
node_ws_handler -->|"parses and sends"| node_protocol
node_ws_handler -->|"dispatches table requests"| node_lobby
node_ws_handler -->|"checks and updates chips"| node_repository
node_lobby -->|"manages tables"| node_table_actor
node_table_actor -.->|"runs poker game"| node_engine
node_table_actor -->|"emits game messages"| node_protocol
node_table_actor -->|"saves hand history"| node_repository
node_table_actor -->|"builds history records"| node_models
node_repository -->|"reads and writes"| node_models
node_repository -->|"uses collection name"| node_collections
node_repository -->|"persists documents"| node_mongodb
node_connection -.->|"connects"| node_mongodb

click node_server "https://github.com/zocketzero/poker-game-backend/blob/main/src/main.rs"
click node_auth_route "https://github.com/zocketzero/poker-game-backend/blob/main/src/routes/auth_route.rs"
click node_ws_route "https://github.com/zocketzero/poker-game-backend/blob/main/src/routes/ws_route.rs"
click node_ws_handler "https://github.com/zocketzero/poker-game-backend/blob/main/src/ws/handler.rs"
click node_protocol "https://github.com/zocketzero/poker-game-backend/blob/main/src/game/messages.rs"
click node_auth_handlers "https://github.com/zocketzero/poker-game-backend/blob/main/src/auth/auth_handlers.rs"
click node_auth_dtos "https://github.com/zocketzero/poker-game-backend/blob/main/src/auth/auth_dtos.rs"
click node_username_rules "https://github.com/zocketzero/poker-game-backend/blob/main/src/auth/regex.rs"
click node_jwt "https://github.com/zocketzero/poker-game-backend/blob/main/src/auth/jwt_manager.rs"
click node_config "https://github.com/zocketzero/poker-game-backend/blob/main/src/config.rs"
click node_lobby "https://github.com/zocketzero/poker-game-backend/blob/main/src/game/lobby.rs"
click node_table_actor "https://github.com/zocketzero/poker-game-backend/blob/main/src/game/table_actor.rs"
click node_repository "https://github.com/zocketzero/poker-game-backend/blob/main/src/repositories/user_repository.rs"
click node_models "https://github.com/zocketzero/poker-game-backend/blob/main/src/db/models.rs"
click node_collections "https://github.com/zocketzero/poker-game-backend/blob/main/src/db/collections.rs"
click node_connection "https://github.com/zocketzero/poker-game-backend/blob/main/src/db/connection.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_auth_route,node_ws_route,node_ws_handler,node_protocol toneBlue
class node_auth_handlers,node_auth_dtos,node_username_rules,node_jwt,node_config,node_mongodb toneAmber
class node_lobby,node_table_actor,node_engine toneMint
class node_repository,node_models,node_collections,node_connection toneRose
class node_clients toneIndigo
```

## Components

### HTTP and sessions

- [HTTP server](https://github.com/zocketzero/poker-game-backend/blob/main/src/main.rs): `src/main.rs`
- [Auth routes](https://github.com/zocketzero/poker-game-backend/blob/main/src/routes/auth_route.rs): `src/routes/auth_route.rs`
- [WebSocket route](https://github.com/zocketzero/poker-game-backend/blob/main/src/routes/ws_route.rs): `src/routes/ws_route.rs`
- [Socket sessions](https://github.com/zocketzero/poker-game-backend/blob/main/src/ws/handler.rs): `src/ws/handler.rs`
- [Socket protocol](https://github.com/zocketzero/poker-game-backend/blob/main/src/game/messages.rs): `src/game/messages.rs`

### Identity

- [Register and login](https://github.com/zocketzero/poker-game-backend/blob/main/src/auth/auth_handlers.rs): `src/auth/auth_handlers.rs`
- [Auth request types](https://github.com/zocketzero/poker-game-backend/blob/main/src/auth/auth_dtos.rs): `src/auth/auth_dtos.rs`
- [Username rules](https://github.com/zocketzero/poker-game-backend/blob/main/src/auth/regex.rs): `src/auth/regex.rs`
- [JWT tokens](https://github.com/zocketzero/poker-game-backend/blob/main/src/auth/jwt_manager.rs): `src/auth/jwt_manager.rs`
- [Configuration](https://github.com/zocketzero/poker-game-backend/blob/main/src/config.rs): `src/config.rs`

### Lobby and gameplay

- [Table lobby](https://github.com/zocketzero/poker-game-backend/blob/main/src/game/lobby.rs): `src/game/lobby.rs`
- [Game table actor](https://github.com/zocketzero/poker-game-backend/blob/main/src/game/table_actor.rs): `src/game/table_actor.rs`
- **poker_engine**

### Persistence

- [User repository](https://github.com/zocketzero/poker-game-backend/blob/main/src/repositories/user_repository.rs): `src/repositories/user_repository.rs`
- [User and hand models](https://github.com/zocketzero/poker-game-backend/blob/main/src/db/models.rs): `src/db/models.rs`
- [Collection names](https://github.com/zocketzero/poker-game-backend/blob/main/src/db/collections.rs): `src/db/collections.rs`
- [Mongo connection](https://github.com/zocketzero/poker-game-backend/blob/main/src/db/connection.rs): `src/db/connection.rs`

### Other components

- **Players**
- **MongoDB**

## Connections

- Players → HTTP server: HTTP requests (evidence: `README.md`)
- HTTP server → Auth routes: serves REST (evidence: `README.md`)
- HTTP server → WebSocket route: serves socket (evidence: `README.md`)
- Auth routes → Register and login: routes auth (evidence: `src/routes/auth_route.rs`)
- Players → Register and login: registers or logs in (evidence: `README.md`)
- Register and login → Auth request types: accepts (evidence: `src/auth/auth_handlers.rs`)
- Register and login → Username rules: validates names (evidence: `src/auth/auth_handlers.rs`)
- Register and login → User repository: creates or finds users (evidence: `src/auth/auth_handlers.rs`)
- Register and login → JWT tokens: creates token (evidence: `src/auth/auth_handlers.rs`)
- WebSocket route → Socket sessions: upgrades connection (evidence: `src/routes/ws_route.rs`)
- Players → Socket sessions: connects with token (evidence: `README.md`)
- Socket sessions → JWT tokens: validates token (evidence: `src/ws/handler.rs`)
- Socket sessions → Socket protocol: parses and sends (evidence: `src/ws/handler.rs`)
- Socket sessions → Table lobby: dispatches table requests (evidence: `src/ws/handler.rs`)
- Socket sessions → User repository: checks and updates chips (evidence: `src/ws/handler.rs`)
- Table lobby → Game table actor: manages tables (evidence: `src/game/lobby.rs`)
- Game table actor → poker_engine: runs poker game
- Game table actor → Socket protocol: emits game messages (evidence: `src/game/table_actor.rs`)
- Game table actor → User repository: saves hand history (evidence: `src/game/table_actor.rs`)
- Game table actor → User and hand models: builds history records (evidence: `src/game/table_actor.rs`)
- User repository → User and hand models: reads and writes (evidence: `src/repositories/user_repository.rs`)
- User repository → Collection names: uses collection name (evidence: `src/repositories/user_repository.rs`)
- User repository → MongoDB: persists documents (evidence: `src/repositories/user_repository.rs`)
- Mongo connection → MongoDB: connects
