# trishul4kumar-ui/nayak-quant-lab architecture

> Architecture diagram of the GitHub repository trishul4kumar-ui/nayak-quant-lab, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/trishul4kumar-ui/nayak-quant-lab
- Repository: https://github.com/trishul4kumar-ui/nayak-quant-lab

## Overview

QUANT LAB is a local-first quantitative research and pre-live controlled-execution laboratory, not a broker-connected chatbot. The principal workflow runs from point-in-time market data and integrity checks through research, alpha/model validation, portfolio and risk authorization, controlled execution, and attribution. The README documents this high-level sequence and many supporting labs; source excerpts confirm selected data, feature, regime, adaptive, ensemble, backtest, and desktop-pipeline behavior. Other subsystem links below are documented capabilities, not claims that unsampled implementations were inspected.

Main entry points: [`src/quantlab/features/engine.py`](https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/features/engine.py) (Feature engine), [`src/quantlab/data/fabric/store.py`](https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/data/fabric/store.py) (PIT data fabric), [`src/quantlab/backtest/engine.py`](https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/backtest/engine.py) (Backtest engine), [`src/quantlab/paper_oms/service.py`](https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/paper_oms/service.py) (Paper OMS)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Desktop workflow"]
  node_desktop["Desktop app<br/>[bootstrap.py]"]
  node_pipeline["Research pipeline"]
end

subgraph group_data["Data foundation"]
  node_domain["Market and research types<br/>[models.py]"]
  node_fabric[("PIT data fabric<br/>[store.py]")]
  node_ingest["Data ingestion<br/>[ingest.py]"]
  node_integrity["Integrity and validation<br/>[integrity.py]"]
end

subgraph group_research["Research engines"]
  node_features["Feature engine<br/>[engine.py]"]
  node_regimes["Regime engine<br/>[engine.py]"]
  node_alpha["Alpha and labels<br/>[definition.py]"]
  node_learning["Statistical learning<br/>[engine.py]"]
  node_adaptive["Adaptive alpha<br/>[engine.py]"]
  node_ensemble["Ensemble engine<br/>[engine.py]"]
  node_discovery["Alpha discovery<br/>[search.py]"]
  node_orchestration["Research control<br/>[orchestrator.py]"]
  node_backtest["Backtest engine<br/>[engine.py]"]
end

subgraph group_decision["Portfolio and controls"]
  node_portfolio["Portfolio construction<br/>[construction.py]"]
  node_capital["Capital allocation<br/>[definitions.py]"]
  node_certification["Certification gates<br/>[service.py]"]
  node_safety{{"Safety gateway<br/>[service.py]"}}
end

subgraph group_execution["Execution and oversight"]
  node_paperoms["Paper OMS<br/>[service.py]"]
  node_broker["Read-only broker gateway<br/>[service.py]"]
  node_shadow["Digital twin and shadow<br/>[service.py]"]
  node_monitoring["Monitoring and attribution<br/>[service.py]"]
  node_knowledge[("Research knowledge graph<br/>[ingest.py]")]
  node_ops["Live operations<br/>[service.py]"]
end

node_user(("Researcher"))

node_user -->|"uses"| node_desktop
node_desktop -->|"presents stages"| node_pipeline
node_ingest -->|"materializes data"| node_fabric
node_fabric -.->|"supplies PIT data"| node_integrity
node_integrity -.->|"gates research"| node_features
node_features -.->|"builds signals"| node_alpha
node_features -->|"computes panels"| node_adaptive
node_regimes -->|"provides regimes"| node_adaptive
node_alpha -.->|"combines signals"| node_ensemble
node_features -->|"provides features"| node_ensemble
node_discovery -.->|"records hypotheses"| node_orchestration
node_orchestration -.->|"coordinates engines"| node_backtest
node_backtest -->|"constructs targets"| node_portfolio
node_portfolio -.->|"feeds allocation"| node_capital
node_capital -.->|"submits for promotion"| node_certification
node_certification -.->|"gates live boundary"| node_safety
node_safety -.->|"authorizes controlled execution"| node_paperoms
node_paperoms -.->|"feeds attribution"| node_monitoring
node_broker -.->|"supports reconciliation"| node_shadow
node_paperoms -->|"simulates shadow cycles"| node_shadow
node_monitoring -.->|"feeds research memory"| node_knowledge
node_ops -.->|"observes live health"| node_shadow
node_fabric -->|"uses market types"| node_domain
node_backtest -->|"consumes bars"| node_domain

