# keithlee96/pluribus-poker-ai architecture

> Architecture diagram of the GitHub repository keithlee96/pluribus-poker-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/keithlee96/pluribus-poker-ai
- Repository: https://github.com/keithlee96/pluribus-poker-ai

## Overview

##### Project type and purpose
- This is a full-stack Python toolkit for building and using a poker AI based on Counterfactual Regret Minimisation (MCCFR).
- It provides a core library (`poker_ai`), a CLI (`poker_ai cluster|train|play`), batch apps (dataset/visualisation), a live web visualiser, and research scripts.

##### File structure
- Top level: Dockerfiles (`Dockerfile`, `ParentDockerfile`), CI/CD configs (`.travis.yml`, GitHub Actions), `docs`, `requirements.txt`, `setup.py`.
- `poker_ai/`: the core Python package, subdivided into:
- `ai/` – MCCFR runner, agent abstractions, multiprocess manager & workers
- `games/` – state & player models (e.g. ShortDeckPokerState)
- `poker/` – engine, table, pot, deck, hand evaluation
- `terminal/` – CLI runner for text UI
- `utils/` – I/O, logging, random seed
- `applications/`: standalone scripts and servers
- `strategy_dag_visualisation/` – dataset generator
- `visualisation/` – a Flask/WebSocket backend + Vue.js frontend
- `research/`: exploratory scripts
- `test/`: unit & functional tests

##### README for additional insights
- CLI commands: `cluster`, `train start|resume`, `play`, each invoking core library modules.
- Docker-based CI builds the environment, runs `pytest`.
- The visualiser runs a local Flask server exposing WebSockets; frontend is a webpack/Vue single-page app.
- Data artifacts: `card_info_lut.joblib`, CSV dataset, strategy files, `results.yaml`.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "User Interfaces"
        CLI["CLI Layer"]:::ui
        TerminalUI["Terminal UI"]:::ui
        WebUI["Web UI"]:::ui
    end

    subgraph "Application Services"
        subgraph "Core Library"
            CoreLib["poker_ai"]:::service
            subgraph "AI Engines"
                AIE_S["Single-process MCCFR"]:::service
                AIE_MP_Server["MP Server"]:::service
                AIE_MP_Worker["MP Worker"]:::service
                AIE_Runner["MP Runner"]:::service
            end
            GameEngine["Game Engine & Rules"]:::service
            subgraph "Clustering Module"
                ClustRunner["LUT Runner"]:::service
                ClustBuilder["LUT Builder"]:::service
            end
        end
        VisualServer["Flask/WebSocket Server"]:::service
        Convert["Convert Module"]:::service
    end

    subgraph "Data Stores"
        LUT["card_info_lut.joblib"]:::data
        Strategies["Strategy Artifacts"]:::data
        Results["results.yaml"]:::data
        Dataset["dataset.csv"]:::data
    end

    subgraph "Infrastructure"
        ParentDocker["Base Docker Image"]:::infra
        DockerTest["Test Docker Image"]:::infra
        CI["CI/CD Configs"]:::infra
        Package["setup.py & requirements.txt"]:::infra
        Docs["docs/"]:::infra
        Tests["test/"]:::infra
        Research["research/"]:::infra
    end

    %% Relationships
    CLI -->|cluster| ClustRunner
    ClustRunner --> AIE_MP_Server
    AIE_MP_Server --> AIE_MP_Worker
    ClustBuilder --> LUT

    CLI -->|train| AIE_S
    AIE_S --> GameEngine
    GameEngine --> Strategies

    CLI -->|play| TerminalUI
    TerminalUI --> Results

    CLI --> CoreLib
    CoreLib --> VisualServer
    VisualServer --> Convert
    Convert --> WebUI

    DatasetGen["Strategy DAG Generator"]:::service
    DatasetGen --> Dataset

    %% Infrastructure flows
    CI --> ParentDocker
    CI --> DockerTest
    CI --> Tests
    Package --> CoreLib

    %% Click Events
    click CoreLib "https://github.com/keithlee96/pluribus-poker-ai/tree/develop/poker_ai/"
    click AIE_S "https://github.com/keithlee96/pluribus-poker-ai/blob/develop/poker_ai/ai/singleprocess/train.py"
    click AIE_MP_Server "https://github.com/keithlee96/pluribus-poker-ai/blob/develop/poker_ai/ai/multiprocess/server.py"
    click AIE_MP_Worker "https://github.com/keithlee96/pluribus-poker-ai/blob/develop/poker_ai/ai/multiprocess/worker.py"
    click AIE_Runner "https://github.com/keithlee96/pluribus-poker-ai/blob/develop/poker_ai/ai/runner.py"
    click GameEngine "https://github.com/keithlee96/pluribus-poker-ai/tree/develop/poker_ai/poker/"
    click ClustBuilder "https://github.com/keithlee96/pluribus-poker-ai/blob/develop/poker_ai/clustering/card_info_lut_builder.py"
    click ClustRunner "https://github.com/keithlee96/pluribus-poker-ai/blob/develop/poker_ai/clustering/runner.py"
    click CLI "https://github.com/keithlee96/pluribus-poker-ai/tree/develop/bin/poker_ai"
    click CLI "https://github.com/keithlee96/pluribus-poker-ai/blob/develop/poker_ai/cli/runner.py"
    click TerminalUI "https://github.com/keithlee96/pluribus-poker-ai/blob/develop/poker_ai/terminal/runner.py"
    click TerminalUI "https://github.com/keithlee96/pluribus-poker-ai/tree/develop/poker_ai/terminal/ascii_objects/"
    click DatasetGen "https://github.com/keithlee96/pluribus-poker-ai/blob/develop/applications/strategy_dag_visualisation/create_dataset.py"
    click VisualServer "https://github.com/keithlee96/pluribus-poker-ai/blob/develop/applications/visualisation/run.py"
    click Convert "https://github.com/keithlee96/pluribus-poker-ai/blob/develop/applications/visualisation/backend/convert.py"
    click WebUI "https://github.com/keithlee96/pluribus-poker-ai/tree/develop/applications/visualisation/frontend/"
    click Research "https://github.com/keithlee96/pluribus-poker-ai/tree/develop/research/"
    click Tests "https://github.com/keithlee96/pluribus-poker-ai/tree/develop/test/unit/"
    click Tests "https://github.com/keithlee96/pluribus-poker-ai/tree/develop/test/functional/"
    click ParentDocker "https://github.com/keithlee96/pluribus-poker-ai/tree/develop/ParentDockerfile"
    click DockerTest "https://github.com/keithlee96/pluribus-poker-ai/tree/develop/Dockerfile"
    click CI "https://github.com/keithlee96/pluribus-poker-ai/blob/develop/.travis.yml"
    click CI "https://github.com/keithlee96/pluribus-poker-ai/blob/develop/.github/workflows/python-publish.yml"
    click Package "https://github.com/keithlee96/pluribus-poker-ai/blob/develop/setup.py"
    click Package "https://github.com/keithlee96/pluribus-poker-ai/blob/develop/requirements.txt"
    click Docs "https://github.com/keithlee96/pluribus-poker-ai/tree/develop/docs/"

    classDef ui fill:#ADD8E6,stroke:#333;
    classDef service fill:#90EE90,stroke:#333;
    classDef data fill:#FFD700,stroke:#333;
    classDef infra fill:#D3D3D3,stroke:#333;
```
