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.
┌──────────────────────── 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 — component inventory
- Data flow — tick → decision, end to end
- Runtime — the LiveEngine loop
- Research stack — how candidates are made and judged
- Authoritative internal map: ">https://github.com/Opselon/NexusTradingForexBot/blob/main/agents/skill.md">
agents/skill.md