# maxme/bitcoin-arbitrage architecture

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

- Interactive diagram: https://gitdiagram.com/maxme/bitcoin-arbitrage
- Repository: https://github.com/maxme/bitcoin-arbitrage

## Overview

##### Project type and purpose
- This is a Python-based command-line tool for detecting Bitcoin arbitrage opportunities across multiple exchanges and, optionally, executing trades automatically.
- It uses an Observer pattern to decouple the core opportunity‐detection engine from side effects (logging, emailing, trading).

##### File structure
Top-level artifacts
- setup.py, requirements.txt, docs/ – packaging and documentation
- README.md – high-level description and usage
- arbitrage/ – main Python package
– arbitrage.py               ← CLI entry point (module __main__)
– arbitrer.py                ← core engine: orchestrates data flow & opportunity detection
– config.py-example          ← user-editable config (markets to watch, observers to use)
– fiatconverter.py           ← converts all prices to a common currency (USD) via ECB API
– utils.py                   ← shared helpers (e.g., HTTP clients, parsing)
– public_markets/            ← “read-only” exchange adapters (order-book retrieval)
– private_markets/           ← “write” exchange adapters (place trades via API keys)
– observers/                 ← Observer implementations (logger, emailer, history dumper, trader bot, XMPP messenger, simulator)
– test/                      ← unit and integration tests

##### README for additional insights
- Supported exchanges (public & private) enumerate all adapter modules under public_markets/ and private_markets/.
- Warning about real trading bots and API‐key security (config.py).
- External dependencies: ECB FX rates, sleekxmpp for XMPP observer.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "CLI & Configuration Loader"
        CLI["CLI & Configuration Loader"]:::core
        CFG["Configuration (config.py-example)"]:::core
    end
    click CLI "https://github.com/maxme/bitcoin-arbitrage/blob/master/arbitrage/arbitrage.py"
    click CFG "https://github.com/maxme/bitcoin-arbitrage/blob/master/arbitrage/config.py-example"

    subgraph "Data Ingestion"
        PMarket["PublicMarketAdapters"]:::adapter
    end
    click PMarket "https://github.com/maxme/bitcoin-arbitrage/blob/master/arbitrage/public_markets/market.py"

    subgraph "Data Normalization"
        FC["FiatConverter"]:::core
    end
    click FC "https://github.com/maxme/bitcoin-arbitrage/blob/master/arbitrage/fiatconverter.py"

    subgraph "Core Engine"
        AE["Arbitrer (Detection & Dispatcher)"]:::core
        UT["Utils"]:::core
    end
    click AE "https://github.com/maxme/bitcoin-arbitrage/blob/master/arbitrage/arbitrer.py"
    click UT "https://github.com/maxme/bitcoin-arbitrage/blob/master/arbitrage/utils.py"

    subgraph "Observer Framework"
        OBS_BASE["Observer Interface"]:::observer
        LOGGER["Logger"]:::observer
        DLOGGER["DetailedLogger"]:::observer
        EMAILER["Emailer"]:::observer
        HISTORY["HistoryDumper"]:::observer
        TRADERBOT["TraderBot"]:::observer
        SPEC_TRADER["SpecializedTraderBot"]:::observer
        SIM_TRADER["TraderBotSim"]:::observer
        XMPPMSG["XMPPMessager"]:::observer
    end
    click OBS_BASE "https://github.com/maxme/bitcoin-arbitrage/blob/master/arbitrage/observers/observer.py"
    click LOGGER "https://github.com/maxme/bitcoin-arbitrage/blob/master/arbitrage/observers/logger.py"
    click DLOGGER "https://github.com/maxme/bitcoin-arbitrage/blob/master/arbitrage/observers/detailedlogger.py"
    click EMAILER "https://github.com/maxme/bitcoin-arbitrage/blob/master/arbitrage/observers/emailer.py"
    click HISTORY "https://github.com/maxme/bitcoin-arbitrage/blob/master/arbitrage/observers/historydumper.py"
    click TRADERBOT "https://github.com/maxme/bitcoin-arbitrage/blob/master/arbitrage/observers/traderbot.py"
    click SPEC_TRADER "https://github.com/maxme/bitcoin-arbitrage/blob/master/arbitrage/observers/specializedtraderbot.py"
    click SIM_TRADER "https://github.com/maxme/bitcoin-arbitrage/blob/master/arbitrage/observers/traderbotsim.py"
    click XMPPMSG "https://github.com/maxme/bitcoin-arbitrage/blob/master/arbitrage/observers/xmppmessager.py"

    subgraph "Execution Adapters"
        PrivateMarket["PrivateMarketAdapters"]:::adapter
    end
    click PrivateMarket "https://github.com/maxme/bitcoin-arbitrage/blob/master/arbitrage/private_markets/market.py"

    subgraph "External Services"
        EXCHANGES["Exchange REST/WebSocket APIs"]:::external
        ECBAPI["ECB FX Rate API"]:::external
        SMTP["SMTP Server"]:::external
        XMPPSRV["XMPP Server"]:::external
    end

    %% Data Flow
    CLI -->|"loads config"| CFG
    CLI -->|"starts engine"| AE
    AE -->|"fetch order books"| PMarket
    PMarket -->|"order book JSON"| EXCHANGES
    EXCHANGES -->|"order book JSON"| PMarket
    PMarket -->|"raw books"| FC
    FC -->|"normalized USD prices"| AE
    AE -->|"Opportunity Event"| OBS_BASE
    OBS_BASE --> LOGGER
    OBS_BASE --> DLOGGER
    OBS_BASE --> EMAILER
    OBS_BASE --> HISTORY
    OBS_BASE --> TRADERBOT
    OBS_BASE --> SPEC_TRADER
    OBS_BASE --> SIM_TRADER
    OBS_BASE --> XMPPMSG
    EMAILER --> SMTP
    XMPPMSG --> XMPPSRV
    TRADERBOT -->|"trade API"| PrivateMarket
    SPEC_TRADER -->|"trade API"| PrivateMarket
    PrivateMarket --> EXCHANGES

    classDef core fill:#D0E4F5,stroke:#036; 
    classDef adapter fill:#DFF5D0,stroke:#360; 
    classDef observer fill:#F5E0D0,stroke:#630; 
    classDef external fill:#EEEEEE,stroke:#666;
```
