# dreamer-85/quant-lab architecture

> Architecture diagram of the GitHub repository dreamer-85/quant-lab, 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/dreamer-85/quant-lab
- Repository: https://github.com/dreamer-85/quant-lab

## Overview

QuantLab Research Engine is a bounded-memory market-data research pipeline built on Lean. Its principal workflow streams raw market events, deterministically reorders and replays them, reconstructs state and observations, computes features, optionally attaches delayed-return labels, then runs experiments and writes results. The README also documents checkpoint/resume, configurable feature and experiment plugins, and local/cloud orchestration. Sampled engine excerpts support the replay, observation, feature, and experiment responsibilities; storage, labeling, input merging, and orchestration details are represented only at the documented subsystem level.

Main entry points: [`Research/Engine/Replay/EventReplayEngine.cs`](https://github.com/dreamer-85/quant-lab/blob/main/Research/Engine/Replay/EventReplayEngine.cs) (Deterministic replay), [`Research/Runner`](https://github.com/dreamer-85/quant-lab/tree/main/Research/Runner) (Job runner), [`Research/Engine/Observations/ObservationEngine.cs`](https://github.com/dreamer-85/quant-lab/blob/main/Research/Engine/Observations/ObservationEngine.cs) (Observation engine), [`Research/Python/quantlab`](https://github.com/dreamer-85/quant-lab/tree/main/Research/Python/quantlab) (Unified CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Data and replay"]
  node_input_stream["Stream and merge"]
  node_event_replay["Deterministic replay"]
  node_market_state["Market state"]
  node_observations["Observation engine"]
end

subgraph group_analysis["Research analysis"]
  node_labels["Future-return labels"]
  node_features["Feature engine<br/>[FeatureEngine.cs]"]
  node_experiments["Experiment engine"]
end

subgraph group_runtime["Job runtime"]
  node_result_writer["Result streaming"]
  node_job_config["Job configuration"]
  node_runner["Job runner"]
  node_checkpoint[("Checkpoint resume")]
end

subgraph group_operations["Run operations"]
  node_unified_cli["Unified CLI"]
end

node_researcher(("Researcher"))
node_market_data[("Market data")]
node_result_files[("CSV JSON Parquet")]
node_cloud_vm(("Cloud VM"))

node_researcher -->|"submits job"| node_unified_cli
node_researcher -->|"defines job"| node_job_config
node_job_config -->|"configures"| node_runner
node_unified_cli -->|"runs locally"| node_runner
node_unified_cli -.->|"dispatches job"| node_cloud_vm
node_cloud_vm -.->|"runs remotely"| node_runner
node_market_data -->|"streams files"| node_input_stream
node_input_stream -->|"merged events"| node_event_replay
node_runner -->|"starts replay"| node_event_replay
node_event_replay -->|"reconstructs state"| node_market_state
node_event_replay -->|"snapshots state"| node_checkpoint
node_checkpoint -->|"restores state"| node_event_replay
node_event_replay -->|"emits results"| node_observations
node_observations -.->|"provides observations"| node_labels
node_observations -->|"provides observations"| node_features
node_labels -.->|"provides outcomes"| node_experiments
node_features -->|"provides features"| node_experiments
node_experiments -->|"produces results"| node_result_writer
node_result_writer -->|"streams output"| node_result_files

click node_input_stream "https://github.com/dreamer-85/quant-lab/tree/main/Research/Engine"
click node_event_replay "https://github.com/dreamer-85/quant-lab/blob/main/Research/Engine/Replay/EventReplayEngine.cs"
click node_market_state "https://github.com/dreamer-85/quant-lab/tree/main/Research/Engine"
click node_observations "https://github.com/dreamer-85/quant-lab/blob/main/Research/Engine/Observations/ObservationEngine.cs"
click node_labels "https://github.com/dreamer-85/quant-lab/tree/main/Research/Engine"
click node_features "https://github.com/dreamer-85/quant-lab/blob/main/Research/Engine/Features/FeatureEngine.cs"
click node_experiments "https://github.com/dreamer-85/quant-lab/blob/main/Research/Engine/Experiments/ExperimentEngine.cs"
click node_result_writer "https://github.com/dreamer-85/quant-lab/tree/main/Research/Engine"
click node_job_config "https://github.com/dreamer-85/quant-lab/tree/main/Research/Engine"
click node_runner "https://github.com/dreamer-85/quant-lab/tree/main/Research/Runner"
click node_checkpoint "https://github.com/dreamer-85/quant-lab/tree/main/Research/Engine"
click node_unified_cli "https://github.com/dreamer-85/quant-lab/tree/main/Research/Python/quantlab"

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_input_stream,node_event_replay,node_market_state,node_observations toneBlue
class node_labels,node_features,node_experiments,node_market_data,node_result_files toneAmber
class node_result_writer,node_job_config,node_runner,node_checkpoint toneMint
class node_unified_cli toneRose
class node_researcher,node_cloud_vm toneIndigo
```

## Components

### Data and replay

- [Stream and merge](https://github.com/dreamer-85/quant-lab/tree/main/Research/Engine): `Research/Engine`
- [Deterministic replay](https://github.com/dreamer-85/quant-lab/blob/main/Research/Engine/Replay/EventReplayEngine.cs): `Research/Engine/Replay/EventReplayEngine.cs`
- [Market state](https://github.com/dreamer-85/quant-lab/tree/main/Research/Engine): `Research/Engine`
- [Observation engine](https://github.com/dreamer-85/quant-lab/blob/main/Research/Engine/Observations/ObservationEngine.cs): `Research/Engine/Observations/ObservationEngine.cs`

### Research analysis

- [Future-return labels](https://github.com/dreamer-85/quant-lab/tree/main/Research/Engine): `Research/Engine`
- [Feature engine](https://github.com/dreamer-85/quant-lab/blob/main/Research/Engine/Features/FeatureEngine.cs): `Research/Engine/Features/FeatureEngine.cs`
- [Experiment engine](https://github.com/dreamer-85/quant-lab/blob/main/Research/Engine/Experiments/ExperimentEngine.cs): `Research/Engine/Experiments/ExperimentEngine.cs`

### Job runtime

- [Result streaming](https://github.com/dreamer-85/quant-lab/tree/main/Research/Engine): `Research/Engine`
- [Job configuration](https://github.com/dreamer-85/quant-lab/tree/main/Research/Engine): `Research/Engine`
- [Job runner](https://github.com/dreamer-85/quant-lab/tree/main/Research/Runner): `Research/Runner`
- [Checkpoint resume](https://github.com/dreamer-85/quant-lab/tree/main/Research/Engine): `Research/Engine`

### Run operations

- [Unified CLI](https://github.com/dreamer-85/quant-lab/tree/main/Research/Python/quantlab): `Research/Python/quantlab`

### Other components

- **Researcher**
- **Market data**
- **CSV JSON Parquet**
- **Cloud VM**

## Connections

- Researcher → Unified CLI: submits job
- Researcher → Job configuration: defines job
- Job configuration → Job runner: configures
- Unified CLI → Job runner: runs locally
- Unified CLI → Cloud VM: dispatches job
- Cloud VM → Job runner: runs remotely
- Market data → Stream and merge: streams files
- Stream and merge → Deterministic replay: merged events
- Job runner → Deterministic replay: starts replay
- Deterministic replay → Market state: reconstructs state
- Deterministic replay → Checkpoint resume: snapshots state
- Checkpoint resume → Deterministic replay: restores state
- Deterministic replay → Observation engine: emits results
- Observation engine → Future-return labels: provides observations
- Observation engine → Feature engine: provides observations
- Future-return labels → Experiment engine: provides outcomes
- Feature engine → Experiment engine: provides features
- Experiment engine → Result streaming: produces results
- Result streaming → CSV JSON Parquet: streams output