# 51bitquant/howtrader architecture

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

- Interactive diagram: https://gitdiagram.com/51bitquant/howtrader
- Repository: https://github.com/51bitquant/howtrader

## Overview

##### Project type and purpose
- HowTrader is a Python‑based, event‑driven quantitative trading framework (forked and enhanced from VNPY).
- It provides a desktop GUI (PyQt), a plugin‑style set of “apps” (CTA strategies, algo trading, data management, recording, portfolio, risk, spread trading, TradingView integration), exchange gateways (REST + WebSocket), and a lightweight HTTP server for webhook (TradingView) signals.

##### Key architectural layers & top‑level components
A. User Interface Layer
- PyQt GUI – MainWindow, widgets under `howtrader/trader/ui`
- Flask HTTP server – webhook endpoint for TradingView (`main()` spawns a Flask app listening on `/webhook`)
B. Event & Core Engine Layer
- EventEngine – centralized pub/sub message bus (`howtrader/event/engine.py`)
- MainEngine – orchestrates gateways & apps (`howtrader/trader/engine.py`)
C. Gateway & API Adapters
- REST client (`howtrader/api/rest/rest_client.py`)
- WebSocket client (`howtrader/api/websocket/websocket_client.py`)
- Exchange gateways – Binance (spot/future/inverse), OKX (`howtrader/gateway/*`)
D. Application (Plugin) Layer
- CTA Strategy App (`howtrader/app/cta_strategy`)
- Algo Trading App (`howtrader/app/algo_trading`)
- DataManager, DataRecorder, PortfolioManager, PortfolioStrategy, RiskManager, SpreadTrading, TradingView apps
- Each app contains: engine, base template, UI widgets, specific strategy modules
E. Data Layer
- Database connectors – SQLite, MongoDB, MySQL (`howtrader/trader/dbconnectors`)
- Object models – OrderData, TradeData, ContractData with high‑precision Decimal (`howtrader/trader/object.py`)
- Charting & historical data retrieval (`howtrader/chart`)

##### Relationships & interactions
- GUI and HTTP server → publish user actions or incoming webhook as Event → EventEngine
- EventEngine → dispatch events to MainEngine
- MainEngine → routes market‑data events from Gateways → Apps/Strategies
- Strategies in Apps → generate orders (OrderData) → MainEngine → route to Gateways
- Gateways → send REST/WebSocket requests to external exchange APIs → receive fills/trades → push back as Events
- MainEngine → persists data via Database connectors → DataRecorder App/UI
- Backtesting loop: BacktestingEngine → loads historical bars from DB → drives strategy logic offline

