# loki4099/migratorybirdquantiveproject architecture

> Architecture diagram of the GitHub repository loki4099/migratorybirdquantiveproject, 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/loki4099/migratorybirdquantiveproject
- Repository: https://github.com/loki4099/migratorybirdquantiveproject

## Overview

Migratory Bird is a local-first, versioned quantitative research platform. Researchers configure a governed universe and graph in the browser, then the backend validates and runs processing, aggregation, strategy, and frozen weekly/monthly experiments; results expose rankings, diagnostics, lineage, and evidence. Accepted results may cross into separately monitored Research Products. The README documents the domain workflow and major capabilities; the sampled source and index support selected frontend routes, API use, runtime modules, and reproducibility layers. Several backend stages are represented by their enclosing runtime modules because their detailed implementations were not sampled.

Main entry points: [`src/style_rotation/experiment/engine.py`](https://github.com/loki4099/migratorybirdquantiveproject/blob/main/src/style_rotation/experiment/engine.py) (Backtest evidence), [`src/style_rotation/v022/representative_pipeline_runtime.py`](https://github.com/loki4099/migratorybirdquantiveproject/blob/main/src/style_rotation/v022/representative_pipeline_runtime.py) (Three processing layers), [`src/style_rotation/v022/aggregation_work_runtime.py`](https://github.com/loki4099/migratorybirdquantiveproject/blob/main/src/style_rotation/v022/aggregation_work_runtime.py) (Aggregation runtime), [`src/style_rotation/lineage/service.py`](https://github.com/loki4099/migratorybirdquantiveproject/blob/main/src/style_rotation/lineage/service.py) (Immutable lineage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ux["Research workspace"]
  node_workspace_ui["Graph workspace"]
  node_draft_context["Draft context"]
  node_api_client["API client<br/>[client.ts]"]
  node_result_ui["Result views"]
end

subgraph group_data["Governed data"]
  node_market_data[("Governed market data<br/>[pipeline.py]")]
  node_universe["Historical universe"]
end

subgraph group_research["Research pipeline"]
  node_asset_selection["Asset selection<br/>[asset_selection.py]"]
  node_processing["Three processing layers"]
  node_workspace_context["Frozen workspace context"]
  node_aggregation["Aggregation runtime"]
  node_strategy["Top-K strategy<br/>[engine.py]"]
end

subgraph group_results["Experiments and products"]
  node_suite["Weekly/monthly suites"]
  node_backtest["Backtest evidence<br/>[engine.py]"]
  node_ranking["Cohort ranking<br/>[ranking.py]"]
  node_product["Product monitoring"]
end

subgraph group_foundation["Runtime and evidence"]
  node_api["Research API<br/>[app.py]"]
  node_lineage[("Immutable lineage<br/>[service.py]")]
  node_canonical["Canonical identity<br/>[canonical.py]"]
  node_environment["Numerical environment<br/>[environment.py]"]
end

node_researcher(("Researcher"))
node_yahoo(("Yahoo Finance"))

node_researcher -->|"configures"| node_workspace_ui
node_workspace_ui -->|"edits draft"| node_draft_context
node_draft_context -->|"saves draft"| node_api_client
node_api_client -.->|"HTTP requests"| node_api
node_api -->|"loads context"| node_workspace_context
node_yahoo -->|"provides observations"| node_market_data
node_universe -->|"governs history"| node_market_data
node_market_data -->|"supplies inputs"| node_asset_selection
node_asset_selection -->|"selects assets"| node_processing
node_processing -->|"emits signals"| node_aggregation
node_aggregation -->|"scores assets"| node_strategy
node_strategy -->|"launches experiments"| node_suite
node_suite -->|"runs cells"| node_backtest
node_backtest -->|"publishes results"| node_ranking
node_ranking -->|"displays evidence"| node_result_ui
node_backtest -->|"promotes accepted cell"| node_product
node_processing -->|"records lineage"| node_lineage
node_aggregation -->|"records lineage"| node_lineage
node_backtest -.->|"records lineage"| node_lineage
node_lineage -->|"fingerprints artifacts"| node_canonical
node_processing -->|"canonicalizes identity"| node_canonical
node_aggregation -->|"canonicalizes identity"| node_canonical
node_backtest -->|"canonicalizes identity"| node_canonical
node_backtest -->|"captures environment"| node_environment

click node_workspace_ui "https://github.com/loki4099/migratorybirdquantiveproject/blob/main/frontend/src/pages/GraphWorkspacePage.tsx"
click node_draft_context "https://github.com/loki4099/migratorybirdquantiveproject/blob/main/frontend/src/workspace/GraphDraftContext.tsx"
click node_api_client "https://github.com/loki4099/migratorybirdquantiveproject/blob/main/frontend/src/api/client.ts"
click node_result_ui "https://github.com/loki4099/migratorybirdquantiveproject/blob/main/frontend/src/pages/ExperimentResultPage.tsx"
click node_api "https://github.com/loki4099/migratorybirdquantiveproject/blob/main/src/style_rotation/api/app.py"
click node_market_data "https://github.com/loki4099/migratorybirdquantiveproject/blob/main/src/style_rotation/data/pipeline.py"
click node_universe "https://github.com/loki4099/migratorybirdquantiveproject/blob/main/src/style_rotation/catalog/dynamic_universe.py"
click node_asset_selection "https://github.com/loki4099/migratorybirdquantiveproject/blob/main/src/style_rotation/v022/asset_selection.py"
click node_processing "https://github.com/loki4099/migratorybirdquantiveproject/blob/main/src/style_rotation/v022/representative_pipeline_runtime.py"
click node_workspace_context "https://github.com/loki4099/migratorybirdquantiveproject/blob/main/src/style_rotation/v022/workspace_context.py"
click node_aggregation "https://github.com/loki4099/migratorybirdquantiveproject/blob/main/src/style_rotation/v022/aggregation_work_runtime.py"
click node_strategy "https://github.com/loki4099/migratorybirdquantiveproject/blob/main/src/style_rotation/strategy/engine.py"
click node_suite "https://github.com/loki4099/migratorybirdquantiveproject/blob/main/src/style_rotation/experiment/orchestration_engine.py"
click node_backtest "https://github.com/loki4099/migratorybirdquantiveproject/blob/main/src/style_rotation/experiment/engine.py"
click node_ranking "https://github.com/loki4099/migratorybirdquantiveproject/blob/main/src/style_rotation/experiment/ranking.py"
click node_product "https://github.com/loki4099/migratorybirdquantiveproject/blob/main/src/style_rotation/product/monitoring_service.py"
click node_lineage "https://github.com/loki4099/migratorybirdquantiveproject/blob/main/src/style_rotation/lineage/service.py"
click node_canonical "https://github.com/loki4099/migratorybirdquantiveproject/blob/main/src/style_rotation/core/canonical.py"
click node_environment "https://github.com/loki4099/migratorybirdquantiveproject/blob/main/src/style_rotation/ops/environment.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_workspace_ui,node_draft_context,node_api_client,node_result_ui toneBlue
class node_market_data,node_universe toneAmber
class node_asset_selection,node_processing,node_workspace_context,node_aggregation,node_strategy toneMint
class node_suite,node_backtest,node_ranking,node_product toneRose
class node_api,node_lineage,node_canonical,node_environment,node_researcher,node_yahoo toneIndigo
```

## Components

### Research workspace

- [Graph workspace](https://github.com/loki4099/migratorybirdquantiveproject/blob/main/frontend/src/pages/GraphWorkspacePage.tsx): `frontend/src/pages/GraphWorkspacePage.tsx`
- [Draft context](https://github.com/loki4099/migratorybirdquantiveproject/blob/main/frontend/src/workspace/GraphDraftContext.tsx): `frontend/src/workspace/GraphDraftContext.tsx`
- [API client](https://github.com/loki4099/migratorybirdquantiveproject/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [Result views](https://github.com/loki4099/migratorybirdquantiveproject/blob/main/frontend/src/pages/ExperimentResultPage.tsx): `frontend/src/pages/ExperimentResultPage.tsx`

### Governed data

- [Governed market data](https://github.com/loki4099/migratorybirdquantiveproject/blob/main/src/style_rotation/data/pipeline.py): `src/style_rotation/data/pipeline.py`
- [Historical universe](https://github.com/loki4099/migratorybirdquantiveproject/blob/main/src/style_rotation/catalog/dynamic_universe.py): `src/style_rotation/catalog/dynamic_universe.py`

### Research pipeline

- [Asset selection](https://github.com/loki4099/migratorybirdquantiveproject/blob/main/src/style_rotation/v022/asset_selection.py): `src/style_rotation/v022/asset_selection.py`
- [Three processing layers](https://github.com/loki4099/migratorybirdquantiveproject/blob/main/src/style_rotation/v022/representative_pipeline_runtime.py): `src/style_rotation/v022/representative_pipeline_runtime.py`
- [Frozen workspace context](https://github.com/loki4099/migratorybirdquantiveproject/blob/main/src/style_rotation/v022/workspace_context.py): `src/style_rotation/v022/workspace_context.py`
- [Aggregation runtime](https://github.com/loki4099/migratorybirdquantiveproject/blob/main/src/style_rotation/v022/aggregation_work_runtime.py): `src/style_rotation/v022/aggregation_work_runtime.py`
- [Top-K strategy](https://github.com/loki4099/migratorybirdquantiveproject/blob/main/src/style_rotation/strategy/engine.py): `src/style_rotation/strategy/engine.py`

### Experiments and products

- [Weekly/monthly suites](https://github.com/loki4099/migratorybirdquantiveproject/blob/main/src/style_rotation/experiment/orchestration_engine.py): `src/style_rotation/experiment/orchestration_engine.py`
- [Backtest evidence](https://github.com/loki4099/migratorybirdquantiveproject/blob/main/src/style_rotation/experiment/engine.py): `src/style_rotation/experiment/engine.py`
- [Cohort ranking](https://github.com/loki4099/migratorybirdquantiveproject/blob/main/src/style_rotation/experiment/ranking.py): `src/style_rotation/experiment/ranking.py`
- [Product monitoring](https://github.com/loki4099/migratorybirdquantiveproject/blob/main/src/style_rotation/product/monitoring_service.py): `src/style_rotation/product/monitoring_service.py`

### Runtime and evidence

- [Research API](https://github.com/loki4099/migratorybirdquantiveproject/blob/main/src/style_rotation/api/app.py): `src/style_rotation/api/app.py`
- [Immutable lineage](https://github.com/loki4099/migratorybirdquantiveproject/blob/main/src/style_rotation/lineage/service.py): `src/style_rotation/lineage/service.py`
- [Canonical identity](https://github.com/loki4099/migratorybirdquantiveproject/blob/main/src/style_rotation/core/canonical.py): `src/style_rotation/core/canonical.py`
- [Numerical environment](https://github.com/loki4099/migratorybirdquantiveproject/blob/main/src/style_rotation/ops/environment.py): `src/style_rotation/ops/environment.py`

### Other components

- **Researcher**
- **Yahoo Finance**

## Connections

- Researcher → Graph workspace: configures
- Graph workspace → Draft context: edits draft (evidence: `frontend/src/workspace/GraphWorkspaceRoute.tsx`)
- Draft context → API client: saves draft (evidence: `frontend/src/workspace/GraphDraftContext.tsx`)
- API client → Research API: HTTP requests
- Research API → Frozen workspace context: loads context
- Yahoo Finance → Governed market data: provides observations
- Historical universe → Governed market data: governs history
- Governed market data → Asset selection: supplies inputs
- Asset selection → Three processing layers: selects assets
- Three processing layers → Aggregation runtime: emits signals (evidence: `src/style_rotation/v022/representative_pipeline_runtime.py`)
- Aggregation runtime → Top-K strategy: scores assets
- Top-K strategy → Weekly/monthly suites: launches experiments
- Weekly/monthly suites → Backtest evidence: runs cells
- Backtest evidence → Cohort ranking: publishes results
- Cohort ranking → Result views: displays evidence
- Backtest evidence → Product monitoring: promotes accepted cell
- Three processing layers → Immutable lineage: records lineage (evidence: `src/style_rotation/v022/representative_pipeline_runtime.py`)
- Aggregation runtime → Immutable lineage: records lineage (evidence: `src/style_rotation/v022/aggregation_work_runtime.py`)
- Backtest evidence → Immutable lineage: records lineage (evidence: `src/style_rotation/experiment/engine.py`)
- Immutable lineage → Canonical identity: fingerprints artifacts (evidence: `src/style_rotation/lineage/service.py`)
- Three processing layers → Canonical identity: canonicalizes identity (evidence: `src/style_rotation/v022/representative_pipeline_runtime.py`)
- Aggregation runtime → Canonical identity: canonicalizes identity (evidence: `src/style_rotation/v022/aggregation_work_runtime.py`)
- Backtest evidence → Canonical identity: canonicalizes identity (evidence: `src/style_rotation/experiment/engine.py`)
- Backtest evidence → Numerical environment: captures environment (evidence: `src/style_rotation/experiment/engine.py`)