Skip to content

ADR 005: Actor Model with Message Passing

Status

Accepted

Context

The trading system requires concurrent execution of multiple components: - Market monitors maintaining WebSocket connections to both exchanges - Arbitrage detection scanning orderbooks continuously - Order execution handling requests to multiple platforms - Risk management checking positions and limits

These components must operate independently without blocking each other, while maintaining clear interfaces and supporting testability.

Decision

Use actor-based concurrency with message passing for inter-component communication.

Implementation Pattern

Each component operates as an independent actor with its own message loop:

// Market Monitor Actor
enum MarketMonitorMsg {
    Subscribe(MarketId),
    OrderbookUpdate(MarketId, OrderbookDelta),
    Shutdown,
}

// Strategy Engine Actor
enum StrategyEngineMsg {
    ArbOpportunity(ArbitrageOpp),
    CopyTrigger(CopyEvent),
    ConfigUpdate(StrategyConfig),
}

Channel Selection

  • Primary: tokio::sync::mpsc for bounded channels with backpressure
  • Performance-critical paths: flume for lower overhead where needed
  • Broadcast: tokio::sync::broadcast for market data fanout

Alternatives Considered

Approach Pros Cons Verdict
Actor Model Isolation, testability, scalability More complex wiring Chosen
Shared State + Mutex Simple implementation Contention, deadlock risk Rejected
Thread-per-Component True parallelism Hard to coordinate, resource heavy Rejected
Single-threaded Event Loop Simple, no sync issues Can't utilize multiple cores Rejected

Consequences

Positive

  • Isolation: Component failures don't cascade
  • Testability: Easy to inject test messages and verify behavior
  • Scalability: Add more actors for parallelism as needed
  • Clarity: Clear boundaries and interfaces between components

Negative

  • More boilerplate for message types and handlers
  • Channel capacity tuning required to prevent backpressure issues
  • Debugging across actor boundaries can be challenging

Neutral

  • Need careful design of message types to avoid over-coupling

References

Linked Requirements

  • NFR-ARCH-002: Use actor model with message passing for concurrency