# 0xemmkty/quantmuse architecture

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

- Interactive diagram: https://gitdiagram.com/0xemmkty/quantmuse
- Repository: https://github.com/0xemmkty/quantmuse

## Overview

##### Project type and purpose
- This is a full-stack, production-ready quantitative trading system.
- It combines a Python “data_service” layer (data fetching, factor analysis, AI/ML, storage, backtesting, strategies, dashboards, and web APIs) with a high-performance C++ core engine for order execution, risk management, and strategy execution.

##### File structure
- Top-level:
- backend/ (C++ core engine)
- data_service/ (Python service layer)
- static/ (HTML/CSS/JS front-end assets)
- scripts (main.py, run_*.py, examples/)
- The Python layer is organized into sub-packages: fetchers, ai, backtest, factors, ml, processors, realtime, storage, strategies, visualization, web, utils, vector_db, dashboard.
- The C++ backend follows a CMake project with includes (data_loader, strategy, order_executor, risk_manager) and src files.

##### Key insights from README
- Python layer exposes:
- Data ingestion (multi-source fetchers, real-time via WebSocket)
- Data processing & feature engineering
- Multi-factor models & backtesting
- AI/LLM integration (LangChain, GPT)
- Strategy framework (registry, runner, optimizer)
- Storage (SQLite/Postgres, Redis cache)
- Visualization (Plotly, Streamlit)
- Web API & dashboard (FastAPI)
- C++ layer: low-latency order execution, risk controls, portfolio management.

##### Main components & their relationships
a. Components:
1. Python Data Service
– Fetchers (Binance, Yahoo, Alpha)
– Realtime Module (WebSocket client)
– Data Processor & Feature Engineering
– Storage Layer (DB + Cache)
– AI/ML Module (LLM, NLP, sentiment)
– Factor Analysis & Backtesting Engine (Python)
– Strategy Framework (registry, runner, optimizer)
– Visualization & Dashboard (Plotly, Streamlit)
– Web API (FastAPI)
2. C++ Core Engine
– Data Loader
– Strategy Engine
– Order Executor
– Risk Manager
– Portfolio/Performance Components
3. External Services & Datastores
– Exchanges (Binance, Yahoo Finance, Alpha Vantage)
– OpenAI GPT API
– Databases: PostgreSQL/SQLite
– Redis (cache)
4. Presentation Layer
– Streamlit Dashboard
– FastAPI Web UI + static frontend (HTML/CSS/JS)

b. Interactions:
– Fetchers ← external exchanges
– Realtime WebSocket feeds → Realtime Module → Data Processor
– Processed data → Storage (DB/Redis)
– AI/ML & factor modules read from Storage
– Strategy Framework & Backtester orchestrate strategies using processed data
– For live trading, Python → C++ engine calls (via native binding or subprocess) for low-latency execution
– C++ engine emits execution results & risk alerts → Python Service
– Frontend UIs poll or subscribe (WebSocket or REST) to Python Service for data & metrics
– Admin/user issues commands via UI → Python Service → C++ engine

c. Architectural patterns
– Layered architecture (Python service layer vs C++ engine)
– Pipeline pattern for data ingestion → processing → storage
– Strategy pattern (pluggable strategies, registry)
– Observer/Publisher-Subscriber (real-time feeds, alerts)
– Micro-modules within Python (semi-microservices)
– CI/CD via CMake/carbon for C++ and setuptools/pytest for Python

