# coder/balatrollm architecture

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

- Interactive diagram: https://gitdiagram.com/coder/balatrollm
- Repository: https://github.com/coder/balatrollm

## Overview

##### Project type and purpose
- This is a Python-based CLI tool (“BalatroLLM”) that drives a poker-deck roguelike game bot by orchestrating calls between (a) the BalatroBot HTTP API and (b) one or more LLM backends.
- It wraps configuration, game-state collection, strategy selection (via Jinja-templated prompts), LLM invocation, and action execution into a cohesive command-line interface.

##### File structure
- Top-level directories:
- src/balatrollm – core Python packages:
– cli.py (Click-based entry point)
– config.py (YAML loader)
– client.py (HTTP client for BalatroBot API)
– collector.py (game-state assembler)
– llm.py (LLM provider abstraction)
– executor.py (sends chosen actions back to the API)
– bot.py (orchestrator tying all subcomponents)
– strategy.py / strategies/… (Strategy pattern: multiple folders of Jinja templates + manifest.json)
– views.py + views/*.html (optional local HTML rendering of responses/tasks)
- config/ – example YAML to drive runtime behavior
- docs/ + mkdocs.yml – documentation site
- tests/ – unit & integration tests
- Config files: .envrc.example, pyproject.toml, Makefile, GitHub workflows for CI/CD & PyPI releases.

##### README for additional insights
- Emphasizes LLM-powered decision making, the BalatroBot API as external service, and multiple “strategies” to choose from.

##### Elements
- Internal modules (solid rectangles, blue)
- Related modules into logical clusters (e.g., “Orchestrator”, “Strategy Plugins”, “Adapters”)

##### Final advice
- Be exhaustive but clear: don’t omit the Collector or Executor—they’re as critical as the LLM call.
- Sequence: CLI → Config → API → Collector → Strategy → LLM → Executor → API.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Subgraphs and modules
    subgraph "User Interface"
        CLI["CLI Interface"]:::internal
        ConfigLoader["Configuration Loader"]:::internal
        ExampleYAML["example.yaml"]:::internal
    end

    subgraph "Core Orchestrator"
        Bot["Orchestrator"]:::internal
        Client["API Client"]:::internal
        Collector["Game-State Collector"]:::internal
        Strategy["Strategy Engine"]:::internal
        Adapter["LLM Provider Adapter"]:::internal
        Executor["Action Executor"]:::internal
        View["View Renderer"]:::internal
    end

    subgraph "Strategy Plugins"
        direction TB
        Aggressive["aggressive/manifest.json"]:::plugin
        Conservative["conservative/manifest.json"]:::plugin
        DefaultStrat["default/manifest.json"]:::plugin
    end

    subgraph "External Services"
        API["BalatroBot HTTP API"]:::external
        LLMService["LLM Backend Service"]:::external
    end

    %% Connections
    CLI -->|"parse_args & load config"| ConfigLoader
    ConfigLoader -->|"load settings"| Bot
    CLI -->|"invoke"| Bot

    Bot -->|"fetch_game_state()"| Client
    Client -->|"> GET state"| API
    API -->|"> JSON state"| Client
    Client -->|"state_data"| Collector
    Collector -->|"structured_model"| Bot

    Bot -->|"render_prompt()"| Strategy
    Strategy -->|"use templates"| Aggressive
    Strategy -->|"use templates"| Conservative
    Strategy -->|"use templates"| DefaultStrat
    Strategy -->|"prompt_text"| Adapter

    Adapter -->|"send_prompt()"| LLMService
    LLMService -->|"response_text"| Adapter
    Adapter -->|"llm_response"| Bot

    Bot -->|"post_action()"| Executor
    Executor -->|"> POST action"| API
    API -->|"ack"| Executor

    Bot -->|"generate_view()"| View
    Bot -->|"output/log"| CLI

    %% Click Events
    click CLI "https://github.com/coder/balatrollm/blob/main/src/balatrollm/cli.py"
    click ConfigLoader "https://github.com/coder/balatrollm/blob/main/src/balatrollm/config.py"
    click ExampleYAML "https://github.com/coder/balatrollm/blob/main/config/example.yaml"
    click Client "https://github.com/coder/balatrollm/blob/main/src/balatrollm/client.py"
    click Collector "https://github.com/coder/balatrollm/blob/main/src/balatrollm/collector.py"
    click Strategy "https://github.com/coder/balatrollm/blob/main/src/balatrollm/strategy.py"
    click Aggressive "https://github.com/coder/balatrollm/blob/main/src/balatrollm/strategies/aggressive/manifest.json"
    click Conservative "https://github.com/coder/balatrollm/blob/main/src/balatrollm/strategies/conservative/manifest.json"
    click DefaultStrat "https://github.com/coder/balatrollm/blob/main/src/balatrollm/strategies/default/manifest.json"
    click Adapter "https://github.com/coder/balatrollm/blob/main/src/balatrollm/llm.py"
    click Executor "https://github.com/coder/balatrollm/blob/main/src/balatrollm/executor.py"
    click Bot "https://github.com/coder/balatrollm/blob/main/src/balatrollm/bot.py"
    click View "https://github.com/coder/balatrollm/blob/main/src/balatrollm/views.py"
    click View "https://github.com/coder/balatrollm/blob/main/src/balatrollm/views/responses.html"
    click View "https://github.com/coder/balatrollm/blob/main/src/balatrollm/views/task.html"

    %% Styles
    classDef internal fill:#DDEEFF,stroke:#0000FF,stroke-width:1px
    classDef external fill:#FFDDDD,stroke:#FF0000,stroke-dasharray: 5 5,stroke-width:1px
    classDef plugin fill:#DDFFDD,stroke:#008000,stroke-dasharray: 2 2,stroke-width:1px
```
