# dogstailfarmer/martin-binance architecture

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

- Interactive diagram: https://gitdiagram.com/dogstailfarmer/martin-binance
- Repository: https://github.com/dogstailfarmer/martin-binance

## Overview

##### Project’s Nature and Purpose
- This project implements a cyclic grid strategy (a modified martingale approach) for trading on multiple crypto exchanges (e.g., Binance, Bitfinex, Huobi, OKX, Bybit).
- It supports live trading and backtesting, provides optimization capabilities, and integrates with external services like Telegram for notifications.
- The project is Python-based with Docker support and includes modules for executing trades, simulating market scenarios, and exporting funds data.

##### File Structure (Key Components)
- Core Trading Engine:
– Files like martin_binance/client.py, martin_binance/executor.py, martin_binance/strategy_base.py, and marting_binance/params.py indicate the trading core that handles strategy logic, parameter configuration, and order execution.
- Backtesting & Optimization:
– The martin_binance/backtest directory (with files such as OoTSP.py, VCoSEL.py, exchange_simulator.py, optimizer.py) represents components to simulate market behaviors, assess strategy performance, and conduct parameter optimization.
- Integration & Services:
– The martin_binance/service directory includes service files (e.g., funds_rate_exporter.py, relaunch.py) plus configuration files (including a tmux config and Grafana JSON), suggesting automated service tasks and monitoring.
– The martin_binance/telegram_proxy and martin_binance/tlg directories handle Telegram integration, which is essential for alerts and notifications.
- Configuration & Templates:
– The templates folder contains configuration script templates (cli_XX_AAABBB.py, ms_cfg.toml, trial_params.json) that allow users to configure trading pairs and system parameters.
- Infrastructure & Deployment:
– Files such as Dockerfile, .dockerignore, and GitHub workflows (in .github) indicate CI/CD integration and containerized deployment support.
– Additional artifacts like the uml/architecture.puml file hint at an existing symbolic overview of the architecture.

a. And Label Main Components:
- Trading Strategy Engine:
- Includes strategy modules (strategy_base.py, parameters management via params.py) and the trading client.
- Execution Module:
- Represented by executor.py, which translates strategy decisions into live orders using client.py for API communications.
- Backtesting & Simulation Module:
- Encapsulates the backtesting folder (exchange_simulator, optimizer, OoTSP.py, VCoSEL.py) that mimics market conditions and tests strategy performance.
- Integration & Service Layer:
- Covers services like funds rate exporters, relaunch functionality, and Telegram proxy modules for notifications.
- Persistence/Logging and Data Utilities:
- Managed by db_utils.py which handles data storage, logging, and potentially the management of state.
- External Interfaces:
- External Exchanges: Symbolize interaction with crypto exchange APIs (handled via the exchanges-wrapper integration mentioned in the README).
- Telegram: For user notifications and remote control aspects.
- Configuration Layer:
- Represents the use of template configurations and TOML/JSON files to customize strategy parameters.

b. Relationships and Interactions:
- The Trading Strategy Engine feeds orders into the Execution Module, which then interacts with External Exchanges.
- The Backtesting Module receives historical market data (or simulates market conditions) and provides feedback that can adjust or validate strategy parameters.
- The Service Layer ensures that essential tasks (exporting funds data, service relaunch logic) are executed regularly and that notifications flow into the Telegram module.
- DB Utilities are used by both live execution and backtesting modules for logging and state management.
- Configuration files act as inputs that feed the strategy engine and backtesting modules.

c. Architectural Patterns:
- Modularity: The project cleanly separates trading logic, execution, testing, and integration services.
- Service-Oriented and Extensibility: The “service” directory and configuration templates suggest that the system is built to allow for plug-and-play additions (for example, additional market pairs or new notification methods).
- Containerization and CI/CD: Dockerfile and GitHub workflows denote an emphasis on reliable deployment and continuous integration.

d. Relevant Technologies and Frameworks:
- Python as the core language with its asynchronous capabilities (noting the Windows limitation mentioned in the README).
- Docker for containerized deployment.
- GitHub Actions for CI/CD.
- Systemd (or similar service managers) for running service scripts.
- External APIs via an “exchanges-wrapper” library.
- Telegram integration for notifications (handled via telegram_proxy modules).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Configuration Layer"
        config["Configuration & Template Management"]:::configStyle
        infra["Infrastructure & Deployment"]:::configStyle
    end

    subgraph "Core Trading System"
        tse["Trading Strategy Engine"]:::coreStyle
        exec["Execution Module"]:::coreStyle
        backtest["Backtesting & Optimization Module"]:::coreStyle
        db["Data Persistence & Logging"]:::coreStyle
    end

    subgraph "Service Integration"
        svc["Integration & Service Layer"]:::serviceStyle
        tg["Telegram Integration"]:::serviceStyle
    end

    external["External Exchanges (APIs)"]:::externalStyle

    %% Data flows
    config -->|"feeds"| tse
    infra -->|"supports"| tse
    tse -->|"triggers"| exec
    tse -->|"simulated data"| backtest
    exec -->|"sends orders"| external
    exec -->|"logs results"| db
    backtest -->|"stores simulation data"| db
    backtest -->|"feedback"| tse
    exec -->|"notifies"| svc
    svc -->|"alerts"| tg

    %% Click Events
    click tse "https://github.com/dogstailfarmer/martin-binance/blob/master/martin_binance/strategy_base.py"
    click exec "https://github.com/dogstailfarmer/martin-binance/blob/master/martin_binance/client.py"
    click backtest "https://github.com/dogstailfarmer/martin-binance/tree/master/martin_binance/backtest"
    click svc "https://github.com/dogstailfarmer/martin-binance/tree/master/martin_binance/service"
    click tg "https://github.com/dogstailfarmer/martin-binance/tree/master/martin_binance/telegram_proxy"
    click db "https://github.com/dogstailfarmer/martin-binance/blob/master/martin_binance/db_utils.py"
    click config "https://github.com/dogstailfarmer/martin-binance/tree/master/martin_binance/templates"
    click infra "https://github.com/dogstailfarmer/martin-binance/tree/master/Dockerfile"

    %% Styles
    classDef configStyle fill:#D1C4E9,stroke:#4A148C,stroke-width:2px,color:white;
    classDef coreStyle fill:#90CAF9,stroke:#0D47A1,stroke-width:2px,color:white;
    classDef serviceStyle fill:#A5D6A7,stroke:#1B5E20,stroke-width:2px,color:white;
    classDef externalStyle fill:#FFF59D,stroke:#F57F17,stroke-width:2px,color:black;
```
