Skip to content

5. Architecture

Dio is built on OCaml 5.2, compiled with OxCaml's flambda2 backend, with true parallelism via domains. Each trading asset runs in its own isolated domain with lock-free communication, enabling microsecond-precision execution across multiple concurrent strategies.

5.1 Key design principles

  • Domain-per-asset isolation. Each trading pair runs in its own OCaml 5 domain. Strategies, order executors, and exchange feeds are fully isolated with lock-free messaging.
  • Event-driven execution. All strategy logic is triggered by events: price ticks, order fills, cancellations, balance updates, and oracle decision publications. There is no polling loop.
  • Capital Oracle supervision. The oracle runs as a supervised module inside the engine, heartbeating on every published pass. A health monitor restarts it automatically if it stalls, and domains resume from the next published pass.
  • Single source of truth. Every sizing and activity value flows from the oracle's decision record through one code path. Diagnostics exist in logs and the standalone executable only, never duplicated into strategy state.
  • Lock-free communication. The tick bus and event registry use atomic compare-and-set operations for zero-contention reads. Writers perform CAS loops on shared state.
  • Ring buffer order queuing. Strategy orders are queued through fixed-capacity ring buffers with per-strategy mutexes, ensuring bounded memory usage and deterministic latency.
  • In-flight deduplication. Both order placements and amendments are deduplicated via composite keys (symbol + side + quantity + price), preventing duplicate submissions.
  • Microsecond latency profiling. The engine records per-domain percentile latencies (p50, p90, p99, p999) in microseconds, providing real-time visibility into performance.
  • Graceful shutdown. The engine handles SIGINT/SIGTERM for orderly shutdown, tearing down feeds and cleaning up sockets with a 3-second forced-exit timeout.

5.2 Exchange integration

Dio currently supports five venues through a common exchange interface:

  • Interactive Brokers. TWS API for orders, market data, and account information across equities, options, futures, bonds, and FX with unified symbology.
  • Alpaca. Websocket market data and trading feeds with REST order management, session-aware time-in-force handling, and fractional-share constraints applied as explicit venue rules.
  • Kraken. Websocket-based feeds for ticker, orderbook, balance, and execution data. Authenticated REST/WS for order management, with tradeable balances derived as wallet totals minus open-order holds.
  • Hyperliquid. Websocket feeds for mid-prices, L2 orderbook, and spot state with holds netted at ingestion. REST-based order management with L1 signature generation and retry/backoff logic.
  • Lighter. Websocket feeds for instruments, orderbook, executions, and balances, with an external signer library for order authorization.

The exchange integration layer is designed to be extensible. New exchange backends can be added by implementing the common exchange interface module.

5.3 Dashboard

A standalone TUI dashboard binary connects to the running engine over a Unix domain socket and displays:

  • Uptime, sentiment index, per-venue connectivity status
  • Heap size, GC statistics, memory fragmentation
  • Per-strategy holdings, mid-price, accumulated positions, pending distances, unrealized value
  • Live capital-oracle decisions: active verdict, resolved spacing, buy and sell sizes, survival diagnostics
  • Per-domain latency percentiles (p50, p90, p99, p999) in microseconds
  • Domain running/stopped status, restart count, and last restart age

The dashboard operates out-of-process for crash isolation and auto-reconnects when the engine restarts.