# ebolaboy/gridbnb-usdt architecture

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

- Interactive diagram: https://gitdiagram.com/ebolaboy/gridbnb-usdt
- Repository: https://github.com/ebolaboy/gridbnb-usdt

## Overview

##### Project type and purpose
- This is a Python‑based automated grid trading bot tailored for the Binance BNB/USDT pair.
- Core features: grid order execution, dynamic grid sizing, risk management, web UI for monitoring, state persistence, notification, and logging.

##### File structure
- Top‑level scripts/modules:
- main.py – orchestrator.
- exchange_client.py – interface with Binance REST/WebSocket APIs.
- trader.py – implements the grid order logic.
- position_controller_s1.py – manages position sizing.
- risk_manager.py – enforces drawdown/ daily loss/position ratio limits.
- order_tracker.py – tracks live orders & fills.
- monitor.py – collects metrics (e.g., PnL, open orders).
- web_server.py – minimal Flask/Tornado web UI.
- helpers.py – shared utilities (e.g., JSON I/O for `data/`).
- config.py – all strategy parameters (grid, risk, symbol).
- Config & environment: `.env.example`, config.py, requirements.txt.
- Persistence: JSON files under `data/` (though not shown in file tree, mentioned in README).
- Logging: trading_system.log.
- Deployment: simple script update_git.ps1 (for Windows).

##### README for additional insights
- Describes dynamic grid adjustment based on volatility.
- Web UI on port 8080, live metrics & manual adjustments.
- PushPlus integration for notifications.
- Emphasis on state recovery on restart.

##### Main components and interactions
a. Components
1. Orchestrator (main.py)
2. Configuration (config.py + .env)
3. Exchange Client (exchange_client.py)
4. Risk Manager (risk_manager.py)
5. Controller (position_controller_s1.py)
6. Trader/Grid Logic (trader.py)
7. Order Tracker (order_tracker.py)
8. Monitor & Notification (monitor.py + PushPlus)
9. Persistence (helpers.py → JSON under data/)
10. Web Server (web_server.py)
11. Logging (built‑in Python logger → trading_system.log)
12. External Services: Binance API, PushPlus API

b. Relationships & data flows
- main.py reads config & .env → initializes modules
- main.py → Exchange Client for market data & order placement
- Trader uses Exchange Client → places grid orders
- Order Tracker listens to fills/status via Exchange Client or WebSocket
- Controller receives fill events → adjusts target positions
- Risk Manager intercepts trade proposals → allows/blocks based on drawdown/daily loss
- Monitor collects snapshots from all modules → stores via helpers & optionally pushes alerts
- Web Server fetches state via helpers (JSON) & in‑memory caches → serves UI
- Notifications module (in monitor or risk_manager) calls PushPlus when thresholds breached
- Logging across every module for audit trail

c. Architectural patterns & design principles
- Modular service‑layer design: each concern (execution, risk, persistence, UI) in its own module
- Single orchestrator entry point (main.py)
- Dependency injection via config.py & environment variables
- Event‑driven flow: fills & market data trigger reactions in tracker, controller, risk manager
- State persistence for fault tolerance and restart recovery

d. Key technologies & libraries
- Python 3.8+
- Requests or ccxt for REST calls (in exchange_client.py)
- Web framework: Flask or asyncio HTTP server (in web_server.py)
- dotenv for environment loading
- PushPlus HTTP API for notifications
- Python logging module

