# kieran-mackle/cryptobots architecture

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

- Interactive diagram: https://gitdiagram.com/kieran-mackle/cryptobots
- Repository: https://github.com/kieran-mackle/cryptobots

## Overview

##### Project type and purpose
- CryptoBots is an open-source Python package and command-line interface for deploying and backtesting pre-built (and user-defined) crypto trading strategies.
- It depends on the AutoTrader library for market data feeds, execution logic, and backtests, and uses YAML configs to parameterize strategy runs.

##### File structure
- Top-level:
- `.github/` – CI/CD workflows for linting, formatting, version bump, publish
- `pyproject.toml` – build/config for packaging
- `src/cryptobots/` – main package
– `_cli/` – command-line entrypoint + utilities
– `config/` – strategy default parameter files (YAML)
– `strategies/` – Python modules implementing each trading strategy
- No separate frontend or database; state lives in the user’s home folder (`~/.cryptobots/`).

##### README for additional insights
- The CLI supports commands: `configure`, `strategies`, `run`, `stop`, `backtest`.
- Strategies load defaults from YAML, prompt user for overrides, then call AutoTrader to execute or backtest.
- API keys are stored locally under `~/.cryptobots/`.

##### Main components & their interactions
a. Components
1. CLI Layer (`cryptobots` executable)
2. Config Loader (reads/writes `~/.cryptobots/` and strategy YAMLs)
3. Strategy Manager (selects and initializes Python strategy modules)
4. Execution Engine (AutoTrader core library)
5. Exchange Adapters (REST/WebSocket connectors within AutoTrader)
6. Persistence (local file store for API keys and logs)
7. (Optional) Backtest Module (simulation using historical data)
b. Data flows & relationships
- User → CLI Layer → Config Loader → Strategy Manager → Execution Engine
- Execution Engine ↔ Exchange Adapters → Crypto Exchange (market data & order placement)
- Backtest Module ← Strategy Manager ← Historical Data Provider
- Execution outcomes, logs, and results → Persistence
c. Architectural patterns & principles
- Modular, plugin-based strategy pattern (each strategy is a self-contained Python module)
- Separation of concerns: CLI, config, strategy logic, execution API all in distinct layers
- External dependency inversion: All exchange I/O delegated to AutoTrader adapters
d. Key technologies
- Python packaging (PEP 517 via `pyproject.toml`)
- Click or argparse (in `cryptobots/_cli/cli.py`) for CLI
- PyYAML for config loading
- AutoTrader library for market I/O and backtesting
- YAML strategy definitions under `src/cryptobots/config/*.yaml`

##### Detailed capture of essential elements
- That the Execution Engine calls both market data feeds and order endpoints via the Exchange Adapters.

