# thuanmaistory/binance-futures-trading-bot architecture

> Architecture diagram of the GitHub repository thuanmaistory/binance-futures-trading-bot, 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/thuanmaistory/binance-futures-trading-bot
- Repository: https://github.com/thuanmaistory/binance-futures-trading-bot

## Overview

##### Main components
- Trading Engine / Bot Core – Represented by main files like src/bot.ts and src/index.ts, this is the entry point managing live operations, API interactions with Binance, and overall coordination.
- Backtesting Module – The src/backtest folder contains key files (bot.ts, database.ts, generateHtmlReport.ts, optimize.ts, etc.) that simulate trading scenarios and generate performance reports.
- Strategy Management – The src/strategies directory is subdivided into entry, exit, and trend strategies. This module implements various trading algorithms and decision-making processes.
- Indicators Library – The src/indicators folder encapsulates technical indicator computations (oscillators, trend, momentum, volatility, volume, and supplementary utilities). These modules are critical since strategies rely on them.
- Configuration Module – Files in src/configs (and the global declaration file globals.d.ts) provide the configuration and customization points for different trading strategies.
- Initialization Utilities – The src/init directory holds the bootstrapping code for setting up the client, logger, JSON config, Telegram bot, and strategy initialization.
- Telegram Notifications – The src/telegram folder manages bot interactions that send notifications to the Telegram channel.
- Utility & Tools Services – The src/utils and src/tools directories offer shared utilities (logging, data loading, mathematical functions, caching, counters, etc.) that support overall operations.
- Machine Learning Module – Although work-in-progress (src/machine_learning), this is planned to extend the system with training and predictive modeling capabilities.
- Test Suites – Several test folders and files validate the functionality of different modules (e.g., tests in src/tools/__tests__, src/utils/__tests__, etc.).

##### Establish Relationships and Interactions
- The Bot Core acts as the conductor: it initializes the system (using src/init modules) and orchestrates interactions between live-trading components and backtesting functionalities.
- Strategy modules read configurations from src/configs and apply various technical indicators (sourced from src/indicators) to determine trading actions.
- In live mode, the bot interacts with Binance APIs (keys configured via .env) and communicates outputs (alerts/notifications) through the Telegram module.
- In Backtesting Mode, the Backtesting Module simulates trade executions, records performance in a database (src/backtest/database.ts), and outputs an HTML report.
- Shared utilities (src/utils and src/tools) are used across modules, so you might show them as supporting components that feed into multiple other areas.
- For machine learning enhancements, a future data flow will include training data collection (possibly from market data extracted by other modules) and model training (via src/machine_learning/train.ts).

##### Architectural Patterns and Design Principles
- Modularity – The clear separation between initialization, strategies, indicators, backtesting, and messaging indicates a modular, layered architecture.
- Extensibility – With custom made strategies and a plug-in approach for indicators, the architecture is designed for easy expansion.
- Separation of Concerns – The project distinguishes between live operations and simulation (backtesting), which are clearly separated in the module hierarchy.
- Testability – The presence of dedicated test folders suggests a design that values automated testing and validation.

##### Extra Details to Highlight
- Initialization sequence (src/init) where environment variables (.env), logging, and Telegram bot setup occur.
- That the strategies (entry and exit, along with risk management) are modular and driven by configuration files in src/configs.
- For backtesting, note the generation of an HTML report via generateHtmlReport.ts and the optimization capabilities.
- Leave placeholders or annotations for future Machine Learning integration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    BotCore["Trading Engine Bot Core<br>(Live Trading & Backtesting)"]:::core
    Init["Initialization Utilities<br>(src/init)"]:::init
    BT["Backtesting Module<br>(src/backtest)"]:::backtest
    Strat["Strategy Management<br>(src/strategies)"]:::strategy
    Config["Configuration Module<br>(src/configs, globals.d.ts)"]:::config
    Ind["Indicators Library<br>(src/indicators)"]:::indicators
    Tele["Telegram Notifications<br>(src/telegram)"]:::tele
    Utils["Utility & Tools Services<br>(src/utils, src/tools)"]:::utils
    ML["Machine Learning Module<br>(src/machine_learning)"]:::ml
    Tests["Test Suites<br>(various tests)"]:::test
    Binance["Binance API"]:::external

    BotCore -->|"init_system"| Init
    BotCore -->|"exec_backtesting"| BT
    BotCore -->|"run_strategy"| Strat
    BotCore -->|"send_notifications"| Tele
    BotCore -->|"utilize_utils"| Utils
    BotCore -->|"connects_to"| Binance

    Init -->|"load_config"| Config
    Init -->|"setup_telegram"| Tele

    Strat -->|"reads_config"| Config
    Strat -->|"uses_indicators"| Ind

    ML -.->|"future_integration"| Strat

    Tests -->|"validate_botcore"| BotCore
    Tests -->|"validate_strategy"| Strat
    Tests -->|"validate_utils"| Utils

    click BotCore "https://github.com/thuanmaistory/binance-futures-trading-bot/blob/master/src/bot.ts"
    click BotCore "https://github.com/thuanmaistory/binance-futures-trading-bot/blob/master/src/index.ts"
    click BT "https://github.com/thuanmaistory/binance-futures-trading-bot/tree/master/src/backtest"
    click Strat "https://github.com/thuanmaistory/binance-futures-trading-bot/tree/master/src/strategies"
    click Ind "https://github.com/thuanmaistory/binance-futures-trading-bot/tree/master/src/indicators"
    click Config "https://github.com/thuanmaistory/binance-futures-trading-bot/tree/master/src/configs"
    click Config "https://github.com/thuanmaistory/binance-futures-trading-bot/blob/master/globals.d.ts"
    click Init "https://github.com/thuanmaistory/binance-futures-trading-bot/tree/master/src/init"
    click Tele "https://github.com/thuanmaistory/binance-futures-trading-bot/tree/master/src/telegram"
    click Utils "https://github.com/thuanmaistory/binance-futures-trading-bot/tree/master/src/utils"
    click Utils "https://github.com/thuanmaistory/binance-futures-trading-bot/tree/master/src/tools"
    click ML "https://github.com/thuanmaistory/binance-futures-trading-bot/tree/master/src/machine_learning"
    click Tests "https://github.com/thuanmaistory/binance-futures-trading-bot/tree/master/src/tools/__tests__"
    click Tests "https://github.com/thuanmaistory/binance-futures-trading-bot/tree/master/src/utils/__tests__"
    click Tests "https://github.com/thuanmaistory/binance-futures-trading-bot/tree/master/src/candles"

    classDef core fill:#f9e79f,stroke:#b7950b,stroke-width:2px
    classDef backtest fill:#d5f5e3,stroke:#27ae60,stroke-width:2px
    classDef strategy fill:#fadbd8,stroke:#e74c3c,stroke-width:2px
    classDef indicators fill:#d6eaf8,stroke:#3498db,stroke-width:2px
    classDef config fill:#f5eef8,stroke:#8e44ad,stroke-width:2px
    classDef init fill:#fef5e7,stroke:#f39c12,stroke-width:2px
    classDef tele fill:#e8f8f5,stroke:#1abc9c,stroke-width:2px
    classDef utils fill:#fcf3cf,stroke:#f1c40f,stroke-width:2px
    classDef ml fill:#f9ebea,stroke:#c0392b,stroke-width:2px
    classDef test fill:#ebedef,stroke:#7f8c8d,stroke-width:2px
    classDef external fill:#d5dbdb,stroke:#95a5a6,stroke-dasharray:5 5
```