- Layer 1 (Orchestration): main.py, config.py, .env
- Layer 2 (Core Engine): exchange_client, trader, order_tracker, position_controller, risk_manager
- Layer 3 (Support): monitor, helpers (for JSON), logger
- Layer 4 (External): Binance REST/WebSocket, PushPlus API
- Layer 5 (UI): web_server.py → browser

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layer 1: Orchestration
    subgraph "Orchestration Layer"
        direction TB
        Orchestrator["main.py"]:::orchestration
        ConfigFile["config.py"]:::orchestration
        EnvFile[".env.example"]:::orchestration
    end

    %% Layer 2: Core Engine
    subgraph "Core Trading Engine" 
        direction TB
        ExchangeClient["exchange_client.py"]:::core
        Trader["trader.py"]:::core
        OrderTracker["order_tracker.py"]:::core
        PositionController["position_controller_s1.py"]:::core
        RiskManager["risk_manager.py"]:::core
    end

    %% Layer 3: Support
    subgraph "Support Services"
        direction TB
        Monitor["monitor.py"]:::support
        Helpers["helpers.py"]:::persistence
        Logger["trading_system.log"]:::support
    end

    %% Layer 4: External Services
    subgraph "External Services"
        direction TB
        BinanceAPI["Binance REST/WebSocket"]:::external
        PushPlusAPI["PushPlus API"]:::external
    end

    %% Layer 5: UI
    subgraph "Web UI Layer"
        direction TB
        WebServer["web_server.py"]:::ui
        Browser["Browser (UI)"]:::ui
    end

    %% Connections
    Orchestrator -->|"load config & env"| ConfigFile
    Orchestrator -->|".env variables"| EnvFile
    Orchestrator -->|"init modules"| ExchangeClient
    Orchestrator -->|"init modules"| Trader
    Orchestrator -->|"init modules"| OrderTracker
    Orchestrator -->|"init modules"| PositionController
    Orchestrator -->|"init modules"| RiskManager
    Orchestrator -->|"init modules"| Monitor
    Orchestrator -->|"init modules"| WebServer

    Trader -->|"order request"| ExchangeClient
    ExchangeClient -->|"market data"| BinanceAPI
    ExchangeClient -->|"order placement"| BinanceAPI
    BinanceAPI -->|"fill events"| OrderTracker
    OrderTracker -->|"fill event"| PositionController
    PositionController -->|"position update"| RiskManager
    RiskManager -->|"trade approval"| Trader

    Monitor -->|"collect metrics"| ExchangeClient
    Monitor -->|"collect metrics"| Trader
    Monitor -->|"collect metrics"| OrderTracker
    Monitor -->|"store state"| Helpers
    Helpers -->|"write/read JSON"| Helpers
    Helpers -->|"persist state"| Helpers
    Helpers -->|"state files under data/"| Helpers

    WebServer -->|"read state"| Helpers
    Browser -->|"HTTP requests"| WebServer
    Monitor -->|"alert thresholds"| PushPlusAPI
    RiskManager -->|"risk breach alert"| PushPlusAPI

    %% Logging
    Orchestrator -->|"log events"| Logger
    ExchangeClient -->|"log events"| Logger
    Trader -->|"log events"| Logger
    OrderTracker -->|"log events"| Logger
    PositionController -->|"log events"| Logger
    RiskManager -->|"log events"| Logger
    Monitor -->|"log events"| Logger
    WebServer -->|"log events"| Logger

    %% Click Events
    click Orchestrator "https://github.com/ebolaboy/gridbnb-usdt/blob/main/main.py"
    click ConfigFile "https://github.com/ebolaboy/gridbnb-usdt/blob/main/config.py"
    click EnvFile "https://github.com/ebolaboy/gridbnb-usdt/blob/main/.env.example"
    click ExchangeClient "https://github.com/ebolaboy/gridbnb-usdt/blob/main/exchange_client.py"
    click Trader "https://github.com/ebolaboy/gridbnb-usdt/blob/main/trader.py"
    click OrderTracker "https://github.com/ebolaboy/gridbnb-usdt/blob/main/order_tracker.py"
    click PositionController "https://github.com/ebolaboy/gridbnb-usdt/blob/main/position_controller_s1.py"
    click RiskManager "https://github.com/ebolaboy/gridbnb-usdt/blob/main/risk_manager.py"
    click Monitor "https://github.com/ebolaboy/gridbnb-usdt/blob/main/monitor.py"
    click Helpers "https://github.com/ebolaboy/gridbnb-usdt/blob/main/helpers.py"
    click WebServer "https://github.com/ebolaboy/gridbnb-usdt/blob/main/web_server.py"
    click Logger "https://github.com/ebolaboy/gridbnb-usdt/blob/main/trading_system.log"
    click Orchestrator "https://github.com/ebolaboy/gridbnb-usdt/blob/main/update_git.ps1"

    %% Styles
    classDef orchestration fill:#f0f0f0,stroke:#333,stroke-width:1px;
    classDef core fill:#cce5ff,stroke:#333,stroke-width:1px;
    classDef support fill:#ffe6cc,stroke:#333,stroke-width:1px;
    classDef persistence fill:#d4edda,stroke:#333,stroke-width:1px;
    classDef external fill:#ffe5b4,stroke:#333,stroke-width:1px;
    classDef ui fill:#e0bbff,stroke:#333,stroke-width:1px;
```
