# ikabot-collective/ikabot architecture

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

- Interactive diagram: https://gitdiagram.com/ikabot-collective/ikabot
- Repository: https://github.com/ikabot-collective/ikabot

## Overview

##### Project type and purpose
- From the README (“Ikabot is a cross-platform Python program…enhances your Ikariam game”), this is a desktop/CLI automation tool (with an embedded web API interface) that interacts with the external Ikariam game servers to provide automated city-management and warfare features.

##### File structure
- Top-level:
- Dockerfile, CI workflows (.github/workflows) – Docker image and CI/CD pipelines.
- setup.py, MANIFEST.in – packaging/ distribution.
- ikabot/ – the application code:
– __main__.py & command_line.py – entry point for CLI.
– config.py / .env.example – configuration management.
– function/ – each script implements a specific game automation feature.
– helpers/ – common utilities (HTTP API comm, encryption, logging, GUI, routing, Telegram bot, etc.).
– web/ – lightweight HTTP session server for remote control or API endpoints.
– locale/ – translations.
- tests/ – automated tests for API routes and core functions.

##### Detail
- 3 user‐facing interfaces (CLI, Web API, Telegram).
- Helper category (network, encryption, logging).
- Don’t over-abstract—show multiple “function” modules as a single block or grouped by category.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "User Interfaces" 
        direction TB
        CLI_MAIN["__main__.py"]:::ui
        CLI_CMD["command_line.py"]:::ui
        WEB_API["session.py"]:::ui
        TELEGRAM_BOT["botComm.py"]:::ui
        TELE_TEST["testTelegramBot.py"]:::ui
    end

    %% Core Logic Layer
    subgraph "Core Logic" 
        direction TB
        FUNC_MODULES["Function Modules\n(ikabot/function/)"]:::core
    end

    %% Configuration
    subgraph "Configuration" 
        direction TB
        CONFIG["config.py"]:::infra
        ENV_EX[".env.example"]:::infra
    end

    %% Helpers / Infrastructure Services
    subgraph "Helper Utilities" 
        direction TB
        API_COMM["apiComm.py"]:::helper
        AES["aesCipher.py"]:::helper
        LOGGING["logging.py"]:::helper
        DNS["dns.py"]:::helper
        GETJSON["getJson.py"]:::helper
        GUI["gui.py"]:::helper
        MARKET["market.py"]:::helper
        NAVAL["naval.py"]:::helper
        PROCESS_HELP["process.py"]:::helper
        RESOURCES["resources.py"]:::helper
        SIGNALS["signals.py"]:::helper
    end

    %% Local File System
    LocalFS["Local File System\n(.env, cookies, logs)"]:::external

    %% External Services
    subgraph "External Services"
        direction TB
        IKARIAM["Ikariam Game Servers"]:::external
        TELE_SERVICE["Telegram Service"]:::external
    end

    %% Containerization & CI/CD
    subgraph "Infrastructure"
        direction TB
        DOCKER["Dockerfile"]:::infra
        CI["CI/CD Pipelines\n(.github/workflows/)"]:::infra
        PACKAGING["setup.py, MANIFEST.in"]:::infra
    end

    %% Relationships
    CLI_MAIN -->|loads CLI| CLI_CMD
    CLI_CMD -->|dispatches| FUNC_MODULES
    WEB_API -->|routes to| FUNC_MODULES
    TELE_TEST -->|invokes| TELEGRAM_BOT
    TELEGRAM_BOT -->|triggers| FUNC_MODULES

    FUNC_MODULES -->|uses| API_COMM
    FUNC_MODULES -->|uses| AES
    FUNC_MODULES -->|uses| LOGGING
    FUNC_MODULES -->|uses| DNS
    FUNC_MODULES -->|uses| GETJSON
    FUNC_MODULES -->|uses| GUI
    FUNC_MODULES -->|uses| MARKET
    FUNC_MODULES -->|uses| NAVAL
    FUNC_MODULES -->|uses| PROCESS_HELP
    FUNC_MODULES -->|uses| RESOURCES
    FUNC_MODULES -->|uses| SIGNALS

    API_COMM -->|HTTP requests| IKARIAM
    TELEGRAM_BOT -->|API calls| TELE_SERVICE
    LOGGING -->|writes| LocalFS
    AES -->|reads/writes| LocalFS
    CONFIG -->|loads| FUNC_MODULES
    ENV_EX -->|provides template| CONFIG

    DOCKER -->|packages| CLI_MAIN
    DOCKER -->|includes| CI
    CI -->|tests| FUNC_MODULES
    CI -->|publishes| PACKAGING

    %% Click Events
    click CLI_MAIN "https://github.com/ikabot-collective/ikabot/blob/master/ikabot/__main__.py"
    click CLI_CMD "https://github.com/ikabot-collective/ikabot/blob/master/ikabot/command_line.py"
    click CONFIG "https://github.com/ikabot-collective/ikabot/blob/master/ikabot/config.py"
    click ENV_EX "https://github.com/ikabot-collective/ikabot/blob/master/.env.example"
    click FUNC_MODULES "https://github.com/ikabot-collective/ikabot/tree/master/ikabot/function"
    click WEB_API "https://github.com/ikabot-collective/ikabot/blob/master/ikabot/web/session.py"
    click TELEGRAM_BOT "https://github.com/ikabot-collective/ikabot/blob/master/ikabot/helpers/botComm.py"
    click TELE_TEST "https://github.com/ikabot-collective/ikabot/blob/master/ikabot/function/testTelegramBot.py"
    click API_COMM "https://github.com/ikabot-collective/ikabot/blob/master/ikabot/helpers/apiComm.py"
    click AES "https://github.com/ikabot-collective/ikabot/blob/master/ikabot/helpers/aesCipher.py"
    click LOGGING "https://github.com/ikabot-collective/ikabot/blob/master/ikabot/helpers/logging.py"
    click DNS "https://github.com/ikabot-collective/ikabot/blob/master/ikabot/helpers/dns.py"
    click GETJSON "https://github.com/ikabot-collective/ikabot/blob/master/ikabot/helpers/getJson.py"
    click GUI "https://github.com/ikabot-collective/ikabot/blob/master/ikabot/helpers/gui.py"
    click MARKET "https://github.com/ikabot-collective/ikabot/blob/master/ikabot/helpers/market.py"
    click NAVAL "https://github.com/ikabot-collective/ikabot/blob/master/ikabot/helpers/naval.py"
    click PROCESS_HELP "https://github.com/ikabot-collective/ikabot/blob/master/ikabot/helpers/process.py"
    click RESOURCES "https://github.com/ikabot-collective/ikabot/blob/master/ikabot/helpers/resources.py"
    click SIGNALS "https://github.com/ikabot-collective/ikabot/blob/master/ikabot/helpers/signals.py"
    click DOCKER "https://github.com/ikabot-collective/ikabot/tree/master/Dockerfile"
    click CI "https://github.com/ikabot-collective/ikabot/blob/master/.github/workflows/build_artifacts.yml"
    click PACKAGING "https://github.com/ikabot-collective/ikabot/blob/master/setup.py"

    %% Styles
    classDef ui fill:#D0E6FF,stroke:#0277BD,color:#000;
    classDef core fill:#D0F2F6,stroke:#00838F,color:#000;
    classDef helper fill:#FFF3E0,stroke:#F57C00,color:#000;
    classDef infra fill:#ECEFF1,stroke:#546E7A,color:#000;
    classDef external fill:#F5F5F5,stroke:#9E9E9E,color:#000
```
