# freddyyandrews/poker-hackathon-kit architecture

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

- Interactive diagram: https://gitdiagram.com/freddyyandrews/poker-hackathon-kit
- Repository: https://github.com/freddyyandrews/poker-hackathon-kit
- Video tour (about a minute): https://gitdiagram.com/freddyyandrews/poker-hackathon-kit/video

## Overview

This is a No-Limit Texas Hold’em bot hackathon kit: users supply a bot, then play matches against it and inspect results. The main runtime path is play.py → Table → hand engine, with Table requesting decisions through seats and BotProcess. The core also provides blind schedules, deterministic seeding, sandbox execution and bot validation. The README documents tournament use and sandbox constraints; the supplied excerpts do not show the full match setup or every validator and process detail, so those connections are limited to visible references.

Main entry points: [`play.py`](https://github.com/freddyyandrews/poker-hackathon-kit/blob/main/play.py) (Match launcher), [`pokercore/table.py`](https://github.com/freddyyandrews/poker-hackathon-kit/blob/main/pokercore/table.py) (Table and match), [`pokercore/sandbox/runner.py`](https://github.com/freddyyandrews/poker-hackathon-kit/blob/main/pokercore/sandbox/runner.py) (Bot protocol runner), [`pokercore/botproc.py`](https://github.com/freddyyandrews/poker-hackathon-kit/blob/main/pokercore/botproc.py) (Bot process)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_match["Match Runtime"]
  node_play["Match launcher<br/>[play.py]"]
  node_table["Table and match<br/>[table.py]"]
  node_engine["Poker engine<br/>[engine.py]"]
  node_blinds["Blind structures<br/>[structures.py]"]
  node_seeds["Seed derivation<br/>[seeds.py]"]
  node_seats["Player seats<br/>[seats.py]"]
end

subgraph group_bots["Bot Execution"]
  node_template["Bot template<br/>[bot.py]"]
  node_caller["Caller bot<br/>[bot.py]"]
  node_process["Bot process<br/>[botproc.py]"]
  node_runner["Bot protocol runner<br/>[runner.py]"]
end

subgraph group_safety["Sandbox and Validation"]
  node_guard["Local confinement<br/>[guard.py]"]
  node_validator["Bot validator<br/>[validator.py]"]
end

node_user(("Kit user"))

node_user -->|"starts match"| node_play
node_user -->|"customizes"| node_template
node_play -->|"runs match"| node_table
node_play -->|"builds seats"| node_seats
node_play -->|"configures blinds"| node_blinds
node_play -->|"chooses seed"| node_seeds
node_table -->|"gets levels"| node_blinds
node_table -->|"derives hand seeds"| node_seeds
node_table -->|"plays hand"| node_engine
node_table -->|"requests actions"| node_seats
node_seats -->|"starts and queries"| node_process
node_process -->|"runs bot protocol"| node_runner
node_runner -->|"confines process"| node_guard
node_process -->|"installs local guard"| node_guard
node_runner -->|"loads bot"| node_template
node_runner -->|"loads bot"| node_caller
node_user -->|"validates bot"| node_validator
node_validator -->|"uses confinement"| node_guard

click node_play "https://github.com/freddyyandrews/poker-hackathon-kit/blob/main/play.py"
click node_table "https://github.com/freddyyandrews/poker-hackathon-kit/blob/main/pokercore/table.py"
click node_engine "https://github.com/freddyyandrews/poker-hackathon-kit/blob/main/pokercore/engine.py"
click node_blinds "https://github.com/freddyyandrews/poker-hackathon-kit/blob/main/pokercore/structures.py"
click node_seeds "https://github.com/freddyyandrews/poker-hackathon-kit/blob/main/pokercore/seeds.py"
click node_seats "https://github.com/freddyyandrews/poker-hackathon-kit/blob/main/pokercore/seats.py"
click node_template "https://github.com/freddyyandrews/poker-hackathon-kit/blob/main/bots/template/bot.py"
click node_caller "https://github.com/freddyyandrews/poker-hackathon-kit/blob/main/bots/caller/bot.py"
click node_process "https://github.com/freddyyandrews/poker-hackathon-kit/blob/main/pokercore/botproc.py"
click node_runner "https://github.com/freddyyandrews/poker-hackathon-kit/blob/main/pokercore/sandbox/runner.py"
click node_guard "https://github.com/freddyyandrews/poker-hackathon-kit/blob/main/pokercore/sandbox/guard.py"
click node_validator "https://github.com/freddyyandrews/poker-hackathon-kit/blob/main/pokercore/validator.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_play,node_table,node_engine,node_blinds,node_seeds,node_seats,node_user toneBlue
class node_template,node_caller,node_process,node_runner toneAmber
class node_guard,node_validator toneMint
```

## Components

### Match Runtime

- [Match launcher](https://github.com/freddyyandrews/poker-hackathon-kit/blob/main/play.py): `play.py`
- [Table and match](https://github.com/freddyyandrews/poker-hackathon-kit/blob/main/pokercore/table.py): `pokercore/table.py`
- [Poker engine](https://github.com/freddyyandrews/poker-hackathon-kit/blob/main/pokercore/engine.py): `pokercore/engine.py`
- [Blind structures](https://github.com/freddyyandrews/poker-hackathon-kit/blob/main/pokercore/structures.py): `pokercore/structures.py`
- [Seed derivation](https://github.com/freddyyandrews/poker-hackathon-kit/blob/main/pokercore/seeds.py): `pokercore/seeds.py`
- [Player seats](https://github.com/freddyyandrews/poker-hackathon-kit/blob/main/pokercore/seats.py): `pokercore/seats.py`

### Bot Execution

- [Bot template](https://github.com/freddyyandrews/poker-hackathon-kit/blob/main/bots/template/bot.py): `bots/template/bot.py`
- [Caller bot](https://github.com/freddyyandrews/poker-hackathon-kit/blob/main/bots/caller/bot.py): `bots/caller/bot.py`
- [Bot process](https://github.com/freddyyandrews/poker-hackathon-kit/blob/main/pokercore/botproc.py): `pokercore/botproc.py`
- [Bot protocol runner](https://github.com/freddyyandrews/poker-hackathon-kit/blob/main/pokercore/sandbox/runner.py): `pokercore/sandbox/runner.py`

### Sandbox and Validation

- [Local confinement](https://github.com/freddyyandrews/poker-hackathon-kit/blob/main/pokercore/sandbox/guard.py): `pokercore/sandbox/guard.py`
- [Bot validator](https://github.com/freddyyandrews/poker-hackathon-kit/blob/main/pokercore/validator.py): `pokercore/validator.py`

### Other components

- **Kit user**

## Connections

- Kit user → Match launcher: starts match (evidence: `README.md`)
- Kit user → Bot template: customizes (evidence: `README.md`)
- Match launcher → Table and match: runs match (evidence: `play.py`)
- Match launcher → Player seats: builds seats (evidence: `play.py`)
- Match launcher → Blind structures: configures blinds (evidence: `play.py`)
- Match launcher → Seed derivation: chooses seed (evidence: `play.py`)
- Table and match → Blind structures: gets levels (evidence: `pokercore/table.py`)
- Table and match → Seed derivation: derives hand seeds (evidence: `pokercore/table.py`)
- Table and match → Poker engine: plays hand (evidence: `pokercore/table.py`)
- Table and match → Player seats: requests actions (evidence: `pokercore/table.py`)
- Player seats → Bot process: starts and queries (evidence: `pokercore/seats.py`)
- Bot process → Bot protocol runner: runs bot protocol (evidence: `pokercore/botproc.py`)
- Bot protocol runner → Local confinement: confines process (evidence: `pokercore/sandbox/runner.py`)
- Bot process → Local confinement: installs local guard (evidence: `pokercore/botproc.py`)
- Bot protocol runner → Bot template: loads bot (evidence: `README.md`)
- Bot protocol runner → Caller bot: loads bot (evidence: `README.md`)
- Kit user → Bot validator: validates bot (evidence: `README.md`)
- Bot validator → Local confinement: uses confinement (evidence: `pokercore/validator.py`)