click node_desktop "https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/app/bootstrap.py"
click node_pipeline "https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/app/research_pipeline.py"
click node_domain "https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/domain/models.py"
click node_fabric "https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/data/fabric/store.py"
click node_ingest "https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/data/fabric/ingest.py"
click node_integrity "https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/research/integrity.py"
click node_features "https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/features/engine.py"
click node_regimes "https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/regimes/engine.py"
click node_alpha "https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/alpha/definition.py"
click node_learning "https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/learning/engine.py"
click node_adaptive "https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/adaptive/engine.py"
click node_ensemble "https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/ensemble/engine.py"
click node_discovery "https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/discovery/search.py"
click node_orchestration "https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/orchestration/orchestrator.py"
click node_backtest "https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/backtest/engine.py"
click node_portfolio "https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/portfolio/construction.py"
click node_capital "https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/capital/definitions.py"
click node_certification "https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/certification/service.py"
click node_safety "https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/execution_authorization/service.py"
click node_paperoms "https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/paper_oms/service.py"
click node_broker "https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/broker_gateway/service.py"
click node_shadow "https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/shadow/service.py"
click node_monitoring "https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/monitoring/service.py"
click node_knowledge "https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/knowledge/ingest.py"
click node_ops "https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/live_ops/service.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_desktop,node_pipeline toneBlue
class node_domain,node_fabric,node_ingest,node_integrity toneAmber
class node_features,node_regimes,node_alpha,node_learning,node_adaptive,node_ensemble,node_discovery,node_orchestration,node_backtest toneMint
class node_portfolio,node_capital,node_certification,node_safety toneRose
class node_paperoms,node_broker,node_shadow,node_monitoring,node_knowledge,node_ops,node_user toneIndigo
```

## Components

### Desktop workflow

- [Desktop app](https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/app/bootstrap.py): `src/quantlab/app/bootstrap.py`
- [Research pipeline](https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/app/research_pipeline.py): `src/quantlab/app/research_pipeline.py`

### Data foundation

- [Market and research types](https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/domain/models.py): `src/quantlab/domain/models.py`
- [PIT data fabric](https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/data/fabric/store.py): `src/quantlab/data/fabric/store.py`
- [Data ingestion](https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/data/fabric/ingest.py): `src/quantlab/data/fabric/ingest.py`
- [Integrity and validation](https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/research/integrity.py): `src/quantlab/research/integrity.py`

### Research engines

- [Feature engine](https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/features/engine.py): `src/quantlab/features/engine.py`
- [Regime engine](https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/regimes/engine.py): `src/quantlab/regimes/engine.py`
- [Alpha and labels](https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/alpha/definition.py): `src/quantlab/alpha/definition.py`
- [Statistical learning](https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/learning/engine.py): `src/quantlab/learning/engine.py`
- [Adaptive alpha](https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/adaptive/engine.py): `src/quantlab/adaptive/engine.py`
- [Ensemble engine](https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/ensemble/engine.py): `src/quantlab/ensemble/engine.py`
- [Alpha discovery](https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/discovery/search.py): `src/quantlab/discovery/search.py`
- [Research control](https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/orchestration/orchestrator.py): `src/quantlab/orchestration/orchestrator.py`
- [Backtest engine](https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/backtest/engine.py): `src/quantlab/backtest/engine.py`

### Portfolio and controls

- [Portfolio construction](https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/portfolio/construction.py): `src/quantlab/portfolio/construction.py`
- [Capital allocation](https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/capital/definitions.py): `src/quantlab/capital/definitions.py`
- [Certification gates](https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/certification/service.py): `src/quantlab/certification/service.py`
- [Safety gateway](https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/execution_authorization/service.py): `src/quantlab/execution_authorization/service.py`

### Execution and oversight

- [Paper OMS](https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/paper_oms/service.py): `src/quantlab/paper_oms/service.py`
- [Read-only broker gateway](https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/broker_gateway/service.py): `src/quantlab/broker_gateway/service.py`
- [Digital twin and shadow](https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/shadow/service.py): `src/quantlab/shadow/service.py`
- [Monitoring and attribution](https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/monitoring/service.py): `src/quantlab/monitoring/service.py`
- [Research knowledge graph](https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/knowledge/ingest.py): `src/quantlab/knowledge/ingest.py`
- [Live operations](https://github.com/trishul4kumar-ui/nayak-quant-lab/blob/main/src/quantlab/live_ops/service.py): `src/quantlab/live_ops/service.py`

### Other components

- **Researcher**

## Connections

- Researcher → Desktop app: uses
- Desktop app → Research pipeline: presents stages (evidence: `src/quantlab/app/research_pipeline.py`)
- Data ingestion → PIT data fabric: materializes data (evidence: `src/quantlab/data/fabric/ingest.py`)
- PIT data fabric → Integrity and validation: supplies PIT data
- Integrity and validation → Feature engine: gates research
- Feature engine → Alpha and labels: builds signals
- Feature engine → Adaptive alpha: computes panels (evidence: `src/quantlab/adaptive/engine.py`)
- Regime engine → Adaptive alpha: provides regimes (evidence: `src/quantlab/adaptive/engine.py`)
- Alpha and labels → Ensemble engine: combines signals
- Feature engine → Ensemble engine: provides features (evidence: `src/quantlab/ensemble/engine.py`)
- Alpha discovery → Research control: records hypotheses
- Research control → Backtest engine: coordinates engines
- Backtest engine → Portfolio construction: constructs targets (evidence: `src/quantlab/backtest/engine.py`)
- Portfolio construction → Capital allocation: feeds allocation
- Capital allocation → Certification gates: submits for promotion
- Certification gates → Safety gateway: gates live boundary
- Safety gateway → Paper OMS: authorizes controlled execution
- Paper OMS → Monitoring and attribution: feeds attribution
- Read-only broker gateway → Digital twin and shadow: supports reconciliation
- Paper OMS → Digital twin and shadow: simulates shadow cycles (evidence: `src/quantlab/shadow/service.py`)
- Monitoring and attribution → Research knowledge graph: feeds research memory
- Live operations → Digital twin and shadow: observes live health
- PIT data fabric → Market and research types: uses market types (evidence: `src/quantlab/data/fabric/ingest.py`)
- Backtest engine → Market and research types: consumes bars (evidence: `src/quantlab/backtest/engine.py`)