# trademonk-llc/quantking architecture

> Architecture diagram of the GitHub repository trademonk-llc/quantking, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/trademonk-llc/quantking
- Repository: https://github.com/trademonk-llc/quantking

## Overview

1. **Overall shape**
   - This repository is a hybrid quantitative trading platform with a **Python orchestration layer** and a **C++ execution/risk core**.
   - The Python side handles data ingestion, analytics, AI/ML, backtesting, visualization, and web/UI entrypoints.
   - The C++ side in `backend/` is the low-latency engine for data loading, strategy execution, order execution, and risk checks.

2. **Primary runtime boundary**
   - `data_service/` is the main application layer and the center of most workflows.
   - `backend/` is a separate compiled subsystem built with **CMake/C++17**.
   - The two layers are architecturally distinct: Python coordinates and analyzes; C++ is intended for performance-sensitive execution and risk control.

3. **Data acquisition layer**
   - Market data comes from multiple fetchers in `data_service/fetchers/`: **Binance**, **Yahoo Finance**, and **Alpha Vantage**.
   - Real-time inputs are handled by `data_service/realtime/`, which includes WebSocket client/feed components.
   - This layer is the entry point for both historical and live market data, feeding downstream processing, factors, strategies, and dashboards.

4. **Processing and storage boundary**
   - `data_service/processors/` normalizes and prepares raw market data.
   - `data_service/storage/` provides persistence and caching via file, database, and cache managers.
   - The README indicates support for **SQLite, PostgreSQL, and Redis**, so storage is not just archival; it also acts as a low-latency cache and state layer for analytics and UI.

5. **Quantitative analytics pipeline**
   - `data_service/factors/` implements factor research: calculation, screening, backtesting, optimization, and stock selection.
   - `data_service/ml/` provides feature engineering and model abstractions for predictive analytics.
   - This layer transforms normalized market data into tradable signals, factor scores, and model features used by strategies and portfolio analysis.

6. **Strategy subsystem**
   - `data_service/strategies/` is the extensible strategy framework.
   - It includes a base strategy abstraction, built-in strategies, a registry, runner, and optimizer.
   - The architecture here is plugin-like: strategy definitions are separated from execution/selection, which makes it possible to swap or optimize strategies without changing the rest of the pipeline.

7. **Backtesting and performance analysis**
   - `data_service/backtest/` contains the simulation engine and performance analysis.
   - This subsystem consumes historical data and strategy outputs to produce evaluation metrics before any live deployment.
   - It sits between strategy research and production execution, serving as the validation boundary for the trading logic.

8. **AI/NLP subsystem**
   - `data_service/ai/` contains LLM integration, NLP processing, news processing, sentiment analysis, sentiment factors, and social media monitoring.
   - This is an optional enrichment layer that consumes unstructured text and external signals, then converts them into sentiment or recommendation inputs.
   - It integrates with the rest of the system through analysis outputs rather than directly controlling execution.

9. **Web and dashboard interfaces**
   - There are two UI paths: `data_service/web/` for a web interface/API server and `data_service/dashboard/` plus `data_service/visualization/` for charting/dashboard components.
   - The repo also includes `static/` assets, indicating a browser-based frontend served by the Python web layer.
   - Entry scripts like `run_web_interface.py`, `run_web_simple.py`, and `run_dashboard.py` suggest multiple deployment modes: a full web app, a simpler interface, and a dashboard-focused mode.

10. **Core execution and risk control**
   - The C++ backend defines `data_loader`, `strategy`, `order_executor`, and `risk_manager`.
   - This implies a clear production path: load market data, evaluate strategy, check risk, and execute orders.
   - `backend/tests/` includes targeted tests for the data loader and risk manager, reinforcing that these are critical safety boundaries.

11. **Configuration and environment**
   - `config.example.json` shows the system is driven by external configuration for API credentials and service settings.
   - `data_service/config.py` likely centralizes runtime configuration for the Python layer.
   - The system depends on external providers such as **Binance**, **Yahoo Finance**, **Alpha Vantage**, and **OpenAI** when those modules are enabled.

12. **Support utilities and observability**
   - `data_service/utils/` provides shared logging and custom exceptions.
   - This is the cross-cutting support layer used by ingestion, processing, AI, strategy, and web modules.
   - It’s important for tracing failures across a multi-stage pipeline that spans live data, analytics, and execution.

13. **Entrypoints and usage modes**
   - `main.py` is the likely top-level application entry.
   - The repository also includes many example scripts under `examples/`, which function as runnable slices of the architecture: fetch data, run factor analysis, backtest strategies, or exercise AI components.
   - These examples are useful for understanding subsystem boundaries because they each activate only part of the pipeline.

14. **How the data flows end-to-end**
   - The typical flow is: **external data sources → fetchers/realtime feeds → processors/storage → factors/ml/AI → strategy/backtest → web visualization or C++ execution**.
   - Historical analysis and live trading share the same upstream data and strategy abstractions, but they diverge at the validation/execution boundary.
   - The C++ backend is the operational core, while Python is the research, orchestration, and presentation layer.

Main entry points: [`data_service/strategies`](https://github.com/trademonk-llc/quantking/tree/main/data_service/strategies) (Strategies), [`main.py`](https://github.com/trademonk-llc/quantking/blob/main/main.py) (Main app), [`data_service/fetchers`](https://github.com/trademonk-llc/quantking/tree/main/data_service/fetchers) (Market fetchers), [`data_service/web`](https://github.com/trademonk-llc/quantking/tree/main/data_service/web) (Web/API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_python_layer["Python trading platform"]
  node_main_entry(("Main app<br/>python entrypoint<br/>[main.py]"))
  node_config["Config"]
  node_fetchers["Market fetchers<br/>data acquisition"]
  node_realtime["Live feed<br/>realtime ingest"]
  node_processors["Data processor<br/>normalization"]
  node_storage[("Storage layer<br/>persistence/cache")]
  node_factors["Factors<br/>quant research"]
  node_ml["ML features<br/>predictive analytics"]
  node_ai["AI/NLP<br/>unstructured signals"]
  node_strategies["Strategies<br/>strategy framework"]
  node_backtest["Backtest<br/>simulation"]
  node_api_web["Web/API<br/>serving layer"]
  node_dashboard_vis["Dashboard<br/>presentation"]
  node_visualization["Charts<br/>visualization"]
  node_vector_db[("Vector store<br/>semantic storage")]
  node_utils["Shared utils<br/>cross-cutting support"]
end

subgraph group_cpp_core["C++ execution core"]
  node_cpp_loader["Data loader<br/>cpp runtime<br/>[data_loader.hpp]"]
  node_cpp_strategy["Strategy core<br/>cpp runtime<br/>[strategy.hpp]"]
  node_cpp_risk["Risk manager<br/>cpp runtime<br/>[risk_manager.hpp]"]
  node_cpp_orders["Order executor<br/>cpp runtime<br/>[order_executor.hpp]"]
  node_cpp_main(("Backend main<br/>cpp entrypoint<br/>[main.cpp]"))
end

node_main_entry -->|"orchestrates"| node_fetchers
node_main_entry -->|"orchestrates"| node_realtime
node_main_entry -->|"launches"| node_api_web
node_main_entry -->|"launches"| node_dashboard_vis
node_config -->|"configures"| node_fetchers
node_config -->|"configures"| node_realtime
node_fetchers -->|"feeds"| node_processors
node_realtime -->|"feeds"| node_processors
node_processors -->|"persists"| node_storage
node_storage -->|"serves"| node_factors
node_storage -->|"serves"| node_ml
node_factors -->|"signals"| node_strategies
node_ml -->|"features"| node_strategies
node_ai -->|"stores"| node_vector_db
node_ai -->|"augments"| node_strategies
node_strategies -->|"validated by"| node_backtest
node_backtest -->|"exposes"| node_api_web
node_dashboard_vis -->|"renders with"| node_visualization
node_api_web -->|"uses"| node_visualization
node_utils -.->|"supports"| node_fetchers
node_utils -.->|"supports"| node_strategies
node_utils -.->|"supports"| node_api_web
node_cpp_main -->|"starts"| node_cpp_loader
node_cpp_main -->|"starts"| node_cpp_strategy
node_cpp_strategy -->|"checks"| node_cpp_risk
node_cpp_risk -->|"permits"| node_cpp_orders
node_cpp_loader -->|"provides data"| node_cpp_strategy

click node_main_entry "https://github.com/trademonk-llc/quantking/blob/main/main.py"
click node_config "https://github.com/trademonk-llc/quantking/blob/main/config.example.json"
click node_fetchers "https://github.com/trademonk-llc/quantking/tree/main/data_service/fetchers"
click node_realtime "https://github.com/trademonk-llc/quantking/tree/main/data_service/realtime"
click node_processors "https://github.com/trademonk-llc/quantking/tree/main/data_service/processors"
click node_storage "https://github.com/trademonk-llc/quantking/tree/main/data_service/storage"
click node_factors "https://github.com/trademonk-llc/quantking/tree/main/data_service/factors"
click node_ml "https://github.com/trademonk-llc/quantking/tree/main/data_service/ml"
click node_ai "https://github.com/trademonk-llc/quantking/tree/main/data_service/ai"
click node_strategies "https://github.com/trademonk-llc/quantking/tree/main/data_service/strategies"
click node_backtest "https://github.com/trademonk-llc/quantking/tree/main/data_service/backtest"
click node_api_web "https://github.com/trademonk-llc/quantking/tree/main/data_service/web"
click node_dashboard_vis "https://github.com/trademonk-llc/quantking/tree/main/data_service/dashboard"
click node_visualization "https://github.com/trademonk-llc/quantking/tree/main/data_service/visualization"
click node_vector_db "https://github.com/trademonk-llc/quantking/tree/main/data_service/vector_db"
click node_utils "https://github.com/trademonk-llc/quantking/tree/main/data_service/utils"
click node_cpp_loader "https://github.com/trademonk-llc/quantking/blob/main/backend/include/data_loader.hpp"
click node_cpp_strategy "https://github.com/trademonk-llc/quantking/blob/main/backend/include/strategy.hpp"
click node_cpp_risk "https://github.com/trademonk-llc/quantking/blob/main/backend/include/risk_manager.hpp"
click node_cpp_orders "https://github.com/trademonk-llc/quantking/blob/main/backend/include/order_executor.hpp"
click node_cpp_main "https://github.com/trademonk-llc/quantking/blob/main/backend/src/main.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main_entry,node_config,node_fetchers,node_realtime,node_processors,node_storage,node_factors,node_ml,node_ai,node_strategies,node_backtest,node_api_web,node_dashboard_vis,node_visualization,node_vector_db,node_utils toneBlue
class node_cpp_loader,node_cpp_strategy,node_cpp_risk,node_cpp_orders,node_cpp_main toneAmber
```

## Components

### Python trading platform

Orchestration, analytics, UI, and research workflows

- [Main app](https://github.com/trademonk-llc/quantking/blob/main/main.py): python entrypoint · Top-level application entry and mode selection · `main.py`
- [Config](https://github.com/trademonk-llc/quantking/blob/main/config.example.json): runtime config · Externalized service and credential settings · `config.example.json`
- [Market fetchers](https://github.com/trademonk-llc/quantking/tree/main/data_service/fetchers): data acquisition · Historical data connectors for major market providers · `data_service/fetchers`
- [Live feed](https://github.com/trademonk-llc/quantking/tree/main/data_service/realtime): realtime ingest · WebSocket client and streaming market inputs · `data_service/realtime`
- [Data processor](https://github.com/trademonk-llc/quantking/tree/main/data_service/processors): normalization · Transforms raw market data into usable datasets · `data_service/processors`
- [Storage layer](https://github.com/trademonk-llc/quantking/tree/main/data_service/storage): persistence/cache · File, database, and cache managers for state and analytics · `data_service/storage`
- [Factors](https://github.com/trademonk-llc/quantking/tree/main/data_service/factors): quant research · Factor calculation, screening, backtest, optimization, and selection · `data_service/factors`
- [ML features](https://github.com/trademonk-llc/quantking/tree/main/data_service/ml): predictive analytics · Feature engineering and model abstractions · `data_service/ml`
- [AI/NLP](https://github.com/trademonk-llc/quantking/tree/main/data_service/ai): unstructured signals · LLM, NLP, news, sentiment, and social monitoring · `data_service/ai`
- [Strategies](https://github.com/trademonk-llc/quantking/tree/main/data_service/strategies): strategy framework · Base strategy abstraction, registry, runner, optimizer, and built-ins · `data_service/strategies`
- [Backtest](https://github.com/trademonk-llc/quantking/tree/main/data_service/backtest): simulation · Historical simulation and performance analysis · `data_service/backtest`
- [Web/API](https://github.com/trademonk-llc/quantking/tree/main/data_service/web): serving layer · Web server and API endpoints for interactive use · `data_service/web`
- [Dashboard](https://github.com/trademonk-llc/quantking/tree/main/data_service/dashboard): presentation · Charts, widgets, and visualization components · `data_service/dashboard`
- [Charts](https://github.com/trademonk-llc/quantking/tree/main/data_service/visualization): visualization · Plotting helpers used by dashboards and demos · `data_service/visualization`
- [Vector store](https://github.com/trademonk-llc/quantking/tree/main/data_service/vector_db): semantic storage · Embedding-backed store supporting AI workflows · `data_service/vector_db`
- [Shared utils](https://github.com/trademonk-llc/quantking/tree/main/data_service/utils): cross-cutting support · Logging and custom exceptions used across modules · `data_service/utils`

### C++ execution core

Low-latency execution, order handling, and risk controls

- [Data loader](https://github.com/trademonk-llc/quantking/blob/main/backend/include/data_loader.hpp): cpp runtime · Loads market data inside the execution core · `backend/include/data_loader.hpp`
- [Strategy core](https://github.com/trademonk-llc/quantking/blob/main/backend/include/strategy.hpp): cpp runtime · Performance-sensitive strategy execution boundary · `backend/include/strategy.hpp`
- [Risk manager](https://github.com/trademonk-llc/quantking/blob/main/backend/include/risk_manager.hpp): cpp runtime · Order and exposure checks before execution · `backend/include/risk_manager.hpp`
- [Order executor](https://github.com/trademonk-llc/quantking/blob/main/backend/include/order_executor.hpp): cpp runtime · Submits and manages orders in the low-latency path · `backend/include/order_executor.hpp`
- [Backend main](https://github.com/trademonk-llc/quantking/blob/main/backend/src/main.cpp): cpp entrypoint · Standalone C++ engine entrypoint · `backend/src/main.cpp`

## Connections

- Main app → Market fetchers: orchestrates · Starts data acquisition workflows
- Main app → Live feed: orchestrates · Starts live market streams
- Main app → Web/API: launches · Runs the web/API application mode
- Main app → Dashboard: launches · Runs dashboard-focused mode
- Config → Market fetchers: configures · Provider credentials and API settings
- Config → Live feed: configures · Streaming endpoints and runtime settings
- Market fetchers → Data processor: feeds · Raw historical data into normalization
- Live feed → Data processor: feeds · Live data into the processing pipeline
- Data processor → Storage layer: persists · Normalized datasets and cacheable state
- Storage layer → Factors: serves · Historical and cached data for research
- Storage layer → ML features: serves · Feature datasets and model inputs
- Factors → Strategies: signals · Factor outputs inform strategy logic
- ML features → Strategies: features · Model features used by strategies
- AI/NLP → Vector store: stores · Embeddings and semantic artifacts
- AI/NLP → Strategies: augments · Sentiment and text-derived signals
- Strategies → Backtest: validated by · Strategy behavior is simulated and scored
- Backtest → Web/API: exposes · Results surfaced through web interfaces
- Dashboard → Charts: renders with · Charts and plotting primitives
- Web/API → Charts: uses · Web pages present charts and strategy views
- Shared utils → Market fetchers: supports · Logging and error handling
- Shared utils → Strategies: supports · Shared logging and exceptions
- Shared utils → Web/API: supports · Cross-cutting web diagnostics
- Backend main → Data loader: starts · Backend execution begins with data loading
- Backend main → Strategy core: starts · Runs the strategy execution core
- Strategy core → Risk manager: checks · Risk controls gate execution decisions
- Risk manager → Order executor: permits · Approved orders proceed to execution
- Data loader → Strategy core: provides data · Loaded market data drives strategy evaluation