# assaf750/quantum-trade architecture

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

- Interactive diagram: https://gitdiagram.com/assaf750/quantum-trade
- Repository: https://github.com/assaf750/quantum-trade

## Overview

1. **What this repo is**
   - This is a monorepo for a quant research, governance, and trading-operations platform.
   - It is explicitly sprint-gated: the repo is organized around a roadmap, with live trading disabled until later hard gates. The current operational shape is a research pipeline plus operator consoles, not a single app.

2. **Top-level control plane**
   - `configs/` defines the system’s rules: sprint registry, readiness gates, execution waves, forbidden scope, RBAC, contracts, and stack/version policy.
   - `docs/adr/`, `docs/design/`, and `reports/` form the governance/evidence layer. Architecture decisions, sprint acceptance, and evidence reports are first-class outputs, not just documentation.

3. **Python domain pipeline**
   - The main domain pipeline is in Python packages such as `data/`, `signals/`, `features/`, `labels/`, `training/`, `evaluation/`, `governance/`, `inference/`, `risk/`, `execution/`, and `monitoring/`.
   - The intended flow is: ingest market data → normalize/quality-check → derive signals/features → generate labels → train/evaluate models → apply governance/promotion rules → produce inference decisions → enforce risk/kill-switch controls → route execution → monitor outcomes.

4. **Data platform and artifact flow**
   - `data/` contains ingestion, quality, recovery, and storage helpers, plus manifest files that describe OHLCV coverage, features, strategy candidates, and robustness artifacts.
   - `data/storage/` and `reports/` are the main persistence boundaries for pipeline outputs. The repository uses generated JSON/MD reports heavily, so many subsystems exchange data through file-based manifests rather than direct in-memory coupling.

5. **Batch research automation**
   - `scripts/` is the operational automation layer: acquisition, resampling, dataset building, audits, strategy scans, backtests, and sprint runners.
   - `services/research_job_runner/` is a concrete runtime service for orchestrating multi-stage research jobs, persisting job state/logs, and feeding UI-visible progress. This is the current entrypoint called out in the README.

6. **Rust service boundary**
   - `rust-services/` is a separate backend implementation boundary with multiple crates: `data_service`, `research_service`, `strategy_registry_service`, `execution_service`, `operator_gateway`, `live_arming_gate`, `order_router`, `risk_engine`, `testnet_exchange_adapter`, `execution_audit`, `rbac`, `observability`, and supporting contract crates.
   - These crates indicate the platform is being split into typed services for data, research, governance, execution, and safety. Rust is used where the system needs stronger contracts, lower-latency paths, or safer execution boundaries.

7. **Execution and safety architecture**
   - The execution side is explicitly guarded by `risk/kill_switch.py`, `execution/guard.py`, `execution/reconciliation.py`, `execution/adapters/`, and the Rust `order_router` / `execution_service` / `live_arming_gate`.
   - The architecture separates “intent,” “authorization,” “routing,” and “audit” so that a trade cannot be placed without passing readiness, policy, and reconciliation layers. Testnet/mock adapters exist, but the repo says real capital and live trading are off by default.

8. **Research and strategy lifecycle**
   - `analysis/`, `backtest/`, `training/`, `evaluation/`, and `governance/` represent the research lifecycle from hypothesis exploration through backtest validation and promotion decisions.
   - The many sprint-specific analysis scripts and the report tree show an iterative evidence pipeline: candidate generation, robustness testing, OOS validation, and then promotion/firewall decisions.

9. **UI layer: multiple frontends, multiple personas**
   - `apps/web/` contains several React/Vite applications: `quantum_shell`, `research_platform`, `strategy_registry`, `execution_console_mock`, and `data_platform`.
   - These are not duplicate apps; they cover different operator surfaces: research workflow, strategy governance, execution console, and data intelligence. Most screens are mock/fixture-driven or snapshot-driven, which matches the repo’s current evidence-first development stage.

