# weedbox/pokerface architecture

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

- Interactive diagram: https://gitdiagram.com/weedbox/pokerface
- Repository: https://github.com/weedbox/pokerface

## Overview

##### Project type and purpose
- pokerface is a Go‑based poker game engine library.
- It provides all the core logic to simulate poker games: deck management, dealing, action order, hand evaluation, pot handling, player settlement, match orchestration, and higher‑level competition flows.
- It is intended to be embedded in other applications (e.g., bots, servers) or used stand‑alone for testing poker rules.

##### File structure
- Top‑level files (action.go, deck.go, event.go, game.go, pokerface.go, etc.) define the core domain objects and main entry point.
- Domain sub‑packages:
- combination: card, hand evaluation
- pot: pot construction and side‑pots
- settlement:-ranking and payout settlement
- regulator: gameplay rules enforcement
- seat_manager: seat allocation
- Orchestration sub‑packages:
- match: single poker match runner, seat queue, table backend
- competition: higher‑level tournament or match sequences, state management
- actor: adapter interfaces & runners for automated/bot players
- table: abstractions for in‑memory or native backends to hold table state
- Configuration and extension points via adapters (native_table_adapter, table_engine_adapter) for pluggable table backends.

##### README

- Core Engine
- Game Controller (game.go, game_state.go, game_options.go)
- Event Dispatcher (event.go)
- Domain Logic
- Combination Engine (combination/)
- Pot Manager (pot/)
- Settlement Engine (settlement/)
- Regulator (regulator/)
- Seat Manager (seat_manager/)
- Match Layer
- Match Runner & Queue (match/)
- Competition Layer
- Competition Manager (competition/)
- Adapters & Interfaces
- Table Backends (table/, actor/native_table_adapter.go, adapter.go)
- Bot/Observer Runners (actor/)
- External Integrations
- Bot processes, test harnesses, external UI or API servers (not included but you’d plug in here)

- Game Controller calls Regulator → updates Table Backend → emits Events
- Event Dispatcher notifies Match Runner → triggers Pot Manager & Settlement at showdown
- Match Runner uses Seat Manager to add/remove players
- Competition Manager sequences multiple Match Runners
- Combination Engine invoked by Settlement & Regulator for hand ranking
- Adapters implement Table Backend interface, injecting into Match Runner

c. Architectural patterns & design principles
- Layered architecture: Domain → Match → Competition
- Dependency inversion: table backends & actor runners are injected via adapters
- Single Responsibility: each package handles one area (hand evaluation, pot, settlement)
- Domain‑driven: domain objects (Action, Player, Table, Pot, Rank)

d. Key technologies/frameworks
- Go modules (go.mod)
- Built‑in testing framework ( *_test.go files)
- Interface‑based adapters for pluggability

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Core Domain Layer
    subgraph "Core Engine"
        direction TB
        PublicAPI["Public API\n(pokerface.go)"]:::coreEngine
        GameController["Game Controller\n(game.go, game_state.go,\n game_options.go)"]:::coreEngine
        EventDispatcher["Event Dispatcher\n(event.go)"]:::coreEngine
        DeckManager["Deck Manager\n(deck.go)"]:::coreEngine
        ActionPlayer["Actions & Player\n(action.go, player.go)"]:::coreEngine
    end

    %% Domain Logic Layer
    subgraph "Domain Logic"
        direction TB
        CombinationEngine["Combination Engine\n(combination/)"]:::domainLogic
        PotManager["Pot Manager\n(pot/)"]:::domainLogic
        SettlementEngine["Settlement Engine\n(settlement/)"]:::domainLogic
        Regulator["Regulator\n(regulator/)"]:::domainLogic
        SeatManager["Seat Manager\n(seat_manager/)"]:::domainLogic
    end

    %% Match Layer
    subgraph "Match Layer"
        direction TB
        MatchRunnerQueue["Match Runner & Queue\n(match/)"]:::orchestration
    end

    %% Competition Layer
    subgraph "Competition Layer"
        direction TB
        CompetitionManager["Competition Manager\n(competition/)"]:::orchestration
    end

    %% Adapters & Interfaces Layer
    subgraph "Adapters & Interfaces"
        direction TB
        TableBackend["Table Backend Interfaces\n(table/)"]:::adapter
        ActorInterfaces["Actor Interfaces & Runners\n(actor/)"]:::adapter
    end

    %% Relationships
    PublicAPI -->|"calls NewGame() / NewController()"| GameController
    GameController -->|"invoke Regulator"| Regulator
    GameController -->|"manage deck"| DeckManager
    GameController -->|"manage actions/players"| ActionPlayer
    GameController -->|"emit events"| EventDispatcher

    Regulator -->|"uses hand ranking"| CombinationEngine
    SettlementEngine -->|"invoke EvaluateHand()"| CombinationEngine
    EventDispatcher -->|"notify match events"| MatchRunnerQueue
    MatchRunnerQueue -->|"apply rules"| Regulator
    MatchRunnerQueue -->|"manage seats"| SeatManager
    MatchRunnerQueue -->|"trigger pot resolution"| PotManager
    MatchRunnerQueue -->|"trigger settlement"| SettlementEngine

    CompetitionManager -->|"sequence matches"| MatchRunnerQueue
    TableBackend -->|"implements backend"| MatchRunnerQueue
    ActorInterfaces -->|"injected runners"| MatchRunnerQueue

    %% Click Events
    click PublicAPI "https://github.com/weedbox/pokerface/blob/main/pokerface.go"
    click GameController "https://github.com/weedbox/pokerface/blob/main/game.go"
    click GameController "https://github.com/weedbox/pokerface/blob/main/game_state.go"
    click GameController "https://github.com/weedbox/pokerface/blob/main/game_options.go"
    click EventDispatcher "https://github.com/weedbox/pokerface/blob/main/event.go"
    click DeckManager "https://github.com/weedbox/pokerface/blob/main/deck.go"
    click ActionPlayer "https://github.com/weedbox/pokerface/blob/main/action.go"
    click ActionPlayer "https://github.com/weedbox/pokerface/blob/main/player.go"
    click CombinationEngine "https://github.com/weedbox/pokerface/tree/main/combination/"
    click PotManager "https://github.com/weedbox/pokerface/tree/main/pot/"
    click SettlementEngine "https://github.com/weedbox/pokerface/tree/main/settlement/"
    click Regulator "https://github.com/weedbox/pokerface/tree/main/regulator/"
    click SeatManager "https://github.com/weedbox/pokerface/tree/main/seat_manager/"
    click MatchRunnerQueue "https://github.com/weedbox/pokerface/tree/main/match/"
    click CompetitionManager "https://github.com/weedbox/pokerface/tree/main/competition/"
    click TableBackend "https://github.com/weedbox/pokerface/tree/main/table/"
    click ActorInterfaces "https://github.com/weedbox/pokerface/tree/main/actor/"

    %% Styles
    classDef coreEngine fill:#D6EAF8,stroke:#21618C,color:#1B2631,stroke-width:1px
    classDef domainLogic fill:#EBDEF0,stroke:#6C3483,color:#1B2631,stroke-width:1px
    classDef orchestration fill:#D5F5E3,stroke:#196F3D,color:#1B2631,stroke-width:1px
    classDef adapter fill:#FAD7A0,stroke:#B9770E,color:#1B2631,stroke-width:1px
```
