# tpim/thenextquant architecture

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

- Interactive diagram: https://gitdiagram.com/tpim/thenextquant
- Repository: https://github.com/tpim/thenextquant

## Overview

##### Project Type and Purpose
- The project is an asynchronous event-driven quantitative trading and market-making system.
- It’s designed to support crypto exchange integrations (e.g., Binance, Huobi, OKEx) with asynchronous I/O (using Python’s asyncio along with aiohttp and aioamqp).
- It leverages external systems (RabbitMQ for event publishing/subscription and optionally MongoDB for data storage) to handle key trading system functionalities.

##### File Structure
- Core Directory – “quant”: This is the heart of the framework and contains modules such as:
- quant/quant.py (central engine)
- Modules for market, trade, asset, order, etc.
- Helper modules like “quant/utils” for decorators, logging, web utilities, and “quant/platform” for exchange-specific connectors (binance.py, huobi.py, okex.py).
- Example Directory – “example”: Contains implementations and configuration samples for different exchanges; highlights how an end user can set up their trading strategy.
- Documentation – “docs”: Provides configuration, usage instructions, and architecture overviews (with schematic images referenced).
- Setup & Configuration – Files like setup.py, config.py, config.json (in multiple locations) signal that configuration is key to the architecture.

##### Extract Architectural and Technical Insights from the README
- The system uses Python’s native asynchronous capabilities (asyncio) for event-driven operations.
- External services include:
- RabbitMQ: For event streaming (publishing and subscribing to events).
- MongoDB (optional): For persistent data storage.
- The README points to examples demonstrating how to plug in strategies and interact with various exchanges.

a. Main Components to Include:
- Core Trading Engine (in the “quant” directory):
- Event Handling Module: (quant/event.py, heartbeat, tasks)
- Business Logic Modules: (market.py, trade.py, asset.py, order.py, position.py)
- Configuration Management: (quant/config.py, const.py)
- Exchange Integration Layer:
- “quant/platform” modules: Each file (binance.py, huobi.py, okex.py) acts as a connector for specific exchange API interactions.
- Example implementations: “example/binance”, “example/huobi”, “example/okex” show how configurations and concrete trading operations are executed.
- Utility and Support Components:
- Utility libraries (logging, tools, web) to support asynchronous operations.
- Decorator support for event-driven triggers.
- External Dependencies:
- RabbitMQ: Indicated for event communication.
- MongoDB: (Optional) for persistent storage.
- Python Async Libraries: aiohttp and aioamqp ensuring the asynchronous non-blocking I/O behavior.

b. Relationships and Interactions:
- From the core engine invoking exchange connectors.
- From the exchange connectors back to the core engine with market data and order execution responses.
- Event propagation paths: how events are generated (by tasks, heartbeat) and propagated via RabbitMQ.
- How utilities feed into the core modules (e.g., logging, decorators).
- Separate the asynchronous event loop (the backbone of the entire system) from the business logic modules. Represent how the event loop manages callbacks and asynchronous communications.

c. Highlighting Architectural Patterns:
- Asynchronous/Event-Driven Architecture: Emphasize the use of asyncio; denote event publishers and subscribers.
- Modular Design: Clearly separate exchange connectors in “quant/platform” from core logic in “quant”.
- Configuration Driven: Show that the system is highly configurable via JSON files (config.json) and scripts demonstrated in the examples.

d. Relevant Technologies:
- Language: Python 3.5.3+
- Frameworks/Libraries: asyncio, aiohttp, aioamqp, motor (for MongoDB integration)
- External Systems: RabbitMQ, MongoDB (optional)
- Miscellaneous: Usage of decorators and event handlers for asynchronous patterns.