##### Architectural patterns & design principles
- Event‑driven pub/sub core (decouples modules)
- Plugin architecture (“apps” can be added/removed at runtime)
- Adapter pattern for different gateways & databases
- Layered separation: UI, Core, Adapters, Data
- Single‑responsibility per module (each app only manages its domain)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        GUI["PyQt GUI (MainWindow & Widgets)"]:::ui
        HTTP["Flask HTTP Server (/webhook)"]:::ui
    end

    %% Core Engine Layer
    subgraph "Core Engine Layer"
        EE["EventEngine"]:::core
        ME["MainEngine"]:::core
        BE["BacktestingEngine"]:::core
    end

    %% Gateway & API Adapters Layer
    subgraph "Gateway & API Adapters"
        REST["REST Client"]:::adapter
        WS["WebSocket Client"]:::adapter
        subgraph "Exchange Gateways"
            BIN_SPOT["Binance Spot GW"]:::adapter
            BIN_USDT["Binance USDT GW"]:::adapter
            BIN_INV["Binance Inverse GW"]:::adapter
            OKX["OKX GW"]:::adapter
        end
    end

    %% Plugin Apps Layer
    subgraph "Plugin Apps"
        CTA["CTA Strategy App"]:::app
        ALGO["Algo Trading App"]:::app
        DM["Data Manager App"]:::app
        DR["Data Recorder App"]:::app
        PM["Portfolio Manager App"]:::app
        PS["Portfolio Strategy App"]:::app
        RM["Risk Manager App"]:::app
        SPREAD["Spread Trading App"]:::app
        TV["TradingView App"]:::app
    end

    %% Data Layer
    subgraph "Data Layer"
        DB_SQL["SQLite Connector"]:::adapter
        DB_MONGO["MongoDB Connector"]:::adapter
        DB_MYSQL["MySQL Connector"]:::adapter
        OBJECTS["Object Models"]:::core
        CHART["Chart & Historical Data"]:::data
    end

    %% External Services
    subgraph "External Services"
        EXCH["Exchanges"]:::external
        TVEXT["TradingView"]:::external
    end

    %% Connections
    GUI -->|"UserActionEvent"| EE
    HTTP -->|"TVSignalEvent"| EE
    EE -->|"Dispatch"| ME
    BE -->|"BacktestingFlow"| ME

    ME -->|"MarketDataEvent"| CTA
    ME -->|"MarketDataEvent"| ALGO
    ME -->|"MarketDataEvent"| DM
    ME -->|"MarketDataEvent"| PS
    ME -->|"MarketDataEvent"| SPREAD
    ME -->|"MarketDataEvent"| TV

    CTA -->|"OrderEvent"| ME
    ALGO -->|"OrderEvent"| ME
    PS -->|"OrderEvent"| ME
    SPREAD -->|"OrderEvent"| ME
    TV -->|"OrderEvent"| ME

    ME --> REST
    ME --> WS

    REST -->|"REST API"| EXCH
    WS -->|"WebSocket API"| EXCH

    EXCH -->|"TradeEvent"| EE

    ME --> DB_SQL
    ME --> DB_MONGO
    ME --> DB_MYSQL

    DB_SQL --> CHART
    DB_MONGO --> CHART
    DB_MYSQL --> CHART

    EE --> DR
    GUI --> CHART

    %% Click Events
    click GUI "https://github.com/51bitquant/howtrader/tree/main/howtrader/trader/ui"
    click HTTP "https://github.com/51bitquant/howtrader/blob/main/howtrader/app/tradingview/engine.py"
    click EE "https://github.com/51bitquant/howtrader/blob/main/howtrader/event/engine.py"
    click ME "https://github.com/51bitquant/howtrader/blob/main/howtrader/trader/engine.py"
    click REST "https://github.com/51bitquant/howtrader/blob/main/howtrader/api/rest/rest_client.py"
    click WS "https://github.com/51bitquant/howtrader/blob/main/howtrader/api/websocket/websocket_client.py"
    click BIN_SPOT "https://github.com/51bitquant/howtrader/blob/main/howtrader/gateway/binance/binance_spot_gateway.py"
    click BIN_USDT "https://github.com/51bitquant/howtrader/blob/main/howtrader/gateway/binance/binance_usdt_gateway.py"
    click BIN_INV "https://github.com/51bitquant/howtrader/blob/main/howtrader/gateway/binance/binance_inverse_gateway.py"
    click OKX "https://github.com/51bitquant/howtrader/blob/main/howtrader/gateway/okx/okx_gateway.py"
    click CTA "https://github.com/51bitquant/howtrader/tree/main/howtrader/app/cta_strategy"
    click ALGO "https://github.com/51bitquant/howtrader/tree/main/howtrader/app/algo_trading"
    click DM "https://github.com/51bitquant/howtrader/tree/main/howtrader/app/data_manager"
    click DR "https://github.com/51bitquant/howtrader/tree/main/howtrader/app/data_recorder"
    click PM "https://github.com/51bitquant/howtrader/tree/main/howtrader/app/portfolio_manager"
    click PS "https://github.com/51bitquant/howtrader/tree/main/howtrader/app/portfolio_strategy"
    click RM "https://github.com/51bitquant/howtrader/tree/main/howtrader/app/risk_manager"
    click SPREAD "https://github.com/51bitquant/howtrader/tree/main/howtrader/app/spread_trading"
    click TV "https://github.com/51bitquant/howtrader/tree/main/howtrader/app/tradingview"
    click DB_SQL "https://github.com/51bitquant/howtrader/blob/main/howtrader/trader/dbconnectors/sqlite_database.py"
    click DB_MONGO "https://github.com/51bitquant/howtrader/blob/main/howtrader/trader/dbconnectors/mongo_database.py"
    click DB_MYSQL "https://github.com/51bitquant/howtrader/blob/main/howtrader/trader/dbconnectors/mysql_database.py"
    click OBJECTS "https://github.com/51bitquant/howtrader/blob/main/howtrader/trader/object.py"
    click CHART "https://github.com/51bitquant/howtrader/tree/main/howtrader/chart"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef app fill:#98FB98,stroke:#000,stroke-width:1px
    classDef adapter fill:#FFFF99,stroke:#000,stroke-width:1px
    classDef ui fill:#FFA500,stroke:#000,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef data fill:#E0FFFF,stroke:#000,stroke-width:1px
```
