ADR-0003: MassTransit on Azure Service Bus as primary messaging¶
- Status: Accepted
- Date: 2026-01-01
- Deciders: Event-Driven Architect, Enterprise Architect
- Tags: messaging, events, integration
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. |