- Yet another for external services (RabbitMQ, MongoDB)
- Brief annotations where necessary to explain the roles (e.g., “Handles asynchronous event publishing” for RabbitMQ).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Core Processing Layer"
        Config["Configuration Management"]:::config
        QEngine["Core Trading Engine"]:::core
        Evt["Event Handling Module"]:::core
        Heart["Heartbeat"]:::core
        Market["Market Module"]:::core
        Trade["Trade Module"]:::core
        Order["Order Module"]:::core
        Asset["Asset Module"]:::core
        Position["Position Module"]:::core
    end

    subgraph "Integration Layer"
        Bin["Binance Connector"]:::integration
        Huobi["Huobi Connector"]:::integration
        OKEx["OKEx Connector"]:::integration
    end

    subgraph "Utility & Support Layer"
        Util["Utilities (Decorators, Logging, Web Tools)"]:::utility
    end

    subgraph "Messaging & Storage Layer"
        RabbitMQ["RabbitMQ (Messaging)"]:::external
        MongoDB["MongoDB (Storage)"]:::external
    end

    %% Relationships in Core Processing Layer
    Config -->|"loads"| QEngine
    QEngine -->|"initiates"| Evt
    Evt -->|"triggers"| Heart
    QEngine -->|"handles"| Market
    QEngine -->|"handles"| Trade
    QEngine -->|"handles"| Order
    QEngine -->|"handles"| Asset
    QEngine -->|"handles"| Position

    %% Relationships with Integration Layer
    QEngine -->|"invokes"| Bin
    QEngine -->|"invokes"| Huobi
    QEngine -->|"invokes"| OKEx
    Bin -->|"returns_data"| Trade
    Huobi -->|"returns_data"| Trade
    OKEx -->|"returns_data"| Trade

    %% Messaging & Storage Interactions
    Evt -->|"publishes_events"| RabbitMQ
    RabbitMQ -->|"dispatches_events"| Evt
    Trade -->|"stores_transactions"| MongoDB

    %% Utility support relationship
    Util -->|"supports"| QEngine
    Util -->|"supports"| Evt
    Util -->|"supports"| Market
    Util -->|"supports"| Trade
    Util -->|"supports"| Order

    %% Click Events for Core Processing Layer
    click QEngine "https://github.com/tpim/thenextquant/blob/master/quant/quant.py"
    click Evt "https://github.com/tpim/thenextquant/blob/master/quant/event.py"
    click Heart "https://github.com/tpim/thenextquant/blob/master/quant/heartbeat.py"
    click Market "https://github.com/tpim/thenextquant/blob/master/quant/market.py"
    click Trade "https://github.com/tpim/thenextquant/blob/master/quant/trade.py"
    click Order "https://github.com/tpim/thenextquant/blob/master/quant/order.py"
    click Asset "https://github.com/tpim/thenextquant/blob/master/quant/asset.py"
    click Position "https://github.com/tpim/thenextquant/blob/master/quant/position.py"
    click Config "https://github.com/tpim/thenextquant/blob/master/quant/config.py"
    click Config "https://github.com/tpim/thenextquant/blob/master/quant/const.py"

    %% Click Events for Integration Layer
    click Bin "https://github.com/tpim/thenextquant/blob/master/quant/platform/binance.py"
    click Huobi "https://github.com/tpim/thenextquant/blob/master/quant/platform/huobi.py"
    click OKEx "https://github.com/tpim/thenextquant/blob/master/quant/platform/okex.py"

    %% Click Event for Utility & Support Layer
    click Util "https://github.com/tpim/thenextquant/tree/master/quant/utils/"

    %% Click Event for Messaging & Storage Layer (Documentation for RabbitMQ)
    click RabbitMQ "https://github.com/tpim/thenextquant/blob/master/docs/others/rabbitmq_deploy.md"

    %% Styles
    classDef core fill:#FAD7A0,stroke:#E67E22,stroke-width:2px;
    classDef integration fill:#AED6F1,stroke:#5DADE2,stroke-width:2px;
    classDef external fill:#ABEBC6,stroke:#28B463,stroke-width:2px;
    classDef utility fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;
    classDef config fill:#F9E79F,stroke:#F39C12,stroke-width:2px;
```