- Component boundaries (CLI vs. core library vs. adapters)
- Data flow directions (user commands → execution → exchange)
- Extensibility points (strategy plugin modules)
- Deployment context (local filesystem for configs and keys)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External User
    User["User"]:::external

    %% CLI & Config Layer
    subgraph "CLI & Config Layer"
        CLI["CLI Layer"]:::ui
        UTIL["CLI Utilities & Constants"]:::ui
        CONFIG["Config Loader"]:::ui
        subgraph "Config Files"
            breakout_yaml["breakout.yaml"]:::ui
            cc_yaml["cc.yaml"]:::ui
            emac_yaml["emac.yaml"]:::ui
            grid_yaml["grid.yaml"]:::ui
            range_yaml["range.yaml"]:::ui
            twap_yaml["twap.yaml"]:::ui
        end
    end

    %% Strategy Layer
    subgraph "Strategy Layer"
        SM["Strategy Manager"]:::biz
        breakout_py["breakout.py"]:::biz
        cc_py["cc.py"]:::biz
        emac_py["emac.py"]:::biz
        grid_py["grid.py"]:::biz
        range_py["range.py"]:::biz
        twap_py["twap.py"]:::biz
        plug["🔌 plugin"]:::biz
    end

    %% Execution & Adapters
    subgraph "Execution & Adapters"
        EE["Execution Engine (AutoTrader)"]:::infra
        AD["Exchange Adapters"]:::infra
    end

    %% Persistence Layer
    subgraph Persistence
        P["Local File Store (~/.cryptobots/)"]:::persist
        creds["credentials.yml"]:::persist
        logs["run_logs/"]:::persist
    end

    %% Backtesting
    subgraph Backtesting
        BM["Backtest Module"]:::infra
        HD["Historical Data"]:::infra
    end

    %% Repository Info
    subgraph "Repository"
        PY["pyproject.toml"]:::repo
        FMT[".github/workflows/format.yml"]:::repo
        BUMP[".github/workflows/bump.yml"]:::repo
        PUB[".github/workflows/publish.yml"]:::repo
        RD["README.md"]:::repo
        CHG["CHANGELOG.md"]:::repo
        LIC["LICENSE"]:::repo
    end

    %% Connections
    User -->|"command"| CLI
    CLI -->|"load YAML→params"| CONFIG
    CONFIG -->|"provide config"| SM
    SM -->|"init strategy"| EE
    SM -.->|"simulate"| BM
    BM -->|"use historical"| HD
    EE -->|"place order→REST call"| AD
    EE -->|"fetch market data→WS/REST"| AD
    AD -->|"market data & orders"| EE
    EE -->|"store logs/results"| P
    SM -->|"store keys/logs"| P
    P --> creds
    P --> logs

    %% Click Events for CLI & Config
    click CLI "https://github.com/kieran-mackle/cryptobots/blob/main/src/cryptobots/_cli/cli.py"
    click UTIL "https://github.com/kieran-mackle/cryptobots/blob/main/src/cryptobots/_cli/utilities.py"
    click UTIL "https://github.com/kieran-mackle/cryptobots/blob/main/src/cryptobots/_cli/constants.py"
    click breakout_yaml "https://github.com/kieran-mackle/cryptobots/blob/main/src/cryptobots/config/breakout.yaml"
    click cc_yaml "https://github.com/kieran-mackle/cryptobots/blob/main/src/cryptobots/config/cc.yaml"
    click emac_yaml "https://github.com/kieran-mackle/cryptobots/blob/main/src/cryptobots/config/emac.yaml"
    click grid_yaml "https://github.com/kieran-mackle/cryptobots/blob/main/src/cryptobots/config/grid.yaml"
    click range_yaml "https://github.com/kieran-mackle/cryptobots/blob/main/src/cryptobots/config/range.yaml"
    click twap_yaml "https://github.com/kieran-mackle/cryptobots/blob/main/src/cryptobots/config/twap.yaml"

    %% Click Events for Strategy Modules
    click breakout_py "https://github.com/kieran-mackle/cryptobots/blob/main/src/cryptobots/strategies/breakout.py"
    click cc_py "https://github.com/kieran-mackle/cryptobots/blob/main/src/cryptobots/strategies/cc.py"
    click emac_py "https://github.com/kieran-mackle/cryptobots/blob/main/src/cryptobots/strategies/emac.py"
    click grid_py "https://github.com/kieran-mackle/cryptobots/blob/main/src/cryptobots/strategies/grid.py"
    click range_py "https://github.com/kieran-mackle/cryptobots/blob/main/src/cryptobots/strategies/range.py"
    click twap_py "https://github.com/kieran-mackle/cryptobots/blob/main/src/cryptobots/strategies/twap.py"

    %% Click Events for Repository
    click PY "https://github.com/kieran-mackle/cryptobots/blob/main/pyproject.toml"
    click FMT "https://github.com/kieran-mackle/cryptobots/blob/main/.github/workflows/format.yml"
    click BUMP "https://github.com/kieran-mackle/cryptobots/blob/main/.github/workflows/bump.yml"
    click PUB "https://github.com/kieran-mackle/cryptobots/blob/main/.github/workflows/publish.yml"
    click RD "https://github.com/kieran-mackle/cryptobots/blob/main/README.md"
    click CHG "https://github.com/kieran-mackle/cryptobots/blob/main/CHANGELOG.md"
    click LIC "https://github.com/kieran-mackle/cryptobots/tree/main/LICENSE"

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:1px;
    classDef ui fill:#bbdefb,stroke:#333,stroke-width:1px;
    classDef biz fill:#c8e6c9,stroke:#333,stroke-width:1px;
    classDef infra fill:#ffe0b2,stroke:#333,stroke-width:1px;
    classDef persist fill:#eceff1,stroke:#333,stroke-width:1px;
    classDef repo fill:#e1bee7,stroke:#333,stroke-width:1px;
```