10. **Shared frontend packages**
   - `packages/` contains reusable UI and contract libraries: `react_design_system`, `react_charts`, `react_governance`, `react_api_client`, `data_contracts`, `shared_contracts`, and `strategy_schema`.
   - This is the main front-end boundary between product surfaces and backend contracts. UI apps consume shared types, mock providers, chart primitives, governance widgets, and API clients instead of re-declaring them per app.

11. **Additional operator UI**
   - `ui/flutter_app/` is a Flutter-based control-center implementation with contracts, state, and widgets for governance, live control, trace exploration, and customization coverage.
   - The repo therefore has a mixed UI strategy: React is the main active surface in `apps/web/`, while Flutter exists as a parallel command-center implementation referenced by older design docs and sprint artifacts.

12. **API and service surface**
   - `api/main.py` exposes a FastAPI control surface, with routes like `status` and `trace`, plus websocket envelope handling.
   - This API is intentionally small at the foundation stage and acts more like an operational/status gateway than a full product API.

13. **Persistence and auditability**
   - `core/db/`, `core/audit/`, and `alembic/` provide repository abstractions, append-only audit logging, and database schema migrations.
   - The audit model is important architecturally: operational actions, governance decisions, and execution-related events are meant to be traceable and replayable.

14. **Generated outputs and verification**
   - A large part of the system is “compile to artifacts”: snapshots under `apps/web/.../src/generated/`, manifests in `data/storage/`, and evidence under `reports/`.
   - `tests/` encodes the system contract end-to-end, including sprint-specific integration tests that verify roadmap stages, safety gates, and service boundaries.

15. **How to diagram it**
   - Draw three main planes: **control/governance** at the top, **research/data/execution services** in the middle, and **operator UIs + reports** on the side.
   - The key flow is: configs and gates constrain scripts/services → Python/Rust pipelines produce manifests/audit records → frontends read generated snapshots and status → execution paths remain blocked behind risk/arming/governance checks unless explicitly enabled.

