Skip to content

ADR-0003: MassTransit on Azure Service Bus as primary messaging

Decision

This page records a decision and its status. A Proposed decision is not binding; an Accepted decision is binding on the Factory until amended or superseded.

  • Status: Accepted
  • Date: 2026-01-01
  • Deciders: Event-Driven Architect, Enterprise Architect
  • Tags: messaging, events, integration

Reviewed 2026-10-09 — amended by ADR-0012 (Accepted 2026-10-09)

  • Amended 2026-10-09. The product owner accepted ADR-0012, which makes ConnectSoft.Extensions.MessagingModel the port and MassTransit on Azure Service Bus one transport profile. This ADR stays in force except where ADR-0012 changes it; read the two together.
  • Conflict: the user's 2026-10 direction prefers the MessagingModel port, allows Orleans and mandates no broker. The only production consumer of the template estate (DerechHaLev) approved the Orleans adapter over MassTransit on 2026-07-20.
  • Verified: MessagingModel.MassTransit is an options/adapter library with no outbox; MessagingModel.Orleans has outbox/inbox grains and an NHibernate outbox writer; Factory lifecycle events publish only through Factory.Messaging.MassTransit with no transactional run state behind them. There is no standalone Azure Service Bus adapter.
  • Provenance: Date is the 2026-06-17 bulk-commit value.

Context

The platform is event-driven end to end (see Event-Driven Architecture). It needs reliable pub/sub, saga/workflow correlation, retries, dead-lettering, and tenant-scoped subscriptions across many bounded contexts, all carrying the canonical Event Envelope.

Decision

Use MassTransit as the primary messaging abstraction running on Azure Service Bus. Envelope fields are mirrored into broker application properties (cs-event-type, cs-tenant-id, cs-trace-id, cs-correlation-id, cs-schema-version) for filtering and correlation.

Consequences

Positive

  • Mature saga/state-machine support, retry/redelivery, and consumer pipelines.
  • Decouples application code from transport specifics; testable with in-memory transport.

Negative / trade-offs

  • A framework dependency and its conventions across all services.

Neutral

  • Azure Service Bus is the production transport; alternatives can be swapped behind MassTransit if needed.

Alternatives considered

Alternative Why not chosen
Raw Azure Service Bus SDK More boilerplate; no built-in saga/retry pipeline.
Kafka / Event Hubs only Heavier operational model for the platform's command/saga needs; revisited per high-throughput stream use cases.