# henrylin99/quantitative_analysis architecture

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

- Interactive diagram: https://gitdiagram.com/henrylin99/quantitative_analysis
- Repository: https://github.com/henrylin99/quantitative_analysis

## Overview

This is a learning-oriented A-share quantitative research system: users explore market data, compute factors, score and model stocks, optimize portfolios, and validate strategies through backtests. The React SPA calls a Flask API; documented capabilities also include an AI workbench, data-job management, real-time analysis, and research reports. Market data is primarily stored in Parquet, with SQLite for application state. The graph combines documented product flows with source-visible calls; unsampled subsystems are represented only where README documentation supports them.

Main entry points: [`app/__init__.py`](https://github.com/henrylin99/quantitative_analysis/blob/master/app/__init__.py) (Flask API), [`frontend/src/App.tsx`](https://github.com/henrylin99/quantitative_analysis/blob/master/frontend/src/App.tsx) (Real-time pages), [`app/services/data_jobs/service.py`](https://github.com/henrylin99/quantitative_analysis/blob/master/app/services/data_jobs/service.py) (Data job service), [`app/services/data_reader.py`](https://github.com/henrylin99/quantitative_analysis/blob/master/app/services/data_reader.py) (Market data reader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["User interface"]
  node_spa["React application<br/>[App.tsx]"]
  node_api["Flask API<br/>[__init__.py]"]
  node_realtime_page["Real-time pages<br/>[App.tsx]"]
end

subgraph group_research["Quant research"]
  node_factor["Factor engine<br/>[factor_engine.py]"]
  node_factor_expr["Factor expressions"]
  node_ml["ML models<br/>[ml_models.py]"]
  node_scoring["Stock scoring<br/>[stock_scoring.py]"]
  node_portfolio["Portfolio optimizer"]
  node_backtest["Backtest engine<br/>[backtest_engine.py]"]
  node_backtest_task["Backtest task<br/>[backtest_tasks.py]"]
end

subgraph group_data["Data services"]
  node_reader["Market data reader<br/>[data_reader.py]"]
  node_market_store[("Market Parquet store")]
  node_jobs_api["Data job API<br/>[data_jobs_api.py]"]
  node_jobs_service["Data job service<br/>[service.py]"]
  node_jobs_task["Data job runner task<br/>[data_jobs_tasks.py]"]
  node_job_registry["Job registry<br/>[registry.py]"]
  node_job_store[("Job state store")]
end

subgraph group_realtime["Real-time analysis"]
  node_indicator["Indicator engine"]
  node_signals["Signal engine"]
  node_monitor_api["Monitoring API"]
  node_risk_api["Risk API<br/>[realtime_risk.py]"]
  node_report_api["Realtime report API<br/>[realtime_report.py]"]
end

subgraph group_assistant["AI and reports"]
  node_ai_page["AI workbench"]
  node_ai_api["AI assistant API"]
  node_ai_service["AI assistant service"]
  node_text2sql["Text-to-SQL engine<br/>[text2sql_engine.py]"]
  node_research_reports["Research reports"]
end

node_user(("Research user"))
node_llm(("LLM provider"))

node_user -->|"uses"| node_spa
node_spa -->|"calls API"| node_api
node_api -->|"routes factor work"| node_factor
node_factor -->|"reads market data"| node_reader
node_factor -->|"evaluates expressions"| node_factor_expr
node_api -->|"routes model work"| node_ml
node_api -->|"routes scoring"| node_scoring
node_api -->|"routes optimization"| node_portfolio
node_api -->|"queues backtest"| node_backtest_task
node_backtest_task -->|"runs engine"| node_backtest
node_backtest -->|"reads market data"| node_reader
node_backtest_task -->|"persists results"| node_market_store
node_reader -.->|"reads Parquet"| node_market_store
node_spa -->|"submits jobs"| node_jobs_api
node_jobs_api -.->|"manages jobs"| node_jobs_service
node_jobs_service -->|"resolves jobs"| node_job_registry
node_jobs_service -->|"stores state"| node_job_store
node_jobs_service -->|"dispatches task"| node_jobs_task
node_jobs_task -->|"loads job definition"| node_job_registry
node_jobs_task -->|"updates state"| node_job_store
node_user -->|"asks questions"| node_ai_page
node_ai_page -.->|"sends chat"| node_ai_api
node_ai_api -->|"handles assistant"| node_ai_service
node_ai_service -.->|"uses query tools"| node_text2sql
node_ai_service -.->|"requests completion"| node_llm
node_user -->|"views analysis"| node_realtime_page
node_realtime_page -.->|"requests indicators"| node_indicator
node_realtime_page -.->|"requests signals"| node_signals
node_realtime_page -.->|"requests monitoring"| node_monitor_api
node_realtime_page -.->|"requests risk analysis"| node_risk_api
node_realtime_page -.->|"requests reports"| node_report_api
node_signals -->|"uses indicators"| node_indicator
node_indicator -->|"reads market data"| node_reader
node_user -->|"requests reports"| node_research_reports
node_api -->|"routes report requests"| node_research_reports

click node_spa "https://github.com/henrylin99/quantitative_analysis/blob/master/frontend/src/App.tsx"
click node_api "https://github.com/henrylin99/quantitative_analysis/blob/master/app/__init__.py"
click node_factor "https://github.com/henrylin99/quantitative_analysis/blob/master/app/services/factor_engine.py"
click node_factor_expr "https://github.com/henrylin99/quantitative_analysis/blob/master/app/services/factor_expression_engine.py"
click node_ml "https://github.com/henrylin99/quantitative_analysis/blob/master/app/services/ml_models.py"
click node_scoring "https://github.com/henrylin99/quantitative_analysis/blob/master/app/services/stock_scoring.py"
click node_portfolio "https://github.com/henrylin99/quantitative_analysis/blob/master/app/services/portfolio_optimizer.py"
click node_backtest "https://github.com/henrylin99/quantitative_analysis/blob/master/app/services/backtest_engine.py"
click node_backtest_task "https://github.com/henrylin99/quantitative_analysis/blob/master/app/tasks/backtest_tasks.py"
click node_reader "https://github.com/henrylin99/quantitative_analysis/blob/master/app/services/data_reader.py"
click node_market_store "https://github.com/henrylin99/quantitative_analysis/blob/master/app/services/parquet_state_store.py"
click node_jobs_api "https://github.com/henrylin99/quantitative_analysis/blob/master/app/api/data_jobs_api.py"
click node_jobs_service "https://github.com/henrylin99/quantitative_analysis/blob/master/app/services/data_jobs/service.py"
click node_jobs_task "https://github.com/henrylin99/quantitative_analysis/blob/master/app/tasks/data_jobs_tasks.py"
click node_job_registry "https://github.com/henrylin99/quantitative_analysis/blob/master/app/services/data_jobs/registry.py"
click node_job_store "https://github.com/henrylin99/quantitative_analysis/blob/master/app/services/data_jobs/parquet_state_store.py"
click node_ai_page "https://github.com/henrylin99/quantitative_analysis/blob/master/frontend/src/pages/AiWorkbenchPage.tsx"
click node_ai_api "https://github.com/henrylin99/quantitative_analysis/blob/master/app/api/ai_assistant_api.py"
click node_ai_service "https://github.com/henrylin99/quantitative_analysis/blob/master/app/services/ai/assistant_service.py"
click node_text2sql "https://github.com/henrylin99/quantitative_analysis/blob/master/app/services/text2sql_engine.py"
click node_realtime_page "https://github.com/henrylin99/quantitative_analysis/blob/master/frontend/src/App.tsx"
click node_indicator "https://github.com/henrylin99/quantitative_analysis/blob/master/app/services/realtime_indicator_engine.py"
click node_signals "https://github.com/henrylin99/quantitative_analysis/blob/master/app/services/realtime_trading_signal_engine.py"
click node_monitor_api "https://github.com/henrylin99/quantitative_analysis/blob/master/app/api/realtime_monitor.py"
click node_risk_api "https://github.com/henrylin99/quantitative_analysis/blob/master/app/api/realtime_risk.py"
click node_report_api "https://github.com/henrylin99/quantitative_analysis/blob/master/app/api/realtime_report.py"
click node_research_reports "https://github.com/henrylin99/quantitative_analysis/blob/master/app/services/research_report_service.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_spa,node_api,node_realtime_page,node_user toneBlue
class node_factor,node_factor_expr,node_ml,node_scoring,node_portfolio,node_backtest,node_backtest_task toneAmber
class node_reader,node_market_store,node_jobs_api,node_jobs_service,node_jobs_task,node_job_registry,node_job_store toneMint
class node_indicator,node_signals,node_monitor_api,node_risk_api,node_report_api toneRose
class node_ai_page,node_ai_api,node_ai_service,node_text2sql,node_research_reports,node_llm toneIndigo
```

## Components

### User interface

- [React application](https://github.com/henrylin99/quantitative_analysis/blob/master/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Flask API](https://github.com/henrylin99/quantitative_analysis/blob/master/app/__init__.py): `app/__init__.py`
- [Real-time pages](https://github.com/henrylin99/quantitative_analysis/blob/master/frontend/src/App.tsx): `frontend/src/App.tsx`

### Quant research

- [Factor engine](https://github.com/henrylin99/quantitative_analysis/blob/master/app/services/factor_engine.py): `app/services/factor_engine.py`
- [Factor expressions](https://github.com/henrylin99/quantitative_analysis/blob/master/app/services/factor_expression_engine.py): `app/services/factor_expression_engine.py`
- [ML models](https://github.com/henrylin99/quantitative_analysis/blob/master/app/services/ml_models.py): `app/services/ml_models.py`
- [Stock scoring](https://github.com/henrylin99/quantitative_analysis/blob/master/app/services/stock_scoring.py): `app/services/stock_scoring.py`
- [Portfolio optimizer](https://github.com/henrylin99/quantitative_analysis/blob/master/app/services/portfolio_optimizer.py): `app/services/portfolio_optimizer.py`
- [Backtest engine](https://github.com/henrylin99/quantitative_analysis/blob/master/app/services/backtest_engine.py): `app/services/backtest_engine.py`
- [Backtest task](https://github.com/henrylin99/quantitative_analysis/blob/master/app/tasks/backtest_tasks.py): `app/tasks/backtest_tasks.py`

### Data services

- [Market data reader](https://github.com/henrylin99/quantitative_analysis/blob/master/app/services/data_reader.py): `app/services/data_reader.py`
- [Market Parquet store](https://github.com/henrylin99/quantitative_analysis/blob/master/app/services/parquet_state_store.py): `app/services/parquet_state_store.py`
- [Data job API](https://github.com/henrylin99/quantitative_analysis/blob/master/app/api/data_jobs_api.py): `app/api/data_jobs_api.py`
- [Data job service](https://github.com/henrylin99/quantitative_analysis/blob/master/app/services/data_jobs/service.py): `app/services/data_jobs/service.py`
- [Data job runner task](https://github.com/henrylin99/quantitative_analysis/blob/master/app/tasks/data_jobs_tasks.py): `app/tasks/data_jobs_tasks.py`
- [Job registry](https://github.com/henrylin99/quantitative_analysis/blob/master/app/services/data_jobs/registry.py): `app/services/data_jobs/registry.py`
- [Job state store](https://github.com/henrylin99/quantitative_analysis/blob/master/app/services/data_jobs/parquet_state_store.py): `app/services/data_jobs/parquet_state_store.py`

### Real-time analysis

- [Indicator engine](https://github.com/henrylin99/quantitative_analysis/blob/master/app/services/realtime_indicator_engine.py): `app/services/realtime_indicator_engine.py`
- [Signal engine](https://github.com/henrylin99/quantitative_analysis/blob/master/app/services/realtime_trading_signal_engine.py): `app/services/realtime_trading_signal_engine.py`
- [Monitoring API](https://github.com/henrylin99/quantitative_analysis/blob/master/app/api/realtime_monitor.py): `app/api/realtime_monitor.py`
- [Risk API](https://github.com/henrylin99/quantitative_analysis/blob/master/app/api/realtime_risk.py): `app/api/realtime_risk.py`
- [Realtime report API](https://github.com/henrylin99/quantitative_analysis/blob/master/app/api/realtime_report.py): `app/api/realtime_report.py`

### AI and reports

- [AI workbench](https://github.com/henrylin99/quantitative_analysis/blob/master/frontend/src/pages/AiWorkbenchPage.tsx): `frontend/src/pages/AiWorkbenchPage.tsx`
- [AI assistant API](https://github.com/henrylin99/quantitative_analysis/blob/master/app/api/ai_assistant_api.py): `app/api/ai_assistant_api.py`
- [AI assistant service](https://github.com/henrylin99/quantitative_analysis/blob/master/app/services/ai/assistant_service.py): `app/services/ai/assistant_service.py`
- [Text-to-SQL engine](https://github.com/henrylin99/quantitative_analysis/blob/master/app/services/text2sql_engine.py): `app/services/text2sql_engine.py`
- [Research reports](https://github.com/henrylin99/quantitative_analysis/blob/master/app/services/research_report_service.py): `app/services/research_report_service.py`

### Other components

- **Research user**
- **LLM provider**

## Connections

- Research user → React application: uses (evidence: `README.md`)
- React application → Flask API: calls API (evidence: `README.md`)
- Flask API → Factor engine: routes factor work
- Factor engine → Market data reader: reads market data (evidence: `app/services/factor_engine.py`)
- Factor engine → Factor expressions: evaluates expressions (evidence: `app/services/factor_engine.py`)
- Flask API → ML models: routes model work
- Flask API → Stock scoring: routes scoring
- Flask API → Portfolio optimizer: routes optimization
- Flask API → Backtest task: queues backtest
- Backtest task → Backtest engine: runs engine (evidence: `app/tasks/backtest_tasks.py`)
- Backtest engine → Market data reader: reads market data (evidence: `app/services/backtest_engine.py`)
- Backtest task → Market Parquet store: persists results (evidence: `app/tasks/backtest_tasks.py`)
- Market data reader → Market Parquet store: reads Parquet
- React application → Data job API: submits jobs (evidence: `README.md`)
- Data job API → Data job service: manages jobs
- Data job service → Job registry: resolves jobs (evidence: `app/services/data_jobs/service.py`)
- Data job service → Job state store: stores state (evidence: `app/services/data_jobs/service.py`)
- Data job service → Data job runner task: dispatches task (evidence: `app/services/data_jobs/service.py`)
- Data job runner task → Job registry: loads job definition (evidence: `app/tasks/data_jobs_tasks.py`)
- Data job runner task → Job state store: updates state (evidence: `app/tasks/data_jobs_tasks.py`)
- Research user → AI workbench: asks questions (evidence: `README.md`)
- AI workbench → AI assistant API: sends chat
- AI assistant API → AI assistant service: handles assistant (evidence: `app/api/ai_assistant_api.py`)
- AI assistant service → Text-to-SQL engine: uses query tools
- AI assistant service → LLM provider: requests completion
- Research user → Real-time pages: views analysis (evidence: `README.md`)
- Real-time pages → Indicator engine: requests indicators
- Real-time pages → Signal engine: requests signals
- Real-time pages → Monitoring API: requests monitoring
- Real-time pages → Risk API: requests risk analysis
- Real-time pages → Realtime report API: requests reports
- Signal engine → Indicator engine: uses indicators (evidence: `app/services/realtime_trading_signal_engine.py`)
- Indicator engine → Market data reader: reads market data (evidence: `app/services/realtime_indicator_engine.py`)
- Research user → Research reports: requests reports (evidence: `README.md`)
- Flask API → Research reports: routes report requests