d. Key technologies
– Python 3.8+, FastAPI, Streamlit, Plotly, LangChain, OpenAI API, pytest
– C++17, CMake, high-performance algorithms
– SQLite/PostgreSQL, Redis
– WebSocket for real-time market data
– Static JS/CSS front-end

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External systems
    subgraph "External Systems"
        EX1["Exchanges\n(Binance, Yahoo, Alpha)"]:::external
        EX2["OpenAI GPT API"]:::external
        DBs["Databases\n(PostgreSQL/SQLite)"]:::db
        REDIS["Redis Cache"]:::db
    end

    %% Python Service Layer
    subgraph "Python Data Service" 
        direction TB
        PS["Python Service"]:::python

        subgraph "Data Ingestion & Processing"
            direction TB
            F["Fetchers"]:::python
            RT["Realtime Module"]:::python
            DP["Data Processor"]:::python
            FE["Feature Engineering"]:::python
        end

        subgraph "Storage & ML"
            direction TB
            SL["Storage Layer"]:::python
            AIM["AI/ML Module"]:::python
        end

        subgraph "Analysis & Strategies"
            direction TB
            FB["Factor & Backtesting"]:::python
            SF["Strategy Framework"]:::python
        end

        subgraph "Visualization & API"
            direction TB
            VIZ["Visualization"]:::ui
            DASH["Dashboard App"]:::ui
            API["Web API"]:::python
        end
    end

    %% C++ Core Engine
    subgraph "C++ Core Engine"
        direction TB
        CPE["C++ Engine"]:::cplusplus
        DL["Data Loader"]:::cplusplus
        SE["Strategy Engine"]:::cplusplus
        OE["Order Executor"]:::cplusplus
        RM["Risk Manager"]:::cplusplus
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        RUNDASH["Dashboard Runner"]:::ui
        RUNWEB["Web UI Runner"]:::ui
        STATIC["Static Assets"]:::ui
    end

    %% External to Python
    EX1 -->|"REST/WebSocket"| F
    EX1 -->|"WebSocket"| RT
    EX2 -->|"API Calls"| AIM
    DBs -->|"SQL"| SL
    REDIS -->|"Cache"| SL

    %% Python internal flows
    F -->|"raw data"| DP
    RT -->|"stream"| DP
    DP -->|"features"| FE
    FE --> SL
    SL --> AIM
    AIM --> FB
    FB --> SF
    SF -->|"live signals"| CPE

    %% C++ Engine flows
    CPE --> DL
    CPE --> SE
    CPE --> OE
    CPE --> RM
    OE --> RM
    RM -->|"alerts"| PS

    %% Python receives from C++
    CPE -->|"execution results"| PS

    %% Python to UI/API
    PS --> API
    API --> RUNWEB
    API --> STATIC
    PS --> VIZ
    PS --> DASH
    RUNDASH --> DASH

    %% Click events
    click PS "https://github.com/0xemmkty/quantmuse/tree/main/data_service/"
    click F "https://github.com/0xemmkty/quantmuse/tree/main/data_service/fetchers/"
    click RT "https://github.com/0xemmkty/quantmuse/tree/main/data_service/realtime/"
    click DP "https://github.com/0xemmkty/quantmuse/blob/main/data_service/processors/data_processor.py"
    click FE "https://github.com/0xemmkty/quantmuse/blob/main/data_service/ml/feature_engineering.py"
    click SL "https://github.com/0xemmkty/quantmuse/tree/main/data_service/storage/"
    click AIM "https://github.com/0xemmkty/quantmuse/tree/main/data_service/ai/"
    click AIM "https://github.com/0xemmkty/quantmuse/tree/main/data_service/ml/"
    click FB "https://github.com/0xemmkty/quantmuse/tree/main/data_service/factors/"
    click FB "https://github.com/0xemmkty/quantmuse/tree/main/data_service/backtest/"
    click SF "https://github.com/0xemmkty/quantmuse/tree/main/data_service/strategies/"
    click VIZ "https://github.com/0xemmkty/quantmuse/tree/main/data_service/visualization/"
    click DASH "https://github.com/0xemmkty/quantmuse/blob/main/data_service/dashboard/dashboard_app.py"
    click API "https://github.com/0xemmkty/quantmuse/blob/main/data_service/web/api_server.py"
    click API "https://github.com/0xemmkty/quantmuse/blob/main/data_service/api/api_manager.py"
    click CPE "https://github.com/0xemmkty/quantmuse/tree/main/backend/"
    click DL "https://github.com/0xemmkty/quantmuse/blob/main/backend/include/data_loader.hpp"
    click DL "https://github.com/0xemmkty/quantmuse/blob/main/backend/src/data_loader.cpp"
    click SE "https://github.com/0xemmkty/quantmuse/blob/main/backend/include/strategy.hpp"
    click SE "https://github.com/0xemmkty/quantmuse/blob/main/backend/src/strategy.cpp"
    click OE "https://github.com/0xemmkty/quantmuse/blob/main/backend/include/order_executor.hpp"
    click OE "https://github.com/0xemmkty/quantmuse/blob/main/backend/src/order_executor.cpp"
    click RM "https://github.com/0xemmkty/quantmuse/blob/main/backend/include/risk_manager.hpp"
    click RM "https://github.com/0xemmkty/quantmuse/blob/main/backend/src/risk_manager.cpp"
    click RUNDASH "https://github.com/0xemmkty/quantmuse/blob/main/run_dashboard.py"
    click RUNWEB "https://github.com/0xemmkty/quantmuse/blob/main/run_web_interface.py"
    click STATIC "https://github.com/0xemmkty/quantmuse/tree/main/static/"

    %% Styles
    classDef python fill:#BBDEFB,stroke:#333,stroke-width:1px
    classDef cplusplus fill:#C8E6C9,stroke:#333,stroke-width:1px
    classDef external fill:#ECEFF1,stroke:#333,stroke-width:1px
    classDef ui fill:#FFE0B2,stroke:#333,stroke-width:1px
    classDef db fill:#B2DFDB,stroke:#333,stroke-width:1px
```
