# linzecolin/eva_os architecture

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

- Interactive diagram: https://gitdiagram.com/linzecolin/eva_os
- Repository: https://github.com/linzecolin/eva_os

## Overview

1. **Repository role and top-level shape**
   - This is a macOS-first quantitative research workspace called **EVA_OS**, with **QuantLab** as the core research/backtesting engine.
   - The architecture is split into three clear layers:
     - **User entrypoints**: macOS app launcher, shell scripts, Streamlit/dashboard UI.
     - **Domain services**: Python package under `src/quantlab`.
     - **Persistent evidence/artifacts**: `data/` plus exported reports in the downloads folder.
   - The system is explicitly **research-only**: no live trading, no real order placement, and no brokerage passwords.

2. **Primary runtime entrypoints**
   - The repo supports multiple ways to start the same workspace:
     - `macos/EVA_OS.app` and the `.command` files for macOS desktop launch.
     - `scripts/startQuantLab.sh`, `statusQuantLab.sh`, `stopQuantLab.sh`, and related orchestration scripts.
     - Streamlit-style app code under `src/quantlab/app/`.
   - The macOS launcher opens the browser, while the terminal scripts allow headless or operational use.

3. **Application/UI layer**
   - The UI is concentrated in `src/quantlab/app/` and the example entrypoints in `src/quantlab/examples/`.
   - The visible workspace is a multi-tool research console, not a single-purpose app:
     - system health / readiness
     - single-symbol backtesting
     - parameter scans
     - report center
     - holdings
     - sentiment / hotspot analysis
     - policy radar
     - validation task workflows
   - The UI is mainly a thin orchestration and visualization layer over the domain modules.

4. **Core research engine**
   - `src/quantlab/backtest/`, `src/quantlab/strategies/`, `src/quantlab/indicators/`, and `src/quantlab/risk/` form the research computation core.
   - Strategies are organized by family:
     - trend
     - momentum
     - mean reversion
     - behavioral
     - custom builder-generated strategies
   - Backtesting produces portfolio metrics, risk-adjusted outputs, and diagnostic comparisons against buy-and-hold.
   - Indicator and risk modules are shared across strategy research, parameter scans, and report generation.

5. **Data ingestion and normalization boundary**
   - `src/quantlab/data/` is the main boundary between external data and internal research objects.
   - It includes:
     - provider adapters (`providers/`) for Moomoo, Yahoo Finance, Alpha Vantage, Polygon, Tushare, Akshare, CSV, and sample data
     - storage and lake management
     - cleaner, quality, validation, replay, symbol search, and universe logic
   - The architecture deliberately isolates provider differences behind a common interface so analysis/backtests consume normalized market data rather than provider-specific formats.

6. **Real-data sources and provider gating**
   - The repo treats **Moomoo OpenD** as the preferred real-quote entry point, but only for market data.
   - `data/provider_status.py`, `data/moomoo_diagnostics.py`, and validation scripts enforce whether a source is usable, configured, or needs review.
   - This is important architecturally because provider availability affects:
     - which data can enter the lake
     - whether cross-source validation passes
     - whether results are allowed to be treated as evidence

7. **Research evidence and report generation**
   - `src/quantlab/reports/` and `data/reportDecision/` implement the evidence-centric reporting layer.
   - Reports are not just charts; they carry lineage and quality metadata:
     - data quality status
     - cross-source validation status
     - entity status
     - workflow lineage
     - cost assumptions
     - risk gate state
     - decision quality status
   - Exported artifacts are written as Word/JSON/CSV/PDF-style outputs, which makes the report center a durable evidence store rather than a transient UI page.

8. **Research bus as the integration backbone**
   - `src/quantlab/integrations/research_bus.py`, `research_bus_api.py`, `research_bus_audit.py`, and `system_orchestrator.py` connect QuantLab to the broader EVA ecosystem.
   - The shared bus is persisted in `data/researchBus/ResearchBus.sqlite` with snapshot files under the same directory.
   - It carries:
     - chat/API requests
     - outbox messages
     - heartbeats
     - report indexes
     - validation tasks
     - holdings state
     - independent validation state
   - This makes the architecture event-and-evidence driven across subsystems, not just a local app with files.

