gavindiazandClaude Code
3a005ddcc6
Docs / Validate documentation (push) Canceled after 0s
Docs / Deploy GitHub Pages (push) Canceled after 0s
CI Final Summary (AI) / AI Final Summary (push) Canceled after 0s
CI Final Summary (AI) / Push/PR event feed (push) Canceled after 0s
CI / CI Integrity and Change Classification (push) Canceled after 0s
CI / Code Quality & Tests (push) Canceled after 0s
Dependency Lock & Migration Safety / Dependency drift (lock vs pyproject) (push) Canceled after 0s
Dependency Lock & Migration Safety / Migration safety (fail-loud + version postconditions) (push) Canceled after 0s
JS Tests / Frontend JS Unit Tests (push) Canceled after 0s
Security / CodeQL Analysis (push) Canceled after 0s
Security / Trivy Vulnerability Scan (push) Canceled after 0s
Tests (OS Matrix) / Py Tests (macos-latest) (push) Canceled after 0s
Tests (OS Matrix) / Py Tests (windows-latest) (push) Canceled after 0s
CI / Extended Validation (Tier 2) (push) Canceled after 0s
CI / Heavy CI (database-provider) (push) Canceled after 0s
CI / Heavy CI (e2e) (push) Canceled after 0s
CI / Heavy CI (integration) (push) Canceled after 0s
CI / Heavy CI (model-validation) (push) Canceled after 0s
CI / Heavy CI (research-backtest) (push) Canceled after 0s
CI / Aggregate CI Results (push) Canceled after 0s
Full project import for the self-hosted code hosting (https://code.aifunny.ltd/gavindiaz/my-NexusTradingForexBot.git). Includes the live-freshness + scaler-hash fixes for the permanent STALE dashboard (tick_pipeline now_utc stamps; infer_probabilities computes model_input_hash on the actual scaled 70D tensor), the data-fetch default-path fix, the g29 web-auth test fixes, and a Chinese user manual (使用手册.md) for the web dashboard. Scratch diagnostic scripts (check*.py, contain a live web-auth token) and the .kilo/ agent-worktree directory are gitignored, not committed. Co-Authored-By: Claude Code <noreply@anthropic.com>
68 lines
5.7 KiB
Markdown
68 lines
5.7 KiB
Markdown
---
|
|
title: Architecture Overview
|
|
description: Hexagonal (ports-and-adapters), event-driven architecture of Nexus Scalp Engine — layers, boundaries, and why they exist.
|
|
lang: en
|
|
---
|
|
|
|
# Architecture Overview
|
|
|
|
NSE is **hexagonal (ports-and-adapters) and event-driven**. Broker platforms,
|
|
models and network adapters are isolated behind port contracts
|
|
(`IMT5Port`, `IGatewayPort`), so the domain never knows which broker — or
|
|
whether a broker — is attached.
|
|
|
|
```text
|
|
┌──────────────────────── ports (contracts) ───────────────────────┐
|
|
│ │
|
|
Market │ ┌──────────┐ ┌──────────┐ ┌─────────┐ ┌────────┐ │
|
|
data ──┼─►│ features │──►│ model │──►│ signals │──►│ risk │ │
|
|
(MT5 / │ │ 50D/70D │ │ ScalpNet │ │ policy │ │ engine │ │
|
|
paper) │ └──────────┘ └──────────┘ └─────────┘ └───┬────┘ │
|
|
│ ▼ │
|
|
│ ┌──────────────┐ │
|
|
│ │ execution │ │
|
|
│ │ OrderManager │ │
|
|
│ └──────┬───────┘ │
|
|
▼ ▼ │
|
|
┌──────────────┐ ┌──────────────┐ ┌──────────────────────────────┐ │
|
|
│ adapters │ │ accounting │ │ application (LiveEngine) │ │
|
|
│ mt5/paper/db │ │ SQLite WAL │ │ async event loop, web │ │
|
|
└──────────────┘ └──────────────┘ └──────────────────────────────┘ │
|
|
└────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Layers
|
|
|
|
| Layer | Location | Responsibility | Hard boundary |
|
|
| :--- | :--- | :--- | :--- |
|
|
| Domain | `src/nexus_scalp/domain/` | Immutable Pydantic contracts (`TickData`, `TradeProposal`, `Position`, `AccountInfo`) | frozen models; `.model_copy(update=…)` |
|
|
| Ports | `src/nexus_scalp/ports/` | `IMT5Port`, `IGatewayPort` protocol interfaces | signature change ⇒ all adapters update |
|
|
| Adapters | `src/nexus_scalp/adapters/` | MT5 Win32 IPC, ZMQ remote gateway, paper simulator, SQLite WAL `AuditRepository` | **no sync DB on the hot path** |
|
|
| Features | `src/nexus_scalp/features/` | 50D base → 70D canonical assembly, schema registry + hash, regime | schema is SSoT; ordering is contract |
|
|
| Models | `src/nexus_scalp/models/` | ScalpNet dual-path (2D snapshot / 3D TCN+attention), 4-logit head | input dim must equal schema dim |
|
|
| Training / Labeling | `src/nexus_scalp/training/`, `labeling/` | purged walk-forward, triple-barrier labels (Polars) | embargo/purge required; no lookahead |
|
|
| Signals / Strategies | `src/nexus_scalp/signals/`, `strategies/` | policy, ~30-rule SMC matrix, factory | **never holds adapter or risk handle** |
|
|
| Risk | `src/nexus_scalp/risk/` | dynamic volume, margin clamps, tier caps | authoritative for boundaries |
|
|
| Execution | `src/nexus_scalp/execution/` | OrderManager: 60-scenario router, 11 position states | authoritative for dispatch; `HARD_MAX_LOTS=10` |
|
|
| Accounting | `src/nexus_scalp/accounting/` | ledger, PnL, market calendar, retention | historical rows immutable |
|
|
| Application | `src/nexus_scalp/application/` | `LiveEngine` async loop: tick → features → … → web | never block the event loop |
|
|
| Intelligence closed loop | `experience/`, `intelligence/`, `mslie/`, `research/`, `shadow/`, `news/`, `model_lifecycle/`, `governance/` | autopsy, behavior detection, candidate training, shadow, promotion gates | **zero order authority**; promotion operator-gated |
|
|
| Model Factory | `src/nexus_scalp/model_generation/` | artifact-first datasets/experiments/models with manifests | inference needs no DB |
|
|
| Observability / Ops | `observability/`, `hygiene/`, `incidents/`, `forensics/`, `settings/` | structured logs, hygiene (AUDIT_ONLY default), incidents, deploy gate | incidents never mutate trading/risk/models |
|
|
| Web/API | `src/nexus_scalp/web/`, `Web/` | FastAPI REST + SSE + WebSocket, buildless SPA Control Center | background tasks registered in `app.state` |
|
|
| Release | `src/nexus_scalp/release/` | installer/CLI surface, update/rollback, verify | update blocked while LIVE |
|
|
|
|
## The closed intelligence loop
|
|
|
|
Live trade → accounting → experience → autopsy → research → candidate
|
|
training → shadow comparison → (operator-gated) promotion. Everything is
|
|
rebuildable from immutable ledgers.
|
|
|
|
## Where to look next
|
|
|
|
- [System map](system-map.md) — component inventory
|
|
- [Data flow](data-flow.md) — tick → decision, end to end
|
|
- [Runtime](runtime.md) — the LiveEngine loop
|
|
- [Research stack](research-stack.md) — how candidates are made and judged
|
|
- Authoritative internal map: [`agents/skill.md`](https://github.com/Opselon/NexusTradingForexBot/blob/main/agents/skill.md)
|