# caramelizeed/xgboost_quant architecture

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

- Interactive diagram: https://gitdiagram.com/caramelizeed/xgboost_quant
- Repository: https://github.com/caramelizeed/xgboost_quant

## Overview

XGBoost Quant is a full-stack quantitative trading system: users select a market and run a simulation that fetches and prepares price data, builds features, trains and evaluates a model, converts probabilities into trades, and returns backtest results for dashboard visualization. The API also exposes model explanations and parameter-sensitivity heatmaps. The README documents the end-to-end pipeline; sampled source confirms data-provider/cache behavior, walk-forward training, backtesting, API dispatch, and frontend requests. Simulation orchestration and several feature/model modules were not sampled, so those documented links are shown at subsystem level.

Main entry points: [`src/api/simulation.py`](https://github.com/caramelizeed/xgboost_quant/blob/main/src/api/simulation.py) (Pipeline orchestration), [`frontend/src/hooks/useSimulation.js`](https://github.com/caramelizeed/xgboost_quant/blob/main/frontend/src/hooks/useSimulation.js) (Simulation hook), [`frontend/src/services/api.js`](https://github.com/caramelizeed/xgboost_quant/blob/main/frontend/src/services/api.js) (API client), [`src/api/main.py`](https://github.com/caramelizeed/xgboost_quant/blob/main/src/api/main.py) (API endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Trading dashboard"]
  node_app["App navigation<br/>[App.jsx]"]
  node_asset_search["Asset search<br/>[AssetSearch.jsx]"]
  node_terminal["Simulation terminal<br/>[Terminal.jsx]"]
  node_sim_hook["Simulation hook<br/>[useSimulation.js]"]
  node_api_client["API client<br/>[api.js]"]
  node_dashboard["Result dashboard<br/>[Dashboard.jsx]"]
  node_charts["Result visualizations<br/>[EquityCurve.jsx]"]
  node_heatmap_ui["Sensitivity heatmap<br/>[HeatmapChart.jsx]"]
end

subgraph group_api["API orchestration"]
  node_api_routes["API endpoints<br/>[main.py]"]
  node_schemas["Request and response schemas<br/>[schemas.py]"]
  node_orchestrator["Pipeline orchestration<br/>[simulation.py]"]
end

subgraph group_data["Market data"]
  node_ingestion["OHLCV ingestion<br/>[ingestion.py]"]
  node_crypto_ingestion["Crypto OHLCV<br/>[ccxt_ingestion.py]"]
  node_cache[("Parquet cache<br/>[ingestion.py]")]
  node_preparation["Cleaning and labeling<br/>[cleaning.py]"]
end

subgraph group_ml["Model pipeline"]
  node_feature_engineering["Feature engineering<br/>[pipeline.py]"]
  node_training["Walk-forward training<br/>[train.py]"]
  node_prediction["Signal probabilities<br/>[predict.py]"]
  node_explanation["SHAP explanation<br/>[explain.py]"]
end

subgraph group_results["Backtest analysis"]
  node_backtest["Strategy backtest<br/>[engine.py]"]
  node_metrics["Performance metrics<br/>[metrics.py]"]
  node_heatmap["Parameter sensitivity<br/>[simulation.py]"]
end

node_user(("Researcher"))
node_yfinance["yfinance"]
node_ccxt["CCXT exchanges"]
node_cli["CLI runner<br/>[main.py]"]

node_user -->|"opens"| node_app
node_app -->|"selects asset"| node_asset_search
node_app -->|"opens"| node_terminal
node_terminal -->|"runs simulation"| node_sim_hook
node_sim_hook -->|"requests results"| node_api_client
node_sim_hook -.->|"requests explanation"| node_api_client
node_api_client -->|"HTTP requests"| node_api_routes
node_api_routes -->|"validates payloads"| node_schemas
node_api_routes -->|"dispatches pipeline"| node_orchestrator
node_orchestrator -->|"fetches prices"| node_ingestion
node_ingestion -->|"reads and writes"| node_cache
node_ingestion -->|"fetches prices"| node_yfinance
node_ingestion -->|"fetches crypto"| node_crypto_ingestion
node_crypto_ingestion -->|"fetches OHLCV"| node_ccxt
node_orchestrator -->|"prepares data"| node_preparation
node_orchestrator -->|"builds features"| node_feature_engineering
node_orchestrator -->|"trains model"| node_training
node_training -->|"transforms features"| node_feature_engineering
node_orchestrator -->|"generates probabilities"| node_prediction
node_orchestrator -->|"runs strategy"| node_backtest
node_backtest -->|"calculates performance"| node_metrics
node_orchestrator -.->|"explains model"| node_explanation
node_orchestrator -.->|"generates sensitivity"| node_heatmap
node_api_routes -->|"returns results"| node_api_client
node_api_client -->|"returns payload"| node_sim_hook
node_sim_hook -->|"supplies results"| node_dashboard
node_dashboard -->|"renders metrics"| node_charts
node_dashboard -.->|"renders sensitivity"| node_heatmap_ui
node_cli -->|"runs pipeline"| node_orchestrator

click node_app "https://github.com/caramelizeed/xgboost_quant/blob/main/frontend/src/App.jsx"
click node_asset_search "https://github.com/caramelizeed/xgboost_quant/blob/main/frontend/src/pages/AssetSearch.jsx"
click node_terminal "https://github.com/caramelizeed/xgboost_quant/blob/main/frontend/src/pages/Terminal.jsx"
click node_sim_hook "https://github.com/caramelizeed/xgboost_quant/blob/main/frontend/src/hooks/useSimulation.js"
click node_api_client "https://github.com/caramelizeed/xgboost_quant/blob/main/frontend/src/services/api.js"
click node_dashboard "https://github.com/caramelizeed/xgboost_quant/blob/main/frontend/src/pages/Dashboard.jsx"
click node_charts "https://github.com/caramelizeed/xgboost_quant/blob/main/frontend/src/components/EquityCurve.jsx"
click node_heatmap_ui "https://github.com/caramelizeed/xgboost_quant/blob/main/frontend/src/components/HeatmapChart.jsx"
click node_api_routes "https://github.com/caramelizeed/xgboost_quant/blob/main/src/api/main.py"
click node_schemas "https://github.com/caramelizeed/xgboost_quant/blob/main/src/api/schemas.py"
click node_orchestrator "https://github.com/caramelizeed/xgboost_quant/blob/main/src/api/simulation.py"
click node_ingestion "https://github.com/caramelizeed/xgboost_quant/blob/main/src/data/ingestion.py"
click node_crypto_ingestion "https://github.com/caramelizeed/xgboost_quant/blob/main/src/data/ccxt_ingestion.py"
click node_cache "https://github.com/caramelizeed/xgboost_quant/blob/main/src/data/ingestion.py"
click node_preparation "https://github.com/caramelizeed/xgboost_quant/blob/main/src/data/cleaning.py"
click node_feature_engineering "https://github.com/caramelizeed/xgboost_quant/blob/main/src/features/pipeline.py"
click node_training "https://github.com/caramelizeed/xgboost_quant/blob/main/src/models/train.py"
click node_prediction "https://github.com/caramelizeed/xgboost_quant/blob/main/src/models/predict.py"
click node_explanation "https://github.com/caramelizeed/xgboost_quant/blob/main/src/models/explain.py"
click node_backtest "https://github.com/caramelizeed/xgboost_quant/blob/main/src/backtest/engine.py"
click node_metrics "https://github.com/caramelizeed/xgboost_quant/blob/main/src/backtest/metrics.py"
click node_heatmap "https://github.com/caramelizeed/xgboost_quant/blob/main/src/api/simulation.py"
click node_cli "https://github.com/caramelizeed/xgboost_quant/blob/main/main.py"

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_app,node_asset_search,node_terminal,node_sim_hook,node_api_client,node_dashboard,node_charts,node_heatmap_ui toneBlue
class node_api_routes,node_schemas,node_orchestrator toneAmber
class node_ingestion,node_crypto_ingestion,node_cache,node_preparation toneMint
class node_feature_engineering,node_training,node_prediction,node_explanation toneRose
class node_backtest,node_metrics,node_heatmap,node_user,node_yfinance,node_ccxt toneIndigo
class node_cli toneTeal
```

## Components

### Trading dashboard

- [App navigation](https://github.com/caramelizeed/xgboost_quant/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Asset search](https://github.com/caramelizeed/xgboost_quant/blob/main/frontend/src/pages/AssetSearch.jsx): `frontend/src/pages/AssetSearch.jsx`
- [Simulation terminal](https://github.com/caramelizeed/xgboost_quant/blob/main/frontend/src/pages/Terminal.jsx): `frontend/src/pages/Terminal.jsx`
- [Simulation hook](https://github.com/caramelizeed/xgboost_quant/blob/main/frontend/src/hooks/useSimulation.js): `frontend/src/hooks/useSimulation.js`
- [API client](https://github.com/caramelizeed/xgboost_quant/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`
- [Result dashboard](https://github.com/caramelizeed/xgboost_quant/blob/main/frontend/src/pages/Dashboard.jsx): `frontend/src/pages/Dashboard.jsx`
- [Result visualizations](https://github.com/caramelizeed/xgboost_quant/blob/main/frontend/src/components/EquityCurve.jsx): `frontend/src/components/EquityCurve.jsx`
- [Sensitivity heatmap](https://github.com/caramelizeed/xgboost_quant/blob/main/frontend/src/components/HeatmapChart.jsx): `frontend/src/components/HeatmapChart.jsx`

### API orchestration

- [API endpoints](https://github.com/caramelizeed/xgboost_quant/blob/main/src/api/main.py): `src/api/main.py`
- [Request and response schemas](https://github.com/caramelizeed/xgboost_quant/blob/main/src/api/schemas.py): `src/api/schemas.py`
- [Pipeline orchestration](https://github.com/caramelizeed/xgboost_quant/blob/main/src/api/simulation.py): `src/api/simulation.py`

### Market data

- [OHLCV ingestion](https://github.com/caramelizeed/xgboost_quant/blob/main/src/data/ingestion.py): `src/data/ingestion.py`
- [Crypto OHLCV](https://github.com/caramelizeed/xgboost_quant/blob/main/src/data/ccxt_ingestion.py): `src/data/ccxt_ingestion.py`
- [Parquet cache](https://github.com/caramelizeed/xgboost_quant/blob/main/src/data/ingestion.py): `src/data/ingestion.py`
- [Cleaning and labeling](https://github.com/caramelizeed/xgboost_quant/blob/main/src/data/cleaning.py): `src/data/cleaning.py`

### Model pipeline

- [Feature engineering](https://github.com/caramelizeed/xgboost_quant/blob/main/src/features/pipeline.py): `src/features/pipeline.py`
- [Walk-forward training](https://github.com/caramelizeed/xgboost_quant/blob/main/src/models/train.py): `src/models/train.py`
- [Signal probabilities](https://github.com/caramelizeed/xgboost_quant/blob/main/src/models/predict.py): `src/models/predict.py`
- [SHAP explanation](https://github.com/caramelizeed/xgboost_quant/blob/main/src/models/explain.py): `src/models/explain.py`

### Backtest analysis

- [Strategy backtest](https://github.com/caramelizeed/xgboost_quant/blob/main/src/backtest/engine.py): `src/backtest/engine.py`
- [Performance metrics](https://github.com/caramelizeed/xgboost_quant/blob/main/src/backtest/metrics.py): `src/backtest/metrics.py`
- [Parameter sensitivity](https://github.com/caramelizeed/xgboost_quant/blob/main/src/api/simulation.py): `src/api/simulation.py`

### Other components

- **Researcher**
- **yfinance**
- **CCXT exchanges**
- [CLI runner](https://github.com/caramelizeed/xgboost_quant/blob/main/main.py): `main.py`

## Connections

- Researcher → App navigation: opens
- App navigation → Asset search: selects asset
- App navigation → Simulation terminal: opens
- Simulation terminal → Simulation hook: runs simulation
- Simulation hook → API client: requests results
- Simulation hook → API client: requests explanation
- API client → API endpoints: HTTP requests
- API endpoints → Request and response schemas: validates payloads
- API endpoints → Pipeline orchestration: dispatches pipeline
- Pipeline orchestration → OHLCV ingestion: fetches prices
- OHLCV ingestion → Parquet cache: reads and writes
- OHLCV ingestion → yfinance: fetches prices
- OHLCV ingestion → Crypto OHLCV: fetches crypto
- Crypto OHLCV → CCXT exchanges: fetches OHLCV
- Pipeline orchestration → Cleaning and labeling: prepares data
- Pipeline orchestration → Feature engineering: builds features
- Pipeline orchestration → Walk-forward training: trains model
- Walk-forward training → Feature engineering: transforms features
- Pipeline orchestration → Signal probabilities: generates probabilities
- Pipeline orchestration → Strategy backtest: runs strategy
- Strategy backtest → Performance metrics: calculates performance
- Pipeline orchestration → SHAP explanation: explains model
- Pipeline orchestration → Parameter sensitivity: generates sensitivity
- API endpoints → API client: returns results
- API client → Simulation hook: returns payload
- Simulation hook → Result dashboard: supplies results
- Result dashboard → Result visualizations: renders metrics
- Result dashboard → Sensitivity heatmap: renders sensitivity
- CLI runner → Pipeline orchestration: runs pipeline