How assaf750/quantum-trade works
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 Scripts · configs Configs · pipeline.py Data ingest · trainer.py Training
Components 22
Control plane
Repo-wide policy, contracts, and governance inputs.
- Configs · System rules: sprint gates, RBAC, stack policy, execution waves, contracts.
configs
Research pipeline
Python data, feature, training, and validation flow.
- Scripts · Operational automation for acquisition, audits, scans, backtests, and sprint runs.
scripts - Data ingest · Market data acquisition, normalization, recovery, and storage helpers.
data/ingestion/pipeline.py - Data storage · Append-only manifests and file-based persistence for pipeline outputs.
data/storage/append_only.py - Signals · Capture, trust, idempotency, repainting, and universe gating.
signals - Features · Feature DAG, leakage guards, registry, and vectorization.
features/dag.py - Labels · Label maturity, state machine, and survival-bias handling.
labels/state_machine.py - Training · Dataset assembly, baselines, offline training, and trackers.
training/trainer.py - Evaluation · Metrics, simulation, fees, and promotion gates.
evaluation/promotion_gates.py - Governance · Champion/challenger promotion, retraining, and proposal rules.
governance/promotion.py - Inference · Decision arbitration and inference output generation.
inference/decision_service.py
Execution & safety
Intent, risk, routing, and reconciliation boundaries.
- Risk guard · Kill-switch control point for blocking unsafe execution.
risk/kill_switch.py - Exec guard · Execution normalization, guardrails, intent, and reconciliation.
execution/guard.py - Adapters · Dry-run, testnet, and rehearsal adapters for execution paths.
execution/adapters/testnet_skeleton.py - Rust services · 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 · Concrete research job runtime with persisted state and UI-visible progress.
services/research_job_runner/app.py - API · Small operational API surface for status, trace, and websocket envelopes.
api/main.py - React apps · Multiple operator UIs: quantum shell, research platform, strategy registry, execution console, data platform.
apps/web - Shared UI · Reusable UI, charting, governance widgets, API clients, and shared contracts.
packages - Flutter app · Parallel control-center implementation with governance, live control, and trace explorer.
ui/flutter_app/lib/main.dart
Connections 26
- 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.