Main entry points: [`scripts`](https://github.com/assaf750/quantum-trade/tree/sprint-139/v0-integration/scripts) (Scripts), [`configs`](https://github.com/assaf750/quantum-trade/tree/sprint-139/v0-integration/configs) (Configs), [`data/ingestion/pipeline.py`](https://github.com/assaf750/quantum-trade/blob/sprint-139/v0-integration/data/ingestion/pipeline.py) (Data ingest), [`training/trainer.py`](https://github.com/assaf750/quantum-trade/blob/sprint-139/v0-integration/training/trainer.py) (Training)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control plane"]
  node_configs["Configs<br/>policy/contracts"]
end

subgraph group_research["Research pipeline"]
  node_scripts["Scripts<br/>automation/runner"]
  node_data_ingest["Data ingest<br/>python/data<br/>[pipeline.py]"]
  node_data_storage[("Data storage<br/>artifacts/manifests<br/>[append_only.py]")]
  node_signals["Signals"]
  node_features["Features<br/>[dag.py]"]
  node_labels["Labels<br/>[state_machine.py]"]
  node_training["Training<br/>[trainer.py]"]
  node_evaluation["Evaluation<br/>python/eval<br/>[promotion_gates.py]"]
  node_governance["Governance<br/>promotion/policy<br/>[promotion.py]"]
  node_inference["Inference<br/>decision service"]
end

subgraph group_execution["Execution & safety"]
  node_risk["Risk guard<br/>kill-switch/risk<br/>[kill_switch.py]"]
  node_execution_guard["Exec guard<br/>order safety<br/>[guard.py]"]
  node_execution_adapters["Adapters"]
  node_rust_services["Rust services<br/>typed backends"]
end

subgraph group_ui["Operator surfaces"]
  node_research_runner["Job runner<br/>service/orchestrator<br/>[app.py]"]
  node_api["API<br/>[main.py]"]
  node_react_apps["React apps<br/>frontend surfaces"]
  node_react_packages["Shared UI<br/>frontend libs"]
  node_flutter_app["Flutter app<br/>command center<br/>[main.dart]"]
end

subgraph group_evidence["Evidence layer"]
  node_docs_adr["ADRs<br/>governance/decisions"]
  node_reports["Reports<br/>evidence/artifacts"]
end

node_configs -->|"gates & policies"| node_scripts
node_configs -->|"job contracts"| node_research_runner
node_configs -->|"service policies"| node_rust_services
node_docs_adr -->|"codifies"| node_configs
node_reports -->|"evidence for"| node_docs_adr
node_scripts -->|"acquire/repair"| node_data_ingest
node_scripts -->|"train/scan"| node_training
node_scripts -->|"backtest/audit"| node_evaluation
node_data_ingest -->|"persist manifests"| node_data_storage
node_data_ingest -->|"feeds"| node_signals
node_signals -->|"derive"| node_features
node_features -->|"pair with"| node_labels
node_labels -->|"dataset"| node_training
node_training -->|"models"| node_evaluation
node_evaluation -->|"promote/reject"| node_governance
node_governance -->|"authorize"| node_inference
node_inference -->|"intent check"| node_risk
node_risk -->|"gate"| node_execution_guard
node_execution_guard -->|"route"| node_execution_adapters
node_execution_adapters -->|"backend path"| node_rust_services
node_research_runner -->|"writes evidence"| node_reports
node_api -->|"serves status"| node_react_apps
node_react_packages -->|"shared UI"| node_react_apps
node_react_apps -->|"reads snapshots"| node_reports
node_flutter_app -->|"control surface"| node_api
node_rust_services -.->|"operational backend"| node_api

click node_configs "https://github.com/assaf750/quantum-trade/tree/sprint-139/v0-integration/configs"
click node_docs_adr "https://github.com/assaf750/quantum-trade/tree/sprint-139/v0-integration/docs/adr"
click node_reports "https://github.com/assaf750/quantum-trade/tree/sprint-139/v0-integration/reports"
click node_scripts "https://github.com/assaf750/quantum-trade/tree/sprint-139/v0-integration/scripts"
click node_data_ingest "https://github.com/assaf750/quantum-trade/blob/sprint-139/v0-integration/data/ingestion/pipeline.py"
click node_data_storage "https://github.com/assaf750/quantum-trade/blob/sprint-139/v0-integration/data/storage/append_only.py"
click node_signals "https://github.com/assaf750/quantum-trade/tree/sprint-139/v0-integration/signals"
click node_features "https://github.com/assaf750/quantum-trade/blob/sprint-139/v0-integration/features/dag.py"
click node_labels "https://github.com/assaf750/quantum-trade/blob/sprint-139/v0-integration/labels/state_machine.py"
click node_training "https://github.com/assaf750/quantum-trade/blob/sprint-139/v0-integration/training/trainer.py"
click node_evaluation "https://github.com/assaf750/quantum-trade/blob/sprint-139/v0-integration/evaluation/promotion_gates.py"
click node_governance "https://github.com/assaf750/quantum-trade/blob/sprint-139/v0-integration/governance/promotion.py"
click node_inference "https://github.com/assaf750/quantum-trade/blob/sprint-139/v0-integration/inference/decision_service.py"
click node_risk "https://github.com/assaf750/quantum-trade/blob/sprint-139/v0-integration/risk/kill_switch.py"
click node_execution_guard "https://github.com/assaf750/quantum-trade/blob/sprint-139/v0-integration/execution/guard.py"
click node_execution_adapters "https://github.com/assaf750/quantum-trade/blob/sprint-139/v0-integration/execution/adapters/testnet_skeleton.py"
click node_research_runner "https://github.com/assaf750/quantum-trade/blob/sprint-139/v0-integration/services/research_job_runner/app.py"
click node_api "https://github.com/assaf750/quantum-trade/blob/sprint-139/v0-integration/api/main.py"
click node_react_apps "https://github.com/assaf750/quantum-trade/tree/sprint-139/v0-integration/apps/web"
click node_react_packages "https://github.com/assaf750/quantum-trade/tree/sprint-139/v0-integration/packages"
click node_flutter_app "https://github.com/assaf750/quantum-trade/blob/sprint-139/v0-integration/ui/flutter_app/lib/main.dart"
click node_rust_services "https://github.com/assaf750/quantum-trade/tree/sprint-139/v0-integration/rust-services/crates"

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_configs toneBlue
class node_scripts,node_data_ingest,node_data_storage,node_signals,node_features,node_labels,node_training,node_evaluation,node_governance,node_inference toneAmber
class node_risk,node_execution_guard,node_execution_adapters,node_rust_services toneMint
class node_research_runner,node_api,node_react_apps,node_react_packages,node_flutter_app toneRose
class node_docs_adr,node_reports toneIndigo
```

## Components

### Control plane

Repo-wide policy, contracts, and governance inputs.

- [Configs](https://github.com/assaf750/quantum-trade/tree/sprint-139/v0-integration/configs): policy/contracts · System rules: sprint gates, RBAC, stack policy, execution waves, contracts. · `configs`

### Research pipeline

Python data, feature, training, and validation flow.

- [Scripts](https://github.com/assaf750/quantum-trade/tree/sprint-139/v0-integration/scripts): automation/runner · Operational automation for acquisition, audits, scans, backtests, and sprint runs. · `scripts`
- [Data ingest](https://github.com/assaf750/quantum-trade/blob/sprint-139/v0-integration/data/ingestion/pipeline.py): python/data · Market data acquisition, normalization, recovery, and storage helpers. · `data/ingestion/pipeline.py`
- [Data storage](https://github.com/assaf750/quantum-trade/blob/sprint-139/v0-integration/data/storage/append_only.py): artifacts/manifests · Append-only manifests and file-based persistence for pipeline outputs. · `data/storage/append_only.py`
- [Signals](https://github.com/assaf750/quantum-trade/tree/sprint-139/v0-integration/signals): python/signals · Capture, trust, idempotency, repainting, and universe gating. · `signals`
- [Features](https://github.com/assaf750/quantum-trade/blob/sprint-139/v0-integration/features/dag.py): python/features · Feature DAG, leakage guards, registry, and vectorization. · `features/dag.py`
- [Labels](https://github.com/assaf750/quantum-trade/blob/sprint-139/v0-integration/labels/state_machine.py): python/labels · Label maturity, state machine, and survival-bias handling. · `labels/state_machine.py`
- [Training](https://github.com/assaf750/quantum-trade/blob/sprint-139/v0-integration/training/trainer.py): python/training · Dataset assembly, baselines, offline training, and trackers. · `training/trainer.py`
- [Evaluation](https://github.com/assaf750/quantum-trade/blob/sprint-139/v0-integration/evaluation/promotion_gates.py): python/eval · Metrics, simulation, fees, and promotion gates. · `evaluation/promotion_gates.py`
- [Governance](https://github.com/assaf750/quantum-trade/blob/sprint-139/v0-integration/governance/promotion.py): promotion/policy · Champion/challenger promotion, retraining, and proposal rules. · `governance/promotion.py`
- [Inference](https://github.com/assaf750/quantum-trade/blob/sprint-139/v0-integration/inference/decision_service.py): decision service · Decision arbitration and inference output generation. · `inference/decision_service.py`

### Execution & safety

Intent, risk, routing, and reconciliation boundaries.

- [Risk guard](https://github.com/assaf750/quantum-trade/blob/sprint-139/v0-integration/risk/kill_switch.py): kill-switch/risk · Kill-switch control point for blocking unsafe execution. · `risk/kill_switch.py`
- [Exec guard](https://github.com/assaf750/quantum-trade/blob/sprint-139/v0-integration/execution/guard.py): order safety · Execution normalization, guardrails, intent, and reconciliation. · `execution/guard.py`
- [Adapters](https://github.com/assaf750/quantum-trade/blob/sprint-139/v0-integration/execution/adapters/testnet_skeleton.py): execution adapters · Dry-run, testnet, and rehearsal adapters for execution paths. · `execution/adapters/testnet_skeleton.py`
- [Rust services](https://github.com/assaf750/quantum-trade/tree/sprint-139/v0-integration/rust-services/crates): typed backends · Service boundary for data, research, registry, execution, arming, routing, RBAC, and observability. · `rust-services/crates`

### Operator surfaces

React, Flutter, and API surfaces for operators.

- [Job runner](https://github.com/assaf750/quantum-trade/blob/sprint-139/v0-integration/services/research_job_runner/app.py): service/orchestrator · Concrete research job runtime with persisted state and UI-visible progress. · `services/research_job_runner/app.py`
- [API](https://github.com/assaf750/quantum-trade/blob/sprint-139/v0-integration/api/main.py): fastapi/gateway · Small operational API surface for status, trace, and websocket envelopes. · `api/main.py`
- [React apps](https://github.com/assaf750/quantum-trade/tree/sprint-139/v0-integration/apps/web): frontend surfaces · Multiple operator UIs: quantum shell, research platform, strategy registry, execution console, data platform. · `apps/web`
- [Shared UI](https://github.com/assaf750/quantum-trade/tree/sprint-139/v0-integration/packages): frontend libs · Reusable UI, charting, governance widgets, API clients, and shared contracts. · `packages`
- [Flutter app](https://github.com/assaf750/quantum-trade/blob/sprint-139/v0-integration/ui/flutter_app/lib/main.dart): command center · Parallel control-center implementation with governance, live control, and trace explorer. · `ui/flutter_app/lib/main.dart`

### Evidence layer

Reports, ADRs, and sprint outputs that record decisions.

- [ADRs](https://github.com/assaf750/quantum-trade/tree/sprint-139/v0-integration/docs/adr): governance/decisions · Architecture decisions and wave-level governance records. · `docs/adr`
- [Reports](https://github.com/assaf750/quantum-trade/tree/sprint-139/v0-integration/reports): evidence/artifacts · Acceptance, audit, robustness, and sprint evidence outputs. · `reports`

## Connections

- Configs → Scripts: gates & policies · Sprint registry and readiness rules constrain automation.
- Configs → Job runner: job contracts · Execution waves and status contracts shape the job runner.
- Configs → Rust services: service policies · Typed backend crates follow repo-wide contracts and version policy.
- ADRs → Configs: codifies · ADRs formalize the governance and policy settings.
- Reports → ADRs: evidence for · Acceptance and audit reports feed architecture decisions.
- Scripts → Data ingest: acquire/repair · Scripts drive acquisition, resampling, and bootstrap flows.
- Scripts → Training: train/scan · Scripts orchestrate dataset builds, training, and strategy scans.
- Scripts → Evaluation: backtest/audit · Scripts run backtests, calibration, and robustness checks.
- Data ingest → Data storage: persist manifests · Ingestion and normalization write file-based artifacts and manifests.
- Data ingest → Signals: feeds · Normalized market data becomes signal input.
- Signals → Features: derive · Signal capture and universe gating feed feature generation.
- Features → Labels: pair with · Feature matrices align with label construction and leakage guards.
- Labels → Training: dataset · Labels are assembled into training datasets.
- Training → Evaluation: models · Trained models are evaluated and scored against promotion gates.
- Evaluation → Governance: promote/reject · Metrics and robustness decide promotion eligibility.
- Governance → Inference: authorize · Promotion policy governs which decision logic may advance.
- Inference → Risk guard: intent check · Inference outputs must pass kill-switch and policy checks.
- Risk guard → Exec guard: gate · Risk decisions constrain execution guard behavior.
- Exec guard → Adapters: route · Guarded intents flow to dry-run and testnet adapters.
- Adapters → Rust services: backend path · Rust execution boundary hosts typed routers, arming, and adapters.
- Job runner → Reports: writes evidence · Research jobs persist logs, state, and operator-visible progress reports.
- API → React apps: serves status · Control endpoints and websocket envelopes feed the UI layer.
- Shared UI → React apps: shared UI · Apps consume shared design, chart, API, and contract libraries.
- React apps → Reports: reads snapshots · Frontends render generated snapshots, manifests, and evidence artifacts.
- Flutter app → API: control surface · Flutter command-center consumes the same operational gateway.
- Rust services → API: operational backend · Rust service boundary supports future control and execution APIs.
