# dheirav/nashforge architecture

> Architecture diagram of the GitHub repository dheirav/nashforge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dheirav/nashforge
- Repository: https://github.com/dheirav/nashforge
- Video tour (about a minute): https://gitdiagram.com/dheirav/nashforge/video

## Overview

NashForge is a heads-up no-limit Hold’em bot centered on abstracted-game CFR solving. Its main path is game rules and card/betting abstraction into a solver, then a stack-depth strategy ladder into arena action selection. The README also describes alternative evolutionary and PPO agents, benchmark instruments, opponent profiling, and river re-solving. Several subsystems are documented but not sampled, so their internal wiring is shown only where the README supports it.

Main entry points: [`engine/game.py`](https://github.com/dheirav/nashforge/blob/main/engine/game.py) (Hold’em rules), [`chipzen/player.py`](https://github.com/dheirav/nashforge/blob/main/chipzen/player.py) (Arena player), [`native/src/nolimit.hpp`](https://github.com/dheirav/nashforge/blob/main/native/src/nolimit.hpp) (Native game), [`games/nolimit.py`](https://github.com/dheirav/nashforge/blob/main/games/nolimit.py) (Abstract no-limit)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_game["Poker game"]
  node_engine["Hold’em rules<br/>[game.py]"]
  node_cards["Cards and evaluation<br/>[hand_eval.py]"]
  node_abstraction["Card abstraction<br/>[buckets.py]"]
  node_betting["Bet schedules<br/>[betting.py]"]
  node_abstract_game["Abstract no-limit<br/>[nolimit.py]"]
end

subgraph group_solver["CFR solving"]
  node_trainer["Training entry<br/>[train_nolimit.py]"]
  node_native_game["Native game<br/>[nolimit.hpp]"]
  node_native_solver["MCCFR core<br/>[mccfr.hpp]"]
  node_bindings["Python bindings<br/>[bindings.cpp]"]
  node_python_cfr["Python CFR solvers<br/>[mccfr.py]"]
  node_river["River re-solver<br/>[river.py]"]
end

subgraph group_learning["Alternative learning"]
  node_evolution["Evolution search<br/>[evolution.py]"]
  node_fitness["Self-play fitness<br/>[fitness.py]"]
  node_ppo_trainer["PPO trainer<br/>[trainer.py]"]
  node_ppo_env["Poker environment<br/>[poker_env.py]"]
end

subgraph group_runtime["Bot runtime"]
  node_ladder["Strategy tables<br/>[flat.py]"]
  node_chip_player["Arena player<br/>[player.py]"]
  node_opponent_reads["Opponent profiling<br/>[opponents.py]"]
  node_arena_client["Arena client<br/>[client.py]"]
  node_chipzen(("Chipzen arena"))
  node_slumbot["Slumbot bridge<br/>[bridge.py]"]
end

subgraph group_measurement["Evaluation"]
  node_benchmark["Benchmark loop"]
  node_viewer["Interactive viewer<br/>[game_controller.py]"]
end

node_trainer -->|"trains through"| node_native_solver
node_bindings -->|"exposes"| node_native_solver
node_native_solver -->|"traverses"| node_native_game
node_native_game -->|"buckets hands"| node_abstraction
node_native_game -->|"uses schedules"| node_betting
node_abstract_game -->|"buckets hands"| node_abstraction
node_abstract_game -->|"uses rules"| node_engine
node_engine -->|"evaluates hands"| node_cards
node_trainer -->|"configures"| node_abstraction
node_python_cfr -->|"traverses"| node_abstract_game
node_river -.->|"re-solves from"| node_ladder
node_chip_player -->|"selects strategy"| node_ladder
node_chip_player -->|"adjusts using"| node_opponent_reads
node_arena_client -->|"requests actions"| node_chip_player
node_arena_client -->|"connects to"| node_chipzen
node_slumbot -.->|"bridges strategy"| node_chip_player
node_evolution -->|"evaluates genomes"| node_fitness
node_fitness -->|"plays hands"| node_engine
node_ppo_trainer -->|"collects transitions"| node_ppo_env
node_ppo_env -->|"steps game"| node_engine
node_benchmark -->|"scores strategy"| node_ladder
node_viewer -->|"plays hands"| node_engine

click node_trainer "https://github.com/dheirav/nashforge/blob/main/scripts/cfr/train_nolimit.py"
click node_engine "https://github.com/dheirav/nashforge/blob/main/engine/game.py"
click node_cards "https://github.com/dheirav/nashforge/blob/main/engine/hand_eval.py"
click node_abstraction "https://github.com/dheirav/nashforge/blob/main/abstraction/buckets.py"
click node_betting "https://github.com/dheirav/nashforge/blob/main/abstraction/betting.py"
click node_abstract_game "https://github.com/dheirav/nashforge/blob/main/games/nolimit.py"
click node_native_game "https://github.com/dheirav/nashforge/blob/main/native/src/nolimit.hpp"
click node_native_solver "https://github.com/dheirav/nashforge/blob/main/native/src/mccfr.hpp"
click node_bindings "https://github.com/dheirav/nashforge/blob/main/native/src/bindings.cpp"
click node_python_cfr "https://github.com/dheirav/nashforge/blob/main/cfr/mccfr.py"
click node_river "https://github.com/dheirav/nashforge/blob/main/cfr/river.py"
click node_ladder "https://github.com/dheirav/nashforge/blob/main/cfr/flat.py"
click node_chip_player "https://github.com/dheirav/nashforge/blob/main/chipzen/player.py"
click node_opponent_reads "https://github.com/dheirav/nashforge/blob/main/chipzen/opponents.py"
click node_arena_client "https://github.com/dheirav/nashforge/blob/main/chipzen/client.py"
click node_slumbot "https://github.com/dheirav/nashforge/blob/main/slumbot/bridge.py"
click node_evolution "https://github.com/dheirav/nashforge/blob/main/training/evolution.py"
click node_fitness "https://github.com/dheirav/nashforge/blob/main/training/fitness.py"
click node_ppo_trainer "https://github.com/dheirav/nashforge/blob/main/rl/ppo/trainer.py"
click node_ppo_env "https://github.com/dheirav/nashforge/blob/main/rl/poker_env.py"
click node_benchmark "https://github.com/dheirav/nashforge/tree/main/evaluation"
click node_viewer "https://github.com/dheirav/nashforge/blob/main/gui/game_controller.py"

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_engine,node_cards,node_abstraction,node_betting,node_abstract_game toneBlue
class node_trainer,node_native_game,node_native_solver,node_bindings,node_python_cfr,node_river toneAmber
class node_evolution,node_fitness,node_ppo_trainer,node_ppo_env toneMint
class node_ladder,node_chip_player,node_opponent_reads,node_arena_client,node_chipzen,node_slumbot toneRose
class node_benchmark,node_viewer toneIndigo
```

## Components

### Poker game

- [Hold’em rules](https://github.com/dheirav/nashforge/blob/main/engine/game.py): `engine/game.py`
- [Cards and evaluation](https://github.com/dheirav/nashforge/blob/main/engine/hand_eval.py): `engine/hand_eval.py`
- [Card abstraction](https://github.com/dheirav/nashforge/blob/main/abstraction/buckets.py): `abstraction/buckets.py`
- [Bet schedules](https://github.com/dheirav/nashforge/blob/main/abstraction/betting.py): `abstraction/betting.py`
- [Abstract no-limit](https://github.com/dheirav/nashforge/blob/main/games/nolimit.py): `games/nolimit.py`

### CFR solving

- [Training entry](https://github.com/dheirav/nashforge/blob/main/scripts/cfr/train_nolimit.py): `scripts/cfr/train_nolimit.py`
- [Native game](https://github.com/dheirav/nashforge/blob/main/native/src/nolimit.hpp): `native/src/nolimit.hpp`
- [MCCFR core](https://github.com/dheirav/nashforge/blob/main/native/src/mccfr.hpp): `native/src/mccfr.hpp`
- [Python bindings](https://github.com/dheirav/nashforge/blob/main/native/src/bindings.cpp): `native/src/bindings.cpp`
- [Python CFR solvers](https://github.com/dheirav/nashforge/blob/main/cfr/mccfr.py): `cfr/mccfr.py`
- [River re-solver](https://github.com/dheirav/nashforge/blob/main/cfr/river.py): `cfr/river.py`

### Alternative learning

- [Evolution search](https://github.com/dheirav/nashforge/blob/main/training/evolution.py): `training/evolution.py`
- [Self-play fitness](https://github.com/dheirav/nashforge/blob/main/training/fitness.py): `training/fitness.py`
- [PPO trainer](https://github.com/dheirav/nashforge/blob/main/rl/ppo/trainer.py): `rl/ppo/trainer.py`
- [Poker environment](https://github.com/dheirav/nashforge/blob/main/rl/poker_env.py): `rl/poker_env.py`

### Bot runtime

- [Strategy tables](https://github.com/dheirav/nashforge/blob/main/cfr/flat.py): `cfr/flat.py`
- [Arena player](https://github.com/dheirav/nashforge/blob/main/chipzen/player.py): `chipzen/player.py`
- [Opponent profiling](https://github.com/dheirav/nashforge/blob/main/chipzen/opponents.py): `chipzen/opponents.py`
- [Arena client](https://github.com/dheirav/nashforge/blob/main/chipzen/client.py): `chipzen/client.py`
- **Chipzen arena**
- [Slumbot bridge](https://github.com/dheirav/nashforge/blob/main/slumbot/bridge.py): `slumbot/bridge.py`

### Evaluation

- [Benchmark loop](https://github.com/dheirav/nashforge/tree/main/evaluation): `evaluation`
- [Interactive viewer](https://github.com/dheirav/nashforge/blob/main/gui/game_controller.py): `gui/game_controller.py`

## Connections

- Training entry → MCCFR core: trains through
- Python bindings → MCCFR core: exposes
- MCCFR core → Native game: traverses
- Native game → Card abstraction: buckets hands
- Native game → Bet schedules: uses schedules
- Abstract no-limit → Card abstraction: buckets hands
- Abstract no-limit → Hold’em rules: uses rules
- Hold’em rules → Cards and evaluation: evaluates hands
- Training entry → Card abstraction: configures
- Python CFR solvers → Abstract no-limit: traverses
- River re-solver → Strategy tables: re-solves from
- Arena player → Strategy tables: selects strategy
- Arena player → Opponent profiling: adjusts using
- Arena client → Arena player: requests actions
- Arena client → Chipzen arena: connects to
- Slumbot bridge → Arena player: bridges strategy
- Evolution search → Self-play fitness: evaluates genomes
- Self-play fitness → Hold’em rules: plays hands
- PPO trainer → Poker environment: collects transitions
- Poker environment → Hold’em rules: steps game
- Benchmark loop → Strategy tables: scores strategy
- Interactive viewer → Hold’em rules: plays hands