# ling5477/nexus-quant architecture

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

## Overview

NexusQuant is a quantitative-trading platform with market-data ingestion, strategy research and validation, paper/shadow evidence, exchange adapters, and operator-facing monitoring. A representative user workflow is to ingest historical market data, inspect strategy runs and validation evidence, then review paper/shadow consistency and operational incidents. The README explicitly limits live-trading authority: shadow trading is not enabled, and the historical OKX pilot does not authorize general live trading. The graph combines sampled service behavior with subsystem names evident in the tree; wiring for unsampled modules is intentionally omitted.

Main entry points: [`backend/nq-core/src/main/java/com/guidinglight/nexusquant/strategy/application/validationoperations/runtimeevidence/ValidationOperationsRuntimeEvidenceOverviewQueryService.java`](https://github.com/ling5477/nexus-quant/blob/dev/backend/nq-core/src/main/java/com/guidinglight/nexusquant/strategy/application/validationoperations/runtimeevidence/ValidationOperationsRuntimeEvidenceOverviewQueryService.java) (Runtime evidence), [`backend/nq-core/src/main/java/com/guidinglight/nexusquant/marketdata/application/service/MarketdataIngestionService.java`](https://github.com/ling5477/nexus-quant/blob/dev/backend/nq-core/src/main/java/com/guidinglight/nexusquant/marketdata/application/service/MarketdataIngestionService.java) (Ingestion service), [`backend/nq-api/src/main/java/com/guidinglight/nexusquant/marketdata/api/web/MarketdataController.java`](https://github.com/ling5477/nexus-quant/blob/dev/backend/nq-api/src/main/java/com/guidinglight/nexusquant/marketdata/api/web/MarketdataController.java) (REST API), [`backend/nq-adapter-binance/src/main/java/com/guidinglight/nexusquant/adapter/binance/marketdata/BinanceHistoricalKlineAdapter.java`](https://github.com/ling5477/nexus-quant/blob/dev/backend/nq-adapter-binance/src/main/java/com/guidinglight/nexusquant/adapter/binance/marketdata/BinanceHistoricalKlineAdapter.java) (Binance adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["API and accounts"]
  node_api["REST API"]
  node_accounts["Exchange accounts"]
end

subgraph group_market["Market data"]
  node_market_service["Ingestion service"]
  node_market_api["Catalog and quality"]
end

subgraph group_research["Research and validation"]
  node_strategy_runs["Strategy run queries"]
  node_backtest["Backtest facts"]
  node_validation["Strategy validation"]
  node_shadow["Shadow workflow"]
  node_consistency["Consistency evidence"]
  node_drilldown["Shadow drilldown"]
end

subgraph group_operations["Operations evidence"]
  node_runtime_evidence["Runtime evidence"]
  node_incidents["Incident overview"]
  node_incident_review["Incident review"]
  node_artifact_preview["Artifact preview"]
  node_pilot_control["Pilot control"]
end

subgraph group_exchange["Exchange adapters"]
  node_binance["Binance adapter"]
  node_okx["OKX adapter"]
end

node_user(("Platform user"))
node_venues{{"Exchange venues"}}

node_user -->|"requests"| node_api
node_user -->|"manages"| node_accounts
node_api -->|"creates and queries"| node_market_service
node_market_service -->|"fetches bars"| node_binance
node_market_service -->|"fetches bars"| node_okx
node_binance -->|"market data"| node_venues
node_okx -->|"market data"| node_venues
node_user -->|"reviews catalog"| node_market_api
node_user -->|"queries runs"| node_strategy_runs
node_user -->|"queries backtests"| node_backtest
node_user -->|"reviews evidence"| node_validation
node_user -->|"reviews workflow"| node_shadow
node_user -->|"inspects run"| node_drilldown
node_user -->|"reviews incidents"| node_incidents
node_user -->|"reviews findings"| node_incident_review
node_user -->|"previews artifact"| node_artifact_preview
node_user -->|"controls pilot scope"| node_pilot_control
node_runtime_evidence -->|"loads evidence"| node_shadow
node_runtime_evidence -->|"loads evidence"| node_consistency
node_runtime_evidence -->|"loads evidence"| node_incident_review
node_runtime_evidence -->|"loads evidence"| node_artifact_preview

click node_api "https://github.com/ling5477/nexus-quant/blob/dev/backend/nq-api/src/main/java/com/guidinglight/nexusquant/marketdata/api/web/MarketdataController.java"
click node_accounts "https://github.com/ling5477/nexus-quant/blob/dev/backend/nq-core/src/main/java/com/guidinglight/nexusquant/account/application/service/ExchangeAccountQueryService.java"
click node_market_service "https://github.com/ling5477/nexus-quant/blob/dev/backend/nq-core/src/main/java/com/guidinglight/nexusquant/marketdata/application/service/MarketdataIngestionService.java"
click node_market_api "https://github.com/ling5477/nexus-quant/blob/dev/backend/nq-api/src/main/java/com/guidinglight/nexusquant/marketdata/api/web/InstrumentCatalogController.java"
click node_binance "https://github.com/ling5477/nexus-quant/blob/dev/backend/nq-adapter-binance/src/main/java/com/guidinglight/nexusquant/adapter/binance/marketdata/BinanceHistoricalKlineAdapter.java"
click node_okx "https://github.com/ling5477/nexus-quant/blob/dev/backend/nq-adapter-okx/src/main/java/com/guidinglight/nexusquant/adapter/okx/marketdata/OkxHistoricalKlineAdapter.java"
click node_strategy_runs "https://github.com/ling5477/nexus-quant/blob/dev/backend/nq-core/src/main/java/com/guidinglight/nexusquant/strategy/application/StrategyRunQueryService.java"
click node_backtest "https://github.com/ling5477/nexus-quant/blob/dev/backend/nq-backtest/src/main/java/com/guidinglight/nexusquant/research/application/backtest/BacktestFactQueryService.java"
click node_validation "https://github.com/ling5477/nexus-quant/blob/dev/backend/nq-core/src/main/java/com/guidinglight/nexusquant/strategy/application/evaluationgate/service/StrategyValidationOverviewQueryService.java"
click node_shadow "https://github.com/ling5477/nexus-quant/blob/dev/backend/nq-core/src/main/java/com/guidinglight/nexusquant/strategy/application/shadowvalidation/service/ShadowValidationWorkflowOverviewQueryService.java"
click node_consistency "https://github.com/ling5477/nexus-quant/blob/dev/backend/nq-core/src/main/java/com/guidinglight/nexusquant/strategy/application/consistencyevidence/service/ConsistencyEvidenceOverviewQueryService.java"
click node_drilldown "https://github.com/ling5477/nexus-quant/blob/dev/backend/nq-core/src/main/java/com/guidinglight/nexusquant/strategy/application/shadowrun/service/PaperShadowConsistencyDrilldownQueryService.java"
click node_runtime_evidence "https://github.com/ling5477/nexus-quant/blob/dev/backend/nq-core/src/main/java/com/guidinglight/nexusquant/strategy/application/validationoperations/runtimeevidence/ValidationOperationsRuntimeEvidenceOverviewQueryService.java"
click node_incidents "https://github.com/ling5477/nexus-quant/blob/dev/backend/nq-core/src/main/java/com/guidinglight/nexusquant/monitoring/application/incident/IncidentReplayOverviewQueryService.java"
click node_incident_review "https://github.com/ling5477/nexus-quant/blob/dev/backend/nq-core/src/main/java/com/guidinglight/nexusquant/monitoring/application/incidentreview/service/IncidentReplayReviewOverviewQueryService.java"
click node_artifact_preview "https://github.com/ling5477/nexus-quant/blob/dev/backend/nq-core/src/main/java/com/guidinglight/nexusquant/strategy/application/pyartifactpreview/service/PythonEvaluationArtifactPreviewOverviewQueryService.java"
click node_pilot_control "https://github.com/ling5477/nexus-quant/blob/dev/backend/nq-api/src/main/java/com/guidinglight/nexusquant/livecontrol/api/PilotScopeControlPlaneController.java"

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_api,node_accounts,node_user toneBlue
class node_market_service,node_market_api toneAmber
class node_strategy_runs,node_backtest,node_validation,node_shadow,node_consistency,node_drilldown toneMint
class node_runtime_evidence,node_incidents,node_incident_review,node_artifact_preview,node_pilot_control toneRose
class node_binance,node_okx,node_venues toneIndigo
```

## Components

### API and accounts

- [REST API](https://github.com/ling5477/nexus-quant/blob/dev/backend/nq-api/src/main/java/com/guidinglight/nexusquant/marketdata/api/web/MarketdataController.java): `backend/nq-api/src/main/java/com/guidinglight/nexusquant/marketdata/api/web/MarketdataController.java`
- [Exchange accounts](https://github.com/ling5477/nexus-quant/blob/dev/backend/nq-core/src/main/java/com/guidinglight/nexusquant/account/application/service/ExchangeAccountQueryService.java): `backend/nq-core/src/main/java/com/guidinglight/nexusquant/account/application/service/ExchangeAccountQueryService.java`

### Market data

- [Ingestion service](https://github.com/ling5477/nexus-quant/blob/dev/backend/nq-core/src/main/java/com/guidinglight/nexusquant/marketdata/application/service/MarketdataIngestionService.java): `backend/nq-core/src/main/java/com/guidinglight/nexusquant/marketdata/application/service/MarketdataIngestionService.java`
- [Catalog and quality](https://github.com/ling5477/nexus-quant/blob/dev/backend/nq-api/src/main/java/com/guidinglight/nexusquant/marketdata/api/web/InstrumentCatalogController.java): `backend/nq-api/src/main/java/com/guidinglight/nexusquant/marketdata/api/web/InstrumentCatalogController.java`

### Research and validation

- [Strategy run queries](https://github.com/ling5477/nexus-quant/blob/dev/backend/nq-core/src/main/java/com/guidinglight/nexusquant/strategy/application/StrategyRunQueryService.java): `backend/nq-core/src/main/java/com/guidinglight/nexusquant/strategy/application/StrategyRunQueryService.java`
- [Backtest facts](https://github.com/ling5477/nexus-quant/blob/dev/backend/nq-backtest/src/main/java/com/guidinglight/nexusquant/research/application/backtest/BacktestFactQueryService.java): `backend/nq-backtest/src/main/java/com/guidinglight/nexusquant/research/application/backtest/BacktestFactQueryService.java`
- [Strategy validation](https://github.com/ling5477/nexus-quant/blob/dev/backend/nq-core/src/main/java/com/guidinglight/nexusquant/strategy/application/evaluationgate/service/StrategyValidationOverviewQueryService.java): `backend/nq-core/src/main/java/com/guidinglight/nexusquant/strategy/application/evaluationgate/service/StrategyValidationOverviewQueryService.java`
- [Shadow workflow](https://github.com/ling5477/nexus-quant/blob/dev/backend/nq-core/src/main/java/com/guidinglight/nexusquant/strategy/application/shadowvalidation/service/ShadowValidationWorkflowOverviewQueryService.java): `backend/nq-core/src/main/java/com/guidinglight/nexusquant/strategy/application/shadowvalidation/service/ShadowValidationWorkflowOverviewQueryService.java`
- [Consistency evidence](https://github.com/ling5477/nexus-quant/blob/dev/backend/nq-core/src/main/java/com/guidinglight/nexusquant/strategy/application/consistencyevidence/service/ConsistencyEvidenceOverviewQueryService.java): `backend/nq-core/src/main/java/com/guidinglight/nexusquant/strategy/application/consistencyevidence/service/ConsistencyEvidenceOverviewQueryService.java`
- [Shadow drilldown](https://github.com/ling5477/nexus-quant/blob/dev/backend/nq-core/src/main/java/com/guidinglight/nexusquant/strategy/application/shadowrun/service/PaperShadowConsistencyDrilldownQueryService.java): `backend/nq-core/src/main/java/com/guidinglight/nexusquant/strategy/application/shadowrun/service/PaperShadowConsistencyDrilldownQueryService.java`

### Operations evidence

- [Runtime evidence](https://github.com/ling5477/nexus-quant/blob/dev/backend/nq-core/src/main/java/com/guidinglight/nexusquant/strategy/application/validationoperations/runtimeevidence/ValidationOperationsRuntimeEvidenceOverviewQueryService.java): `backend/nq-core/src/main/java/com/guidinglight/nexusquant/strategy/application/validationoperations/runtimeevidence/ValidationOperationsRuntimeEvidenceOverviewQueryService.java`
- [Incident overview](https://github.com/ling5477/nexus-quant/blob/dev/backend/nq-core/src/main/java/com/guidinglight/nexusquant/monitoring/application/incident/IncidentReplayOverviewQueryService.java): `backend/nq-core/src/main/java/com/guidinglight/nexusquant/monitoring/application/incident/IncidentReplayOverviewQueryService.java`
- [Incident review](https://github.com/ling5477/nexus-quant/blob/dev/backend/nq-core/src/main/java/com/guidinglight/nexusquant/monitoring/application/incidentreview/service/IncidentReplayReviewOverviewQueryService.java): `backend/nq-core/src/main/java/com/guidinglight/nexusquant/monitoring/application/incidentreview/service/IncidentReplayReviewOverviewQueryService.java`
- [Artifact preview](https://github.com/ling5477/nexus-quant/blob/dev/backend/nq-core/src/main/java/com/guidinglight/nexusquant/strategy/application/pyartifactpreview/service/PythonEvaluationArtifactPreviewOverviewQueryService.java): `backend/nq-core/src/main/java/com/guidinglight/nexusquant/strategy/application/pyartifactpreview/service/PythonEvaluationArtifactPreviewOverviewQueryService.java`
- [Pilot control](https://github.com/ling5477/nexus-quant/blob/dev/backend/nq-api/src/main/java/com/guidinglight/nexusquant/livecontrol/api/PilotScopeControlPlaneController.java): `backend/nq-api/src/main/java/com/guidinglight/nexusquant/livecontrol/api/PilotScopeControlPlaneController.java`

### Exchange adapters

- [Binance adapter](https://github.com/ling5477/nexus-quant/blob/dev/backend/nq-adapter-binance/src/main/java/com/guidinglight/nexusquant/adapter/binance/marketdata/BinanceHistoricalKlineAdapter.java): `backend/nq-adapter-binance/src/main/java/com/guidinglight/nexusquant/adapter/binance/marketdata/BinanceHistoricalKlineAdapter.java`
- [OKX adapter](https://github.com/ling5477/nexus-quant/blob/dev/backend/nq-adapter-okx/src/main/java/com/guidinglight/nexusquant/adapter/okx/marketdata/OkxHistoricalKlineAdapter.java): `backend/nq-adapter-okx/src/main/java/com/guidinglight/nexusquant/adapter/okx/marketdata/OkxHistoricalKlineAdapter.java`

### Other components

- **Platform user**
- **Exchange venues**

## Connections

- Platform user → REST API: requests
- Platform user → Exchange accounts: manages
- REST API → Ingestion service: creates and queries
- Ingestion service → Binance adapter: fetches bars
- Ingestion service → OKX adapter: fetches bars
- Binance adapter → Exchange venues: market data
- OKX adapter → Exchange venues: market data
- Platform user → Catalog and quality: reviews catalog
- Platform user → Strategy run queries: queries runs
- Platform user → Backtest facts: queries backtests
- Platform user → Strategy validation: reviews evidence
- Platform user → Shadow workflow: reviews workflow
- Platform user → Shadow drilldown: inspects run
- Platform user → Incident overview: reviews incidents
- Platform user → Incident review: reviews findings
- Platform user → Artifact preview: previews artifact
- Platform user → Pilot control: controls pilot scope
- Runtime evidence → Shadow workflow: loads evidence
- Runtime evidence → Consistency evidence: loads evidence
- Runtime evidence → Incident review: loads evidence
- Runtime evidence → Artifact preview: loads evidence