Event Bus Architecture — Redis pub/sub backbone

Overview

The event bus is the nervous system of the Barfinex platform. Every inter-service communication — market data, signals, decisions, risk events, execution outcomes — travels as a typed, enveloped message over Redis pub/sub. No service calls another service's REST API for real-time data; they publish and subscribe through the bus.

Library: libs/event-bus — Redis pub/sub abstraction with exponential-backoff reconnect, dedup subscription, and per-interval latency metrics. Reads EVENT_BUS_REDIS_URL / REDIS_URL / REDIS_HOST+REDIS_PORT.

BaseEvent envelope

Every message on every channel is wrapped in a BaseEvent:

{
  eventId:       string    -- UUID, unique per event instance
  type:          string    -- SubscriptionType enum key
  source:        string    -- service name: 'provider' | 'detector' | 'advisor' | 'inspector'
  timestamp:     number    -- Unix ms
  correlationId: string?   -- links events in one decision cycle
  causationId:   string?   -- the eventId that caused this event
  payload:       T         -- typed payload per EventPayloadMap
}

Source enforcement: assertEventSourceMatch(type, source) is called at publish time — each service can only emit events with its own prefix. Detector cannot publish PROVIDER_*; Advisor cannot publish INSPECTOR_*. Compile-time guard.

Channel categories

All channel names are defined in libs/types/src/subscription.interface.ts as the SubscriptionType enum. Never use string literals — always import from @barfinex/types.

Provider channels — publisher: Provider (8081)

Detector channels — publisher: Detector (8101)

DETECTOR_SIGNAL_GENERATED is the primary trigger for the Advisor pipeline. It carries a strategyId (detector sysname) used by DecisionWindowService to deduplicate per-strategy windows — two detectors on the same symbol each get an independent decision cycle.

Advisor channels — publisher: Advisor (8009)

Execution intents (consumed by Inspector — runtime validated):

Decision events:

Telemetry (28 event types):

Alert channels:

Inspector channels — publisher: Inspector (8008)

Market regime events:

Execution events:

Alert events (auto-forwarded to Telegram):

Note: INSPECTOR_RISK_GOVERNOR_DECISION is NOT a Redis channel. It is an audit log label used with auditService.log(). Do not add to SubscriptionType.

Execution-critical channels: Redis Streams dual-write

Four execution-critical channels dual-write to Redis Streams for bounded replay:

• ADVISOR_EXECUTION_INTENT_OPEN
• ADVISOR_EXECUTION_INTENT_CLOSE
• ADVISOR_EXECUTION_INTENT_REDUCE
• ADVISOR_EXECUTION_INTENT_FLIP

Also runtime-validated at publish/subscribe boundaries:

• DETECTOR_SIGNAL_GENERATED
• DETECTOR_POSITION_*_REQUEST
• PROVIDER_ORDER_FILL
• PROVIDER_ORDER_TERMINAL

Redis Streams provide bounded replay via stable subscriptionId — consumers can re-read the last N messages after reconnect without losing execution intents.

Cross-service subscription matrix

Latency observability

All services record event bus latency via @barfinex/utils:

• event_bus_latency_ms — round-trip pub→sub latency
• event_trace_latency_ms — end-to-end trace latency from event metadata
• p50 / p95 / p99 / p999 quantile gauges — exposed on Prometheus /metrics endpoint

Provider publishes these for market/order events. Detector and Advisor record from event metadata. Inspector records on execution/risk ingress.

Deprecated aliases (never use in new code)