linzecolin/eva_os

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.