# mduboef/pokerbot architecture

> Architecture diagram of the GitHub repository mduboef/pokerbot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mduboef/pokerbot
- Repository: https://github.com/mduboef/pokerbot

## Overview

##### Project Type and Components
- The README clearly explains how to create custom players by subclassing a BasePokerPlayer and details an example game file (example.py).

##### File Structure
- At the top level, files such as README.md, example.py, pokerBotPlayer.py, raise_player.py, randomplayer.py, and testperf.py suggest that these are sample or testing scripts for demonstrating the library’s use.
- The API layer (in pypokerengine/api): Files like emulator.py and game.py suggest these are responsible for exposing a set of endpoints or functions that users can call to initialize, run, and manage a game.
- The Engine layer (in pypokerengine/engine): This contains most of the core game logic. Modules such as dealer.py, deck.py, game_evaluator.py, hand_evaluator.py, round_manager.py, and others are responsible for the rules of the game, card operations, seating, and round management.
- Utility modules (in pypokerengine/utils): Provided for support in actions, card handling, game state tracking, visualizations, as well as handling timeouts.
- The modularity of the project suggests clear separation of concerns (API, engine, utilities) typical for a simulation engine.

##### Elements
- Each major folder (API, Engine, Utilities) as separate blocks.
- API Layer (emulator.py, game.py) ⇔ Custom Players (example, pokerBotPlayer, etc.)
- API Layer interacting with multiple Engine components (dealer, evaluator, etc.)
- Interconnections among Engine sub-components (dealer → deck, round_manager → seats, etc.)
- Utilities providing support functions to Engine (e.g., card_utils, timeout_decorator) and even to API if needed.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Custom Players
    subgraph "Custom Players"
        CP1["example.py"]:::sample
        CP2["pokerBotPlayer.py"]:::sample
        CP3["raise_player.py"]:::sample
        CP4["randomplayer.py"]:::sample
    end

    %% API Layer
    subgraph "API Layer"
        API1["emulator"]:::api
        API2["game"]:::api
    end

    %% Game Engine
    subgraph "Game Engine"
        subgraph "Dealer & Deck Management"
            E1["Dealer"]:::engine
            E2["Deck"]:::engine
        end
        subgraph "Evaluators"
            E3["Game Evaluator"]:::engine
            E4["Hand Evaluator"]:::engine
        end
        subgraph "Round Management"
            E5["Round Manager"]:::engine
            E6["Seats"]:::engine
        end
        subgraph "Additional Mechanics"
            E7["Action Checker"]:::engine
            E8["Card Module"]:::engine
            E9["Message Builder"]:::engine
            E10["Table"]:::engine
        end
        subgraph "Custom Player Interface"
            E11["BasePokerPlayer"]:::engine
            E12["Players Module"]:::engine
        end
    end

    %% Utilities
    subgraph "Utilities"
        U1["Action Utils"]:::util
        U2["Card Utils"]:::util
        U3["Game State Utils"]:::util
        U4["Timeout Decorator"]:::util
        U5["Visualize Utils"]:::util
    end

    %% Connections from Custom Players to API Layer
    CP1 -->|"calls"| API2
    CP2 -->|"calls"| API2
    CP3 -->|"calls"| API2
    CP4 -->|"calls"| API2

    %% Connections from API Layer to Game Engine
    API2 -->|"deals"| E1
    API2 -->|"manages_round"| E5
    API2 -->|"evaluates"| E3
    API2 -->|"evaluates_hand"| E4
    API2 -->|"builds_msg"| E9
    API2 -->|"interfaces"| E11

    %% Internal Game Engine Connections
    E1 -->|"uses"| E2
    E5 -->|"controls"| E6
    E3 -->|"consults"| E8
    E7 -->|"checks"| E8
    E11 -->|"registered_by"| E12
    E12 -->|"notifies"| CP1
    E12 --> CP2
    E12 --> CP3
    E12 --> CP4

    %% Utilities supporting Game Engine components
    U1 -->|"supports"| E7
    U2 -->|"supports"| E8
    U3 -->|"monitors"| E5
    U4 -->|"decorates"| E7
    U5 -->|"renders"| E10

    %% Click Events for Custom Players
    click CP1 "https://github.com/mduboef/pokerbot/blob/main/example.py"
    click CP2 "https://github.com/mduboef/pokerbot/blob/main/pokerBotPlayer.py"
    click CP3 "https://github.com/mduboef/pokerbot/blob/main/raise_player.py"
    click CP4 "https://github.com/mduboef/pokerbot/blob/main/randomplayer.py"

    %% Click Events for API Layer
    click API1 "https://github.com/mduboef/pokerbot/blob/main/pypokerengine/api/emulator.py"
    click API2 "https://github.com/mduboef/pokerbot/blob/main/pypokerengine/api/game.py"

    %% Click Events for Game Engine Components
    click E1 "https://github.com/mduboef/pokerbot/blob/main/pypokerengine/engine/dealer.py"
    click E2 "https://github.com/mduboef/pokerbot/blob/main/pypokerengine/engine/deck.py"
    click E3 "https://github.com/mduboef/pokerbot/blob/main/pypokerengine/engine/game_evaluator.py"
    click E4 "https://github.com/mduboef/pokerbot/blob/main/pypokerengine/engine/hand_evaluator.py"
    click E5 "https://github.com/mduboef/pokerbot/blob/main/pypokerengine/engine/round_manager.py"
    click E6 "https://github.com/mduboef/pokerbot/blob/main/pypokerengine/engine/seats.py"
    click E7 "https://github.com/mduboef/pokerbot/blob/main/pypokerengine/engine/action_checker.py"
    click E8 "https://github.com/mduboef/pokerbot/blob/main/pypokerengine/engine/card.py"
    click E9 "https://github.com/mduboef/pokerbot/blob/main/pypokerengine/engine/message_builder.py"
    click E10 "https://github.com/mduboef/pokerbot/blob/main/pypokerengine/engine/table.py"
    click E11 "https://github.com/mduboef/pokerbot/blob/main/pypokerengine/engine/player.py"
    click E12 "https://github.com/mduboef/pokerbot/blob/main/pypokerengine/players.py"

    %% Click Events for Utilities
    click U1 "https://github.com/mduboef/pokerbot/blob/main/pypokerengine/utils/action_utils.py"
    click U2 "https://github.com/mduboef/pokerbot/blob/main/pypokerengine/utils/card_utils.py"
    click U3 "https://github.com/mduboef/pokerbot/blob/main/pypokerengine/utils/game_state_utils.py"
    click U4 "https://github.com/mduboef/pokerbot/blob/main/pypokerengine/utils/timeout_decorator.py"
    click U5 "https://github.com/mduboef/pokerbot/blob/main/pypokerengine/utils/visualize_utils.py"

    %% Styling Classes
    classDef api fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef engine fill:#A9DFBF,stroke:#145A32,stroke-width:2px;
    classDef util fill:#F9E79F,stroke:#7D6608,stroke-width:2px;
    classDef sample fill:#F5B7B1,stroke:#78281F,stroke-width:2px;
```