9. **Validation and evidence triage subsystem**
   - `src/quantlab/research/`, `src/quantlab/validation`, `src/quantlab/reports/decision_support.py`, and `src/quantlab/system/` implement the “what should be trusted?” layer.
   - Key concepts include:
     - validation queue and priority planning
     - independent validation execution
     - cross-source validation
     - decision quality scoring
     - research risk gates
   - A major boundary is that missing or weak evidence does **not** get promoted to a strong conclusion; it is downgraded to watch-only or needs-more-evidence states.

10. **Holdings, entities, and portfolio-related state**
   - Holdings are handled via `src/quantlab/integrations/holdings_book.py`, `holding_symbol_map.py`, and entity registry outputs in `data/entityRegistry/`.
   - The repo distinguishes:
     - confirmed holdings
     - pending imports / pending review
     - proxy-mapped symbols
     - missing symbols
   - This boundary matters because holdings are used in analysis and personal profiling, but only confirmed, valid objects are allowed to flow into backtests and downstream evidence.

11. **System health, readiness, and governance**
   - `src/quantlab/system/` and `src/quantlab/consumption/` implement operational governance rather than trading logic.
   - The system produces readiness, integration, trust, and shutdown-monitor artifacts.
   - Governance artifacts live in `data/systemAudit/`, `data/consumption/`, `data/approvals/`, `data/policy/`, and `data/value/`.
   - These modules ensure the workspace knows whether it is operationally safe and whether conclusions are sufficiently justified.

12. **Scripts, automation, and macOS operations**
   - The `scripts/` directory is effectively the operational control plane.
   - It contains:
     - startup/shutdown/status commands
     - daily checks
     - data lake manifest generation
     - event replay
     - research bus sync and webhook tooling
     - validation task execution
     - integration audits
     - report generation and cleanup
   - This means the repo is designed for both interactive use and repeatable batch workflows, with scripts acting as stable orchestration boundaries.

13. **Persistence model and artifact layout**
   - The repo persists most important outputs as files under `data/` rather than a remote database service.
   - Important storage zones include:
     - `data/raw`, `processed`, `cache`, `results`
     - `data/holdings`
     - `data/marketEvents`
     - `data/dataLake`
     - `data/replay`
     - `data/reportDecision`
     - `data/validationQueue`
     - `data/researchBus`
   - The architecture is therefore file-centric and audit-friendly: every major workflow leaves an inspectable artifact trail.

14. **How data flows through the system**
   - The typical flow is:
     1. provider or imported input enters the data layer
     2. normalization/quality checks filter and classify it
     3. analysis or backtest consumes the validated data
     4. reports and metadata are exported
     5. evidence is synced into the research bus and system audits
     6. gaps become validation tasks rather than assumptions
   - This flow is repeated across market analysis, holdings, policy, consumption, and independent validation, which is why the architecture feels like a coordinated research operations platform rather than a single analytics app.

15. **Key architectural constraint**
   - The most important boundary in this repo is **evidence integrity**:
     - no live trading
     - no silent promotion of weak data
     - no overwriting valid holdings with empty or broken imports
     - no claiming validation success when providers or data coverage are insufficient
   - Any diagram should show this as a cross-cutting governance layer spanning data ingestion, analysis, reporting, and synchronization.

