Event Bus

The platform uses an event bus abstraction with pluggable backends for asynchronous communication between services.

Backends

PostgreSQL Event Bus (Production)

Durable event storage in the domain_events table. Workers claim events using optimistic locking, process them, and mark them complete. Failed events are retried with exponential backoff and eventually routed to a dead-letter queue.

Key properties:

• Durability: Events survive service restarts (persisted in PostgreSQL)
• Ordering: Events processed in insertion order within a topic
• Concurrency: Multiple workers can claim events without duplicates (optimistic locking)
• Recovery: Graceful shutdown tracks in-flight events; crash recovery re-processes unclaimed events
• Metrics: Published count, delivered count, failed count, processing latency

Implemented in packages/event-bus/src/postgres-event-bus.ts at commit 4b572c2.

Google Cloud Pub/Sub (Production)

Cloud-native event delivery for higher-throughput deployments. Per-topic subscriptions with configurable ACK deadline and retry policy. Optional message ordering per tenant.

Implemented in packages/event-bus/src/pubsub-event-bus.ts at commit 4b572c2.

In-Memory (Development Only)

Single-process, non-durable event bus for local development and testing. Not suitable for production.

Event Publishing

Services publish events via the event bus abstraction:

await eventBus.publish({
  type: 'bhi.calculated',
  tenantId: ctx.tenantId,
  payload: { customerId, score, band, trend },
  metadata: { correlationId, actorType: 'system' }
});

Event Subscription

Services subscribe to event types with handler functions:

await eventBus.subscribe('bhi.calculated', async (event) => {
  // Process event within subscriber service
});

Wildcard subscriptions are supported via subscribeAll().

Event Types

Events are published for key lifecycle transitions:

• Data sync events: sync.started, sync.completed, sync.failed
• BHI events: bhi.calculated
• NBA events: nba.generated
• Workflow events: workflow.created, workflow.triggered, workflow.completed, workflow.failed
• Task events: task.created, task.completed, task.failed

Event type definitions are in packages/shared-types/.

Backend Selection

Controlled via EVENT_BUS_TYPE environment variable:

• in-memory -- development
• postgres -- production (default)
• pubsub -- production (GCP-native)