# torom/botli architecture

> Architecture diagram of the GitHub repository torom/botli, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/torom/botli
- Repository: https://github.com/torom/botli

## Overview

##### Main Components

a) Core Components:
- Lichess API Interface
- UCI Engine Manager
- Game Manager
- Matchmaking System
- Challenge Handler
- Opening Book Manager
- Configuration Manager

b) External Services:
- Lichess API
- UCI Chess Engines
- Opening Books
- Endgame Tablebases (Syzygy/Gaviota)

##### Component Relationships

a) Primary Data Flow:
- Lichess API <-> API Handler (api.py)
- Engine Manager (engine.py) <-> UCI Engines
- Game Manager (game_manager.py) <-> Lichess Game Handler (lichess_game.py)

b) Secondary Flows:
- Configuration (config.py) -> All Components
- Event Handler (event_handler.py) -> Game Manager
- Challenger (challenger.py) -> Matchmaking (matchmaking.py)

##### Implementation Details

- user_interface.py: Entry point and command handling
- game_manager.py: Central game coordination
- engine.py: UCI engine communication
- challenger.py & matchmaking.py: Challenge management
- botli_dataclasses.py: Data structures
- config.py & configs.py: Configuration management

##### Deployment Aspects

Deployment options:
- Docker container
- Systemd service
- Interactive mode
- Non-interactive mode

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Services Layer
    subgraph External
        LichessAPI[("Lichess API")]
        UCIEngines[("UCI Chess Engines")]
        OpeningBooks[("Opening Books")]:::data
        Tablebases[("Endgame Tablebases")]:::data
    end

    %% Core Layer
    subgraph Core
        APIInterface["API Interface"]:::core
        EngineManager["UCI Engine Manager"]:::core
        GameManager["Game Manager"]:::core
        MatchMaker["Matchmaking System"]:::core
        ChallengeHandler["Challenge Handler"]:::core
        ConfigManager["Configuration Manager"]:::core
    end

    %% Data Layer
    subgraph Data
        DataModels["Data Models"]:::data
        GameComponents["Game Components"]:::data
    end

    %% Interface Layer
    subgraph Interface
        UserInterface["User Interface"]:::interface
        EventHandler["Event Handler"]:::interface
        ChatSystem["Chat System"]:::interface
        OpponentMgmt["Opponent Management"]:::interface
    end

    %% Relationships
    LichessAPI <--> APIInterface
    UCIEngines <--> EngineManager
    OpeningBooks --> GameManager
    Tablebases --> GameManager

    APIInterface <--> GameManager
    EngineManager <--> GameManager
    GameManager <--> MatchMaker
    MatchMaker <--> ChallengeHandler
    ConfigManager --> GameManager
    ConfigManager --> EngineManager
    ConfigManager --> MatchMaker

    GameComponents <--> GameManager
    DataModels --> GameManager
    DataModels --> ChallengeHandler

    UserInterface --> EventHandler
    EventHandler --> GameManager
    ChatSystem --> GameManager
    OpponentMgmt --> MatchMaker

    %% Click Events
    click APIInterface "https://github.com/Torom/BotLi/blob/main/api.py"
    click EngineManager "https://github.com/Torom/BotLi/blob/main/engine.py"
    click GameManager "https://github.com/Torom/BotLi/blob/main/game_manager.py"
    click MatchMaker "https://github.com/Torom/BotLi/blob/main/matchmaking.py"
    click ChallengeHandler "https://github.com/Torom/BotLi/blob/main/challenger.py"
    click ConfigManager "https://github.com/Torom/BotLi/blob/main/config.py"
    click DataModels "https://github.com/Torom/BotLi/blob/main/botli_dataclasses.py"
    click GameComponents "https://github.com/Torom/BotLi/blob/main/game.py"
    click UserInterface "https://github.com/Torom/BotLi/blob/main/user_interface.py"
    click EventHandler "https://github.com/Torom/BotLi/blob/main/event_handler.py"
    click ChatSystem "https://github.com/Torom/BotLi/blob/main/chatter.py"
    click OpponentMgmt "https://github.com/Torom/BotLi/blob/main/opponents.py"
    click UCIEngines "https://github.com/Torom/BotLi/tree/main/engines/"

    %% Styles
    classDef core fill:#a8d5ff,stroke:#333,stroke-width:2px
    classDef interface fill:#ffd7a8,stroke:#333,stroke-width:2px
    classDef data fill:#fff3a8,stroke:#333,stroke-width:2px
    classDef external fill:#a8ffc9,stroke:#333,stroke-width:2px

    %% Legend
    subgraph Legend
        CoreComp["Core Component"]:::core
        InterfaceComp["Interface Component"]:::interface
        DataComp["Data Component"]:::data
        ExtComp["External Service"]:::external
    end
```