Main entry points: [`src/quantlab/integrations/research_bus.py`](https://github.com/linzecolin/eva_os/blob/main/src/quantlab/integrations/research_bus.py) (Research Bus), [`src/quantlab/app`](https://github.com/linzecolin/eva_os/tree/main/src/quantlab/app) (Research UI), [`src/quantlab/backtest`](https://github.com/linzecolin/eva_os/tree/main/src/quantlab/backtest) (Backtest Engine), [`src/quantlab/reports`](https://github.com/linzecolin/eva_os/tree/main/src/quantlab/reports) (Reports)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entrypoints["Entrypoints"]
  node_macos_launcher["macOS App<br/>launcher<br/>[EVA_OS.app]"]
  node_scripts_ops["Ops Scripts<br/>orchestration scripts"]
  node_streamlit_ui["Research UI"]
  node_examples_entry["Example Entrypoints<br/>cli wrappers"]
end

subgraph group_core["Research Core"]
  node_backtest_core["Backtest Engine<br/>research engine"]
  node_strategies_core["Strategies<br/>strategy library"]
  node_indicators_core(("Indicators<br/>signal library"))
  node_risk_core{{"Risk Controls<br/>risk logic"}}
  node_analysis_core["Analysis<br/>analytics"]
end

subgraph group_data["Data Boundary"]
  node_data_ingest[("Data Layer<br/>market data boundary")]
  node_providers["Providers<br/>adapters"]
  node_quality_gate{{"Quality Gate<br/>validation<br/>[quality.py]"}}
  node_provider_status(("Provider Status<br/>gating<br/>[provider_status.py]"))
  node_storage_lake[("Data Lake<br/>persistence<br/>[lake.py]")]
end

subgraph group_governance["Governance"]
  node_reporting["Reports<br/>evidence export"]
  node_decision_support{{"Decision Support<br/>evidence triage"}}
  node_validation_flow["Validation Flow<br/>review workflow"]
  node_system_governance["System Governance<br/>trust and readiness"]
end

subgraph group_bus["Research Bus"]
  node_research_bus[("Research Bus<br/>integration backbone<br/>[research_bus.py]")]
  node_holdings_state["Holdings State<br/>portfolio state<br/>[holdings_book.py]"]
  node_orchestrator["System Orchestrator<br/>coordination"]
end

node_macos_launcher -->|"opens"| node_streamlit_ui
node_scripts_ops -->|"starts"| node_streamlit_ui
node_scripts_ops -->|"orchestrates"| node_orchestrator
node_examples_entry -->|"runs"| node_backtest_core
node_examples_entry -->|"runs"| node_validation_flow
node_streamlit_ui -->|"shows"| node_analysis_core
node_streamlit_ui -->|"renders"| node_reporting
node_streamlit_ui -->|"queues"| node_validation_flow
node_data_ingest -->|"adapts"| node_providers
node_data_ingest -->|"normalizes"| node_quality_gate
node_provider_status -->|"gates"| node_data_ingest
node_quality_gate -->|"persists"| node_storage_lake
node_storage_lake -->|"feeds"| node_backtest_core
node_indicators_core -->|"supports"| node_strategies_core
node_strategies_core -->|"executes"| node_backtest_core
node_risk_core -->|"constrains"| node_backtest_core
node_analysis_core -->|"summarizes"| node_reporting
node_backtest_core -->|"exports"| node_reporting
node_reporting -->|"indexes"| node_decision_support
node_decision_support -->|"spawns"| node_validation_flow
node_validation_flow -->|"confirms"| node_system_governance
node_system_governance -->|"publishes"| node_research_bus
node_holdings_state -->|"syncs"| node_research_bus
node_orchestrator -->|"coordinates"| node_research_bus
node_research_bus -->|"routes"| node_validation_flow
node_research_bus -->|"indexes"| node_reporting
node_research_bus -->|"carries"| node_holdings_state
node_data_ingest -->|"syncs"| node_research_bus

click node_macos_launcher "https://github.com/linzecolin/eva_os/blob/main/macos/EVA_OS.app"
click node_scripts_ops "https://github.com/linzecolin/eva_os/tree/main/scripts"
click node_streamlit_ui "https://github.com/linzecolin/eva_os/tree/main/src/quantlab/app"
click node_examples_entry "https://github.com/linzecolin/eva_os/tree/main/src/quantlab/examples"
click node_backtest_core "https://github.com/linzecolin/eva_os/tree/main/src/quantlab/backtest"
click node_strategies_core "https://github.com/linzecolin/eva_os/tree/main/src/quantlab/strategies"
click node_indicators_core "https://github.com/linzecolin/eva_os/tree/main/src/quantlab/indicators"
click node_risk_core "https://github.com/linzecolin/eva_os/tree/main/src/quantlab/risk"
click node_analysis_core "https://github.com/linzecolin/eva_os/tree/main/src/quantlab/analysis"
click node_data_ingest "https://github.com/linzecolin/eva_os/tree/main/src/quantlab/data"
click node_providers "https://github.com/linzecolin/eva_os/tree/main/src/quantlab/data/providers"
click node_quality_gate "https://github.com/linzecolin/eva_os/blob/main/src/quantlab/data/quality.py"
click node_provider_status "https://github.com/linzecolin/eva_os/blob/main/src/quantlab/data/provider_status.py"
click node_storage_lake "https://github.com/linzecolin/eva_os/blob/main/src/quantlab/data/lake.py"
click node_reporting "https://github.com/linzecolin/eva_os/tree/main/src/quantlab/reports"
click node_decision_support "https://github.com/linzecolin/eva_os/blob/main/src/quantlab/reports/decision_support.py"
click node_validation_flow "https://github.com/linzecolin/eva_os/tree/main/src/quantlab/research"
click node_system_governance "https://github.com/linzecolin/eva_os/tree/main/src/quantlab/system"
click node_research_bus "https://github.com/linzecolin/eva_os/blob/main/src/quantlab/integrations/research_bus.py"
click node_holdings_state "https://github.com/linzecolin/eva_os/blob/main/src/quantlab/integrations/holdings_book.py"
click node_orchestrator "https://github.com/linzecolin/eva_os/blob/main/src/quantlab/integrations/system_orchestrator.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_macos_launcher,node_scripts_ops,node_streamlit_ui,node_examples_entry toneBlue
class node_backtest_core,node_strategies_core,node_indicators_core,node_risk_core,node_analysis_core toneAmber
class node_data_ingest,node_providers,node_quality_gate,node_provider_status,node_storage_lake toneMint
class node_reporting,node_decision_support,node_validation_flow,node_system_governance toneRose
class node_research_bus,node_holdings_state,node_orchestrator toneIndigo
```

## Components

### Entrypoints

macOS launchers, shell scripts, and UI surfaces

- [macOS App](https://github.com/linzecolin/eva_os/blob/main/macos/EVA_OS.app): launcher · Desktop entrypoint for EVA_OS on macOS · `macos/EVA_OS.app`
- [Ops Scripts](https://github.com/linzecolin/eva_os/tree/main/scripts): orchestration scripts · Startup, status, sync, validation, and maintenance automation · `scripts`
- [Research UI](https://github.com/linzecolin/eva_os/tree/main/src/quantlab/app): ui · Streamlit/dashboard research console and app shell · `src/quantlab/app`
- [Example Entrypoints](https://github.com/linzecolin/eva_os/tree/main/src/quantlab/examples): cli wrappers · Command-style examples that expose major workflows · `src/quantlab/examples`

### Research Core

Backtesting, strategies, indicators, and risk logic

- [Backtest Engine](https://github.com/linzecolin/eva_os/tree/main/src/quantlab/backtest): research engine · Runs portfolio simulations and comparative backtests · `src/quantlab/backtest`
- [Strategies](https://github.com/linzecolin/eva_os/tree/main/src/quantlab/strategies): strategy library · Trend, momentum, mean reversion, behavioral, and custom strategies · `src/quantlab/strategies`
- [Indicators](https://github.com/linzecolin/eva_os/tree/main/src/quantlab/indicators): signal library · Shared technical indicators used by analysis and strategies · `src/quantlab/indicators`
- [Risk Controls](https://github.com/linzecolin/eva_os/tree/main/src/quantlab/risk): risk logic · Position sizing, gates, and decision-quality scoring · `src/quantlab/risk`
- [Analysis](https://github.com/linzecolin/eva_os/tree/main/src/quantlab/analysis): analytics · Portfolio, sentiment, hotspots, comparison, and diagnostics · `src/quantlab/analysis`

### Data Boundary

Ingestion, normalization, provider gating, and persistence

- [Data Layer](https://github.com/linzecolin/eva_os/tree/main/src/quantlab/data): market data boundary · Normalization boundary between external providers and internal research objects · `src/quantlab/data`
- [Providers](https://github.com/linzecolin/eva_os/tree/main/src/quantlab/data/providers): adapters · Moomoo, Yahoo Finance, Alpha Vantage, Polygon, Tushare, Akshare, CSV, sample · `src/quantlab/data/providers`
- [Quality Gate](https://github.com/linzecolin/eva_os/blob/main/src/quantlab/data/quality.py): validation · Cleaner, quality, validation, replay, symbol search, and universe rules · `src/quantlab/data/quality.py`
- [Provider Status](https://github.com/linzecolin/eva_os/blob/main/src/quantlab/data/provider_status.py): gating · Usability, configuration, and review state for data sources · `src/quantlab/data/provider_status.py`
- [Data Lake](https://github.com/linzecolin/eva_os/blob/main/src/quantlab/data/lake.py): persistence · File-centric storage and lake management for research artifacts · `src/quantlab/data/lake.py`

### Governance

Validation, trust, readiness, and decision support

- [Reports](https://github.com/linzecolin/eva_os/tree/main/src/quantlab/reports): evidence export · Catalog, export, and decision-support reporting layer · `src/quantlab/reports`
- [Decision Support](https://github.com/linzecolin/eva_os/blob/main/src/quantlab/reports/decision_support.py): evidence triage · Report lineage, evidence gaps, and quality-aware recommendation support · `src/quantlab/reports/decision_support.py`
- [Validation Flow](https://github.com/linzecolin/eva_os/tree/main/src/quantlab/research): review workflow · Validation queue, execution, and independent validation workflows · `src/quantlab/research`
- [System Governance](https://github.com/linzecolin/eva_os/tree/main/src/quantlab/system): trust and readiness · Daily readiness, data trust, health, integration audit, shutdown monitoring · `src/quantlab/system`

### Research Bus

Shared integration backbone and cross-system state

- [Research Bus](https://github.com/linzecolin/eva_os/blob/main/src/quantlab/integrations/research_bus.py): integration backbone · Shared bus for chat requests, outbox messages, heartbeats, reports, holdings, and validation state · `src/quantlab/integrations/research_bus.py`
- [Holdings State](https://github.com/linzecolin/eva_os/blob/main/src/quantlab/integrations/holdings_book.py): portfolio state · Holdings book, symbol mapping, and entity registry flow · `src/quantlab/integrations/holdings_book.py`
- [System Orchestrator](https://github.com/linzecolin/eva_os/blob/main/src/quantlab/integrations/system_orchestrator.py): coordination · Connects QuantLab subsystems into broader EVA workflows · `src/quantlab/integrations/system_orchestrator.py`

## Connections

- macOS App → Research UI: opens · Desktop launch starts the workspace UI
- Ops Scripts → Research UI: starts · Shell scripts launch the research console
- Ops Scripts → System Orchestrator: orchestrates · Operational scripts drive system coordination workflows
- Example Entrypoints → Backtest Engine: runs · Example entrypoints expose research workflows
- Example Entrypoints → Validation Flow: runs · Examples trigger validation and review workflows
- Research UI → Analysis: shows · UI surfaces analytics and diagnostic views
- Research UI → Reports: renders · UI presents report center and evidence views
- Research UI → Validation Flow: queues · UI can surface tasks and validation workflows
- Data Layer → Providers: adapts · Provider adapters feed the common data boundary
- Data Layer → Quality Gate: normalizes · Incoming data is cleaned and validated
- Provider Status → Data Layer: gates · Provider availability controls what can enter the lake
- Quality Gate → Data Lake: persists · Validated data is stored as durable research artifacts
- Data Lake → Backtest Engine: feeds · Backtests consume normalized, validated market data
- Indicators → Strategies: supports · Strategies reuse shared indicator calculations
- Strategies → Backtest Engine: executes · Strategies are evaluated by the backtest engine
- Risk Controls → Backtest Engine: constrains · Risk gates and sizing shape research outputs
- Analysis → Reports: summarizes · Analysis output becomes report content and diagnostics
- Backtest Engine → Reports: exports · Backtest results are turned into evidence reports
- Reports → Decision Support: indexes · Reports carry lineage and evidence metadata
- Decision Support → Validation Flow: spawns · Evidence gaps become validation tasks rather than assumptions
- Validation Flow → System Governance: confirms · Validation results inform readiness and trust posture
- System Governance → Research Bus: publishes · Governance artifacts are synced to the shared bus
- Holdings State → Research Bus: syncs · Holdings and entity state are shared through the bus
- System Orchestrator → Research Bus: coordinates · The orchestrator uses the bus as the integration backbone
- Research Bus → Validation Flow: routes · Validation tasks and state move across the bus
- Research Bus → Reports: indexes · Report indexes and artifacts are published to the bus
- Research Bus → Holdings State: carries · Holdings state and symbol mappings are distributed
- Data Layer → Research Bus: syncs · Data and evidence can be mirrored into the shared bus