# aydanli/quant_investment architecture

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

- Interactive diagram: https://gitdiagram.com/aydanli/quant_investment
- Repository: https://github.com/aydanli/quant_investment

## Overview

Quant System v3 is a personal ETF momentum-rotation research platform. Its main workflow loads trusted market data, computes features and allocations, applies risk controls, replays T+1 execution in a backtest, and reports results. Separate capabilities cover governed research admission, persistent local paper replay, and a read-only Robinhood mirror. README documents these broader boundaries; sampled source confirms the backtest wiring and selected persistence and quality behavior, but not every subsystem connection.

Main entry points: [`main.py`](https://github.com/aydanli/quant_investment/blob/master/main.py) (Backtest Entry), [`data/trusted_loader.py`](https://github.com/aydanli/quant_investment/blob/master/data/trusted_loader.py) (Trusted Loader), [`services/paper_cycle.py`](https://github.com/aydanli/quant_investment/blob/master/services/paper_cycle.py) (Local Paper Cycle), [`execution/oms.py`](https://github.com/aydanli/quant_investment/blob/master/execution/oms.py) (Order Management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_market["Market Data"]
  node_trusted["Trusted Loader<br/>[trusted_loader.py]"]
  node_provider["Data Providers<br/>[providers.py]"]
  node_quality["Quality Checks<br/>[quality.py]"]
  node_features["Feature Engineering<br/>[features.py]"]
end

subgraph group_portfolio["Portfolio Engine"]
  node_main["Backtest Entry<br/>[main.py]"]
  node_strategy["Momentum Strategy"]
  node_regime["Market Regime<br/>[regime.py]"]
  node_risk["Risk Engine<br/>[engine.py]"]
  node_backtest["T+1 Backtest<br/>[engine.py]"]
  node_ledger["Position Ledger<br/>[ledger.py]"]
end

subgraph group_research["Research Governance"]
  node_admission["Nested Admission"]
  node_admission_service["Admission Persistence"]
  node_protocol["Research Protocol<br/>[protocol.py]"]
  node_governance[("Governance Store<br/>[governance.py]")]
end

subgraph group_operations["Paper Operations"]
  node_paper["Local Paper Cycle<br/>[paper_cycle.py]"]
  node_signals["Signal Service<br/>[signal_service.py]"]
  node_oms["Order Management<br/>[oms.py]"]
  node_broker["Broker Boundary<br/>[broker.py]"]
  node_execution_store[("Execution Store<br/>[execution.py]")]
  node_database[("SQLite Store<br/>[db.py]")]
end

subgraph group_insight["Reporting Views"]
  node_reporter["Backtest Reports<br/>[reporter.py]"]
  node_mirror["Robinhood Mirror"]
  node_mirror_store[("Mirror Snapshots")]
  node_dashboard["Research Dashboard"]
end

node_researcher(("Researcher"))
node_market_sources(("Market Data Services"))
node_robinhood(("Brokerage Snapshot"))

node_researcher -->|"runs backtest"| node_main
node_main -->|"loads data"| node_trusted
node_trusted -->|"fetches sources"| node_provider
node_market_sources -.->|"supplies data"| node_provider
node_trusted -->|"checks quality"| node_quality
node_main -->|"builds features"| node_features
node_main -->|"scores assets"| node_strategy
node_main -->|"detects regime"| node_regime
node_main -->|"scales weights"| node_risk
node_main -->|"runs replay"| node_backtest
node_backtest -->|"updates holdings"| node_ledger
node_main -->|"summarizes results"| node_reporter
node_researcher -->|"registers study"| node_protocol
node_protocol -->|"constrains evaluation"| node_admission
node_admission -->|"submits results"| node_admission_service
node_admission_service -->|"persists trials"| node_governance
node_researcher -->|"runs paper cycle"| node_paper
node_paper -->|"requests allocation"| node_signals
node_paper -->|"manages orders"| node_oms
node_oms -->|"previews submits"| node_broker
node_oms -->|"records intents"| node_execution_store
node_researcher -->|"views research"| node_dashboard
node_robinhood -->|"provides snapshot"| node_mirror_store
node_mirror -->|"reads snapshots"| node_mirror_store
node_dashboard -->|"reads persisted data"| node_database

click node_main "https://github.com/aydanli/quant_investment/blob/master/main.py"
click node_trusted "https://github.com/aydanli/quant_investment/blob/master/data/trusted_loader.py"
click node_provider "https://github.com/aydanli/quant_investment/blob/master/data/providers.py"
click node_quality "https://github.com/aydanli/quant_investment/blob/master/data/quality.py"
click node_features "https://github.com/aydanli/quant_investment/blob/master/data/features.py"
click node_strategy "https://github.com/aydanli/quant_investment/blob/master/strategy/momentum_rotation.py"
click node_regime "https://github.com/aydanli/quant_investment/blob/master/strategy/regime.py"
click node_risk "https://github.com/aydanli/quant_investment/blob/master/risk/engine.py"
click node_backtest "https://github.com/aydanli/quant_investment/blob/master/backtest/engine.py"
click node_ledger "https://github.com/aydanli/quant_investment/blob/master/backtest/ledger.py"
click node_reporter "https://github.com/aydanli/quant_investment/blob/master/report/reporter.py"
click node_admission "https://github.com/aydanli/quant_investment/blob/master/research/nested_walk_forward.py"
click node_admission_service "https://github.com/aydanli/quant_investment/blob/master/research/admission_service.py"
click node_protocol "https://github.com/aydanli/quant_investment/blob/master/research/protocol.py"
click node_governance "https://github.com/aydanli/quant_investment/blob/master/storage/repositories/governance.py"
click node_paper "https://github.com/aydanli/quant_investment/blob/master/services/paper_cycle.py"
click node_signals "https://github.com/aydanli/quant_investment/blob/master/services/signal_service.py"
click node_oms "https://github.com/aydanli/quant_investment/blob/master/execution/oms.py"
click node_broker "https://github.com/aydanli/quant_investment/blob/master/execution/broker.py"
click node_execution_store "https://github.com/aydanli/quant_investment/blob/master/storage/repositories/execution.py"
click node_mirror "https://github.com/aydanli/quant_investment/blob/master/services/mirror_dashboard.py"
click node_mirror_store "https://github.com/aydanli/quant_investment/blob/master/storage/repositories/brokerage_mirror.py"
click node_dashboard "https://github.com/aydanli/quant_investment/blob/master/streamlit_dashboard_db_v1_1_save_experiment.py"
click node_database "https://github.com/aydanli/quant_investment/blob/master/storage/db.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_trusted,node_provider,node_quality,node_features toneBlue
class node_main,node_strategy,node_regime,node_risk,node_backtest,node_ledger toneAmber
class node_admission,node_admission_service,node_protocol,node_governance toneMint
class node_paper,node_signals,node_oms,node_broker,node_execution_store,node_database toneRose
class node_reporter,node_mirror,node_mirror_store,node_dashboard,node_researcher,node_market_sources,node_robinhood toneIndigo
```

## Components

### Market Data

- [Trusted Loader](https://github.com/aydanli/quant_investment/blob/master/data/trusted_loader.py): `data/trusted_loader.py`
- [Data Providers](https://github.com/aydanli/quant_investment/blob/master/data/providers.py): `data/providers.py`
- [Quality Checks](https://github.com/aydanli/quant_investment/blob/master/data/quality.py): `data/quality.py`
- [Feature Engineering](https://github.com/aydanli/quant_investment/blob/master/data/features.py): `data/features.py`

### Portfolio Engine

- [Backtest Entry](https://github.com/aydanli/quant_investment/blob/master/main.py): `main.py`
- [Momentum Strategy](https://github.com/aydanli/quant_investment/blob/master/strategy/momentum_rotation.py): `strategy/momentum_rotation.py`
- [Market Regime](https://github.com/aydanli/quant_investment/blob/master/strategy/regime.py): `strategy/regime.py`
- [Risk Engine](https://github.com/aydanli/quant_investment/blob/master/risk/engine.py): `risk/engine.py`
- [T+1 Backtest](https://github.com/aydanli/quant_investment/blob/master/backtest/engine.py): `backtest/engine.py`
- [Position Ledger](https://github.com/aydanli/quant_investment/blob/master/backtest/ledger.py): `backtest/ledger.py`

### Research Governance

- [Nested Admission](https://github.com/aydanli/quant_investment/blob/master/research/nested_walk_forward.py): `research/nested_walk_forward.py`
- [Admission Persistence](https://github.com/aydanli/quant_investment/blob/master/research/admission_service.py): `research/admission_service.py`
- [Research Protocol](https://github.com/aydanli/quant_investment/blob/master/research/protocol.py): `research/protocol.py`
- [Governance Store](https://github.com/aydanli/quant_investment/blob/master/storage/repositories/governance.py): `storage/repositories/governance.py`

### Paper Operations

- [Local Paper Cycle](https://github.com/aydanli/quant_investment/blob/master/services/paper_cycle.py): `services/paper_cycle.py`
- [Signal Service](https://github.com/aydanli/quant_investment/blob/master/services/signal_service.py): `services/signal_service.py`
- [Order Management](https://github.com/aydanli/quant_investment/blob/master/execution/oms.py): `execution/oms.py`
- [Broker Boundary](https://github.com/aydanli/quant_investment/blob/master/execution/broker.py): `execution/broker.py`
- [Execution Store](https://github.com/aydanli/quant_investment/blob/master/storage/repositories/execution.py): `storage/repositories/execution.py`
- [SQLite Store](https://github.com/aydanli/quant_investment/blob/master/storage/db.py): `storage/db.py`

### Reporting Views

- [Backtest Reports](https://github.com/aydanli/quant_investment/blob/master/report/reporter.py): `report/reporter.py`
- [Robinhood Mirror](https://github.com/aydanli/quant_investment/blob/master/services/mirror_dashboard.py): `services/mirror_dashboard.py`
- [Mirror Snapshots](https://github.com/aydanli/quant_investment/blob/master/storage/repositories/brokerage_mirror.py): `storage/repositories/brokerage_mirror.py`
- [Research Dashboard](https://github.com/aydanli/quant_investment/blob/master/streamlit_dashboard_db_v1_1_save_experiment.py): `streamlit_dashboard_db_v1_1_save_experiment.py`

### Other components

- **Researcher**
- **Market Data Services**
- **Brokerage Snapshot**

## Connections

- Researcher → Backtest Entry: runs backtest
- Backtest Entry → Trusted Loader: loads data
- Trusted Loader → Data Providers: fetches sources
- Market Data Services → Data Providers: supplies data
- Trusted Loader → Quality Checks: checks quality
- Backtest Entry → Feature Engineering: builds features
- Backtest Entry → Momentum Strategy: scores assets
- Backtest Entry → Market Regime: detects regime
- Backtest Entry → Risk Engine: scales weights
- Backtest Entry → T+1 Backtest: runs replay
- T+1 Backtest → Position Ledger: updates holdings
- Backtest Entry → Backtest Reports: summarizes results
- Researcher → Research Protocol: registers study
- Research Protocol → Nested Admission: constrains evaluation
- Nested Admission → Admission Persistence: submits results
- Admission Persistence → Governance Store: persists trials
- Researcher → Local Paper Cycle: runs paper cycle
- Local Paper Cycle → Signal Service: requests allocation
- Local Paper Cycle → Order Management: manages orders
- Order Management → Broker Boundary: previews submits
- Order Management → Execution Store: records intents
- Researcher → Research Dashboard: views research
- Brokerage Snapshot → Mirror Snapshots: provides snapshot
- Robinhood Mirror → Mirror Snapshots: reads snapshots
- Research Dashboard → SQLite Store: reads persisted data