# sagan-research/sagan-trade architecture

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

- Interactive diagram: https://gitdiagram.com/sagan-research/sagan-trade
- Repository: https://github.com/sagan-research/sagan-trade

## Overview

Sagan Trade is a quantitative research and trading library: users derive transparent alpha signals from market data, manage exposure with risk and regime filters, and evaluate strategies through fee-aware backtesting. The repository also contains separate WQB alpha-mining and NIFTY research workflows, plus a Streamlit trading dashboard. README claims identify additional model, microstructure, and portfolio capabilities, but their internal wiring is not established by the sampled source; those are shown as distinct components without inferred call chains.

Main entry points: [`WQB_Submission/core/orchestrator.py`](https://github.com/sagan-research/sagan-trade/blob/main/WQB_Submission/core/orchestrator.py) (Batch Orchestrator), [`sagan_trade/backtest_engine.py`](https://github.com/sagan-research/sagan-trade/blob/main/sagan_trade/backtest_engine.py) (Backtest Engine), [`sagan_trade/symbolic_regressor.py`](https://github.com/sagan-research/sagan-trade/blob/main/sagan_trade/symbolic_regressor.py) (Symbolic Regressor), [`WQB_Submission/core/api.py`](https://github.com/sagan-research/sagan-trade/blob/main/WQB_Submission/core/api.py) (WQ Brain API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_signals["Signal Research"]
  node_symbolic["Symbolic Regressor"]
  node_features["Feature Engineering"]
  node_microstructure["Market Microstructure"]
  node_learnedmodels["Forecast Models<br/>[tft_model.py]"]
  node_pinn["PINN Models<br/>[pinn_models.py]"]
end

subgraph group_portfolio["Risk And Evaluation"]
  node_risk["Asymmetric Risk"]
  node_regime["Volatility Regime"]
  node_backtest["Backtest Engine<br/>[backtest_engine.py]"]
  node_advancedbacktest["Advanced Backtesting"]
  node_portfolioopt["Portfolio Optimization"]
  node_firestore[("Firestore Store")]
  node_dashboard["Trading Dashboard<br/>[app.py]"]
end

subgraph group_research["Research Workflows"]
  node_quantrunner["Research Runner<br/>[run_pipeline.py]"]
  node_quantengine["Quant Research<br/>[research_engine.py]"]
end

subgraph group_wqb["WQB Alpha Mining"]
  node_wqbentry["WQB CLI<br/>[main.py]"]
  node_orchestrator["Batch Orchestrator<br/>[orchestrator.py]"]
  node_generator["Expression Generator<br/>[generator.py]"]
  node_wqbapi["WQ Brain API<br/>[api.py]"]
  node_evaluator["Alpha Evaluator<br/>[evaluator.py]"]
end

node_user(("Quant User"))
node_marketdata(("Market Data"))
node_yfinance(("Market Data Provider"))
node_report["Research Report"]
node_wqservice(("WQ Brain Service"))

node_user -->|"trains and predicts"| node_symbolic
node_marketdata -->|"provides prices"| node_symbolic
node_symbolic -.->|"synthesizes indicators"| node_features
node_user -->|"requests sizing"| node_risk
node_user -->|"requests signals"| node_regime
node_user -->|"runs strategy"| node_backtest
node_risk -->|"supplies risk model"| node_backtest
node_regime -->|"supplies filter"| node_backtest
node_symbolic -->|"supplies alpha"| node_backtest
node_backtest -->|"returns metrics"| node_user
node_user -->|"evaluates strategy"| node_advancedbacktest
node_user -->|"optimizes holdings"| node_portfolioopt
node_user -->|"requests analysis"| node_microstructure
node_user -->|"uses forecasts"| node_learnedmodels
node_user -->|"uses forecasts"| node_pinn
node_user -->|"views and configures"| node_dashboard
node_user -->|"starts research"| node_quantrunner
node_quantrunner -->|"runs research"| node_quantengine
node_quantengine -->|"downloads prices"| node_yfinance
node_quantengine -->|"returns metrics"| node_report
node_quantrunner -->|"writes JSON"| node_report
node_user -->|"starts mining"| node_wqbentry
node_wqbentry -->|"starts loop or batch"| node_orchestrator
node_orchestrator -->|"generates expressions"| node_generator
node_orchestrator -->|"dispatches simulations"| node_wqbapi
node_wqbapi -->|"simulates and submits"| node_wqservice
node_wqservice -->|"returns results"| node_wqbapi
node_orchestrator -->|"ranks results"| node_evaluator
node_orchestrator -->|"submits best alpha"| node_wqbapi

click node_symbolic "https://github.com/sagan-research/sagan-trade/blob/main/sagan_trade/symbolic_regressor.py"
click node_features "https://github.com/sagan-research/sagan-trade/blob/main/sagan_trade/feature_engineering.py"
click node_microstructure "https://github.com/sagan-research/sagan-trade/blob/main/sagan_trade/market_microstructure.py"
click node_learnedmodels "https://github.com/sagan-research/sagan-trade/blob/main/sagan_trade/tft_model.py"
click node_pinn "https://github.com/sagan-research/sagan-trade/blob/main/sagan_trade/pinn_models.py"
click node_risk "https://github.com/sagan-research/sagan-trade/blob/main/sagan_trade/asymmetric_risk_engine.py"
click node_regime "https://github.com/sagan-research/sagan-trade/blob/main/sagan_trade/volatility_regime_filter.py"
click node_backtest "https://github.com/sagan-research/sagan-trade/blob/main/sagan_trade/backtest_engine.py"
click node_advancedbacktest "https://github.com/sagan-research/sagan-trade/blob/main/sagan_trade/backtesting_advanced.py"
click node_portfolioopt "https://github.com/sagan-research/sagan-trade/blob/main/sagan_trade/portfolio_optimization.py"
click node_firestore "https://github.com/sagan-research/sagan-trade/blob/main/sagan_trade/firestore_client.py"
click node_dashboard "https://github.com/sagan-research/sagan-trade/blob/main/dashboard/app.py"
click node_quantrunner "https://github.com/sagan-research/sagan-trade/blob/main/nifty_quant_pipeline/run_pipeline.py"
click node_quantengine "https://github.com/sagan-research/sagan-trade/blob/main/nifty_quant_pipeline/research_engine.py"
click node_wqbentry "https://github.com/sagan-research/sagan-trade/blob/main/WQB_Submission/main.py"
click node_orchestrator "https://github.com/sagan-research/sagan-trade/blob/main/WQB_Submission/core/orchestrator.py"
click node_generator "https://github.com/sagan-research/sagan-trade/blob/main/WQB_Submission/core/generator.py"
click node_wqbapi "https://github.com/sagan-research/sagan-trade/blob/main/WQB_Submission/core/api.py"
click node_evaluator "https://github.com/sagan-research/sagan-trade/blob/main/WQB_Submission/core/evaluator.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_symbolic,node_features,node_microstructure,node_learnedmodels,node_pinn,node_user toneBlue
class node_risk,node_regime,node_backtest,node_advancedbacktest,node_portfolioopt,node_firestore,node_dashboard toneAmber
class node_quantrunner,node_quantengine toneMint
class node_wqbentry,node_orchestrator,node_generator,node_wqbapi,node_evaluator toneRose
class node_marketdata,node_yfinance,node_report,node_wqservice toneIndigo
```

## Components

### Signal Research

- [Symbolic Regressor](https://github.com/sagan-research/sagan-trade/blob/main/sagan_trade/symbolic_regressor.py): `sagan_trade/symbolic_regressor.py`
- [Feature Engineering](https://github.com/sagan-research/sagan-trade/blob/main/sagan_trade/feature_engineering.py): `sagan_trade/feature_engineering.py`
- [Market Microstructure](https://github.com/sagan-research/sagan-trade/blob/main/sagan_trade/market_microstructure.py): `sagan_trade/market_microstructure.py`
- [Forecast Models](https://github.com/sagan-research/sagan-trade/blob/main/sagan_trade/tft_model.py): `sagan_trade/tft_model.py`
- [PINN Models](https://github.com/sagan-research/sagan-trade/blob/main/sagan_trade/pinn_models.py): `sagan_trade/pinn_models.py`

### Risk And Evaluation

- [Asymmetric Risk](https://github.com/sagan-research/sagan-trade/blob/main/sagan_trade/asymmetric_risk_engine.py): `sagan_trade/asymmetric_risk_engine.py`
- [Volatility Regime](https://github.com/sagan-research/sagan-trade/blob/main/sagan_trade/volatility_regime_filter.py): `sagan_trade/volatility_regime_filter.py`
- [Backtest Engine](https://github.com/sagan-research/sagan-trade/blob/main/sagan_trade/backtest_engine.py): `sagan_trade/backtest_engine.py`
- [Advanced Backtesting](https://github.com/sagan-research/sagan-trade/blob/main/sagan_trade/backtesting_advanced.py): `sagan_trade/backtesting_advanced.py`
- [Portfolio Optimization](https://github.com/sagan-research/sagan-trade/blob/main/sagan_trade/portfolio_optimization.py): `sagan_trade/portfolio_optimization.py`
- [Firestore Store](https://github.com/sagan-research/sagan-trade/blob/main/sagan_trade/firestore_client.py): `sagan_trade/firestore_client.py`
- [Trading Dashboard](https://github.com/sagan-research/sagan-trade/blob/main/dashboard/app.py): `dashboard/app.py`

### Research Workflows

- [Research Runner](https://github.com/sagan-research/sagan-trade/blob/main/nifty_quant_pipeline/run_pipeline.py): `nifty_quant_pipeline/run_pipeline.py`
- [Quant Research](https://github.com/sagan-research/sagan-trade/blob/main/nifty_quant_pipeline/research_engine.py): `nifty_quant_pipeline/research_engine.py`

### WQB Alpha Mining

- [WQB CLI](https://github.com/sagan-research/sagan-trade/blob/main/WQB_Submission/main.py): `WQB_Submission/main.py`
- [Batch Orchestrator](https://github.com/sagan-research/sagan-trade/blob/main/WQB_Submission/core/orchestrator.py): `WQB_Submission/core/orchestrator.py`
- [Expression Generator](https://github.com/sagan-research/sagan-trade/blob/main/WQB_Submission/core/generator.py): `WQB_Submission/core/generator.py`
- [WQ Brain API](https://github.com/sagan-research/sagan-trade/blob/main/WQB_Submission/core/api.py): `WQB_Submission/core/api.py`
- [Alpha Evaluator](https://github.com/sagan-research/sagan-trade/blob/main/WQB_Submission/core/evaluator.py): `WQB_Submission/core/evaluator.py`

### Other components

- **Quant User**
- **Market Data**
- **Market Data Provider**
- **Research Report**
- **WQ Brain Service**

## Connections

- Quant User → Symbolic Regressor: trains and predicts
- Market Data → Symbolic Regressor: provides prices
- Symbolic Regressor → Feature Engineering: synthesizes indicators
- Quant User → Asymmetric Risk: requests sizing
- Quant User → Volatility Regime: requests signals
- Quant User → Backtest Engine: runs strategy
- Asymmetric Risk → Backtest Engine: supplies risk model
- Volatility Regime → Backtest Engine: supplies filter
- Symbolic Regressor → Backtest Engine: supplies alpha
- Backtest Engine → Quant User: returns metrics
- Quant User → Advanced Backtesting: evaluates strategy
- Quant User → Portfolio Optimization: optimizes holdings
- Quant User → Market Microstructure: requests analysis
- Quant User → Forecast Models: uses forecasts
- Quant User → PINN Models: uses forecasts
- Quant User → Trading Dashboard: views and configures
- Quant User → Research Runner: starts research
- Research Runner → Quant Research: runs research
- Quant Research → Market Data Provider: downloads prices
- Quant Research → Research Report: returns metrics
- Research Runner → Research Report: writes JSON
- Quant User → WQB CLI: starts mining
- WQB CLI → Batch Orchestrator: starts loop or batch
- Batch Orchestrator → Expression Generator: generates expressions
- Batch Orchestrator → WQ Brain API: dispatches simulations
- WQ Brain API → WQ Brain Service: simulates and submits
- WQ Brain Service → WQ Brain API: returns results
- Batch Orchestrator → Alpha Evaluator: ranks results
- Batch Orchestrator → WQ Brain API: submits best alpha