trademonk-llc/quantking

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.