# matusgib/fullhouse-engine architecture

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

- Interactive diagram: https://gitdiagram.com/matusgib/fullhouse-engine
- Repository: https://github.com/matusgib/fullhouse-engine

## Overview

Fullhouse Engine is a local No-Limit Texas Hold’em bot competition kit: authors provide a bot that turns a game-state request into an action, and the match runtime advances hands and reports results. The README also describes a live demo and tournament simulation; training scripts and the CFR bot’s bundled blueprint support strategy development and play. The match loop and bot protocol are supported by sampled source; some demo, tournament, and training links are based on README descriptions and the file tree.

Main entry points: [`sandbox/match.py`](https://github.com/matusgib/fullhouse-engine/blob/main/sandbox/match.py) (Match orchestrator), [`sandbox/runner.py`](https://github.com/matusgib/fullhouse-engine/blob/main/sandbox/runner.py) (Bot runner), [`bots/template/bot.py`](https://github.com/matusgib/fullhouse-engine/blob/main/bots/template/bot.py) (Submitted bot), [`demo.py`](https://github.com/matusgib/fullhouse-engine/blob/main/demo.py) (Live demo UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Match runtime"]
  node_match["Match orchestrator<br/>[match.py]"]
  node_engine["Poker engine<br/>[game.py]"]
  node_runner["Bot runner<br/>[runner.py]"]
  node_validator["Submission validator<br/>[validator.py]"]
end

subgraph group_bots["Bot strategies"]
  node_bot["Submitted bot<br/>[bot.py]"]
  node_reference["Reference bots"]
  node_cfrbot["CFR blueprint bot<br/>[bot.py]"]
  node_blueprint["CFR data"]
end

subgraph group_demo["Demo and tournament"]
  node_demo["Live demo UI<br/>[demo.py]"]
  node_tournament["Tournament rules<br/>[tournament.py]"]
end

subgraph group_research["Strategy training"]
  node_kuhn["Kuhn CFR training<br/>[cfr_kuhn.py]"]
  node_leduc["Leduc CFR training<br/>[cfr_leduc.py]"]
  node_holdem["Hold’em training<br/>[holdem_train.py]"]
  node_abstraction["Hold’em abstraction"]
end

node_author(("Bot author"))
node_matchactor(("Match participant"))

node_author -->|"implements"| node_bot
node_author -.->|"validates locally"| node_validator
node_match -->|"starts process"| node_runner
node_runner -->|"loads and queries"| node_bot
node_match -->|"creates and advances"| node_engine
node_engine -->|"returns state"| node_match
node_match -->|"sends state"| node_runner
node_runner -->|"returns action"| node_match
node_matchactor -->|"runs match"| node_match
node_validator -->|"checks submission"| node_bot
node_demo -->|"runs matches"| node_match
node_demo -->|"runs tournament"| node_tournament
node_tournament -.->|"coordinates rounds"| node_match
node_kuhn -.->|"reuses CFR approach"| node_leduc
node_holdem -.->|"uses abstraction"| node_abstraction
node_cfrbot -->|"loads strategy data"| node_blueprint

click node_match "https://github.com/matusgib/fullhouse-engine/blob/main/sandbox/match.py"
click node_engine "https://github.com/matusgib/fullhouse-engine/blob/main/engine/game.py"
click node_runner "https://github.com/matusgib/fullhouse-engine/blob/main/sandbox/runner.py"
click node_validator "https://github.com/matusgib/fullhouse-engine/blob/main/sandbox/validator.py"
click node_bot "https://github.com/matusgib/fullhouse-engine/blob/main/bots/template/bot.py"
click node_reference "https://github.com/matusgib/fullhouse-engine/tree/main/bots"
click node_cfrbot "https://github.com/matusgib/fullhouse-engine/blob/main/bots/fullhouse_cfr/bot.py"
click node_blueprint "https://github.com/matusgib/fullhouse-engine/tree/main/bots/fullhouse_cfr/data"
click node_demo "https://github.com/matusgib/fullhouse-engine/blob/main/demo.py"
click node_tournament "https://github.com/matusgib/fullhouse-engine/blob/main/engine/tournament.py"
click node_kuhn "https://github.com/matusgib/fullhouse-engine/blob/main/training/cfr_kuhn.py"
click node_leduc "https://github.com/matusgib/fullhouse-engine/blob/main/training/cfr_leduc.py"
click node_holdem "https://github.com/matusgib/fullhouse-engine/blob/main/training/holdem_train.py"
click node_abstraction "https://github.com/matusgib/fullhouse-engine/blob/main/training/holdem_abstraction.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_match,node_engine,node_runner,node_validator toneBlue
class node_bot,node_reference,node_cfrbot,node_blueprint toneAmber
class node_demo,node_tournament toneMint
class node_kuhn,node_leduc,node_holdem,node_abstraction toneRose
class node_author,node_matchactor toneIndigo
```

## Components

### Match runtime

- [Match orchestrator](https://github.com/matusgib/fullhouse-engine/blob/main/sandbox/match.py): `sandbox/match.py`
- [Poker engine](https://github.com/matusgib/fullhouse-engine/blob/main/engine/game.py): `engine/game.py`
- [Bot runner](https://github.com/matusgib/fullhouse-engine/blob/main/sandbox/runner.py): `sandbox/runner.py`
- [Submission validator](https://github.com/matusgib/fullhouse-engine/blob/main/sandbox/validator.py): `sandbox/validator.py`

### Bot strategies

- [Submitted bot](https://github.com/matusgib/fullhouse-engine/blob/main/bots/template/bot.py): `bots/template/bot.py`
- [Reference bots](https://github.com/matusgib/fullhouse-engine/tree/main/bots): `bots`
- [CFR blueprint bot](https://github.com/matusgib/fullhouse-engine/blob/main/bots/fullhouse_cfr/bot.py): `bots/fullhouse_cfr/bot.py`
- [CFR data](https://github.com/matusgib/fullhouse-engine/tree/main/bots/fullhouse_cfr/data): `bots/fullhouse_cfr/data`

### Demo and tournament

- [Live demo UI](https://github.com/matusgib/fullhouse-engine/blob/main/demo.py): `demo.py`
- [Tournament rules](https://github.com/matusgib/fullhouse-engine/blob/main/engine/tournament.py): `engine/tournament.py`

### Strategy training

- [Kuhn CFR training](https://github.com/matusgib/fullhouse-engine/blob/main/training/cfr_kuhn.py): `training/cfr_kuhn.py`
- [Leduc CFR training](https://github.com/matusgib/fullhouse-engine/blob/main/training/cfr_leduc.py): `training/cfr_leduc.py`
- [Hold’em training](https://github.com/matusgib/fullhouse-engine/blob/main/training/holdem_train.py): `training/holdem_train.py`
- [Hold’em abstraction](https://github.com/matusgib/fullhouse-engine/blob/main/training/holdem_abstraction.py): `training/holdem_abstraction.py`

### Other components

- **Bot author**
- **Match participant**

## Connections

- Bot author → Submitted bot: implements
- Bot author → Submission validator: validates locally
- Match orchestrator → Bot runner: starts process
- Bot runner → Submitted bot: loads and queries
- Match orchestrator → Poker engine: creates and advances
- Poker engine → Match orchestrator: returns state
- Match orchestrator → Bot runner: sends state
- Bot runner → Match orchestrator: returns action
- Match participant → Match orchestrator: runs match
- Submission validator → Submitted bot: checks submission
- Live demo UI → Match orchestrator: runs matches
- Live demo UI → Tournament rules: runs tournament
- Tournament rules → Match orchestrator: coordinates rounds
- Kuhn CFR training → Leduc CFR training: reuses CFR approach
- Hold’em training → Hold’em abstraction: uses abstraction
- CFR blueprint bot → CFR data: loads strategy data