Skip to content

Architecture (Logical)

This document describes the logical architecture only. Implementation structure, module internals, and package naming are deferred to future work. For the runnable local demo flow, see Demo Flow.

Diagram

%%{init: {
  "theme": "base",
  "themeVariables": {
    "fontSize": "14px"
  },
  "flowchart": {
    "nodeSpacing": 32,
    "rankSpacing": 42,
    "padding": 12
  }
}}%%

flowchart TB
    A["Run Spec"] --> B["Nautilus<br/>Run Mode"]
    B --> C["Journal<br/>Metadata<br/>Artifacts"]
    C --> D["Evidence Compare<br/>tc evidence compare"]
    D --> E["Evidence artifacts<br/>JSON and Markdown"]
    C --> F["Reports<br/>Observability"]
    E --> F
    F --> G["Safety<br/>Reconciliation<br/>Drills"]

Responsibilities

Run Spec

  • Defines mode (backtest or paper) and run intent
  • Captures immutable run inputs (configuration and references)
  • Serves as the versioned source of truth for a run
  • Includes reserved local-only connectivity_readiness metadata for env-placeholder preflight intent
  • Uses venue labels in examples (binance, binance_testnet) for run metadata and future probe intent only, not active exchange/testnet/live connectivity

Nautilus Run Mode

  • Executes the run in one of two modes: backtest or paper
  • Applies the same operational model across both modes where possible
  • Produces run lifecycle events for downstream tracking
  • Backtest mode currently executes a Nautilus engine smoke path over prepared 1-minute candles
  • Backtest currently registers one built-in local scenario strategy (ops_smoke_demo)
  • Backtest venue: binance currently maps to Nautilus test instrument context plus local candle fixtures
  • RunSpec strategy fields are currently scenario identity metadata, not custom strategy loading

Journal / Metadata / Artifacts

  • Journal records operational run events and notable actions
  • Metadata records identifiers, timestamps, status, and hashes
  • Artifacts store outputs in a predictable run-oriented layout
  • Concrete artifact paths in this repo:
  • artifacts/runs/<run_id>/run_spec.yaml
  • artifacts/runs/<run_id>/metadata.json
  • artifacts/runs/<run_id>/journal.jsonl
  • artifacts/runs/<run_id>/metrics.json
  • artifacts/runs/<run_id>/report.md
  • artifacts/runs/<run_id>/connectivity_readiness.json (when readiness is evaluated)
  • artifacts/runs/<run_id>/connectivity_probe.json (when loopback probe is evaluated)

Reports / Observability

  • Reports summarize run outcomes and key checks
  • Observability hooks expose basic signals for health and run progress
  • Designed for practical inspection, not full production telemetry
  • tc metrics export and tc metrics serve use the same artifact-backed renderer; export is a one-shot inspection path, and serve is the HTTP path (/metrics) scraped by Prometheus for Grafana
  • tc metrics serve --evidence-root artifacts/evidence includes aggregate evidence metrics rendered from evidence artifacts
  • Grafana evidence panels (Backtest vs Paper Evidence Status, Evidence Known Gaps) visualize those aggregate evidence metrics
  • Readiness metrics are artifact-backed from connectivity_readiness.json; they do not perform network probes
  • Probe metrics are artifact-backed from connectivity_probe.json; probe execution remains local loopback-only and read-only
  • Static dashboard definition: dashboards/grafana/tradingchassis-ops-lab-run-observability.json

Evidence compare (cross-run artifact)

  • Consumes two existing run artifact directories (backtest + paper)
  • Produces one cross-run evidence directory under artifacts/evidence/<backtest_run_id>__<paper_run_id>/
  • Writes both machine-readable (backtest_vs_paper_evidence.json) and operator-readable (backtest_vs_paper_evidence.md) outputs
  • Comparison is operational and artifact-backed, not strategy-performance analysis

Safety / Reconciliation / Drills

  • Safety controls include kill switch behavior
  • Reconciliation checks detect expected state mismatches
  • Failure drills validate operational response for known scenarios
  • File-based local outputs:
  • runtime/kill_switch/<run_id>.state.json
  • runtime/kill_switch/<run_id>.events.jsonl
  • artifacts/runs/<run_id>/reconciliation_result.json
  • artifacts/runs/<run_id>/drills/*.json