DIRAC-ADR-0001: Messaging-First Integration¶
Status: Accepted Date: 2026-03-29 Scope: Cross-repo platform decision Supersedes: Superseded by:
Context¶
DIRAC coordinates multiple domain systems, interfaces, and operational services. The previous architecture prose described intent-driven messaging, topic exchange conventions, and BRO/FED responsibilities, but those rules were not captured as an explicit decision record.
Without a canonical decision, repositories can drift toward ad hoc point-to-point integration, duplicate orchestration logic, or inconsistent message vocabulary.
Decision¶
DIRAC adopts a messaging-first integration model for cross-repo coordination.
- Cross-domain coordination should default to message-driven interaction.
- BRO is the canonical messaging hub for event flow, correlation, and topic conventions.
- FED is the canonical API and DTO boundary for capabilities that require API access, service encapsulation, or contract discovery.
- Direct repo-to-repo coupling is discouraged when messaging or FED contracts can satisfy the integration need.
The canonical topic families are:
emit/{domain}/{service}/{resource}/{id}/{event}
echo/{domain}/{service}/{resource}/{id}/{event}
call/{domain}/{service}/{resource}/{id}/{verb}
cmd/{domain}/{app}/{region}/{fleet}/{item}
dt/{domain}/{app}/{region}/{fleet}/{item}
meta/{domain}/{app}/{region}/{fleet}/{item}
API-led access remains allowed where continuous data access, typed query flows, or consumer ergonomics make messaging alone insufficient, but those exceptions must preserve contract ownership in FED.
Consequences¶
- Shared topic conventions become part of the platform contract rather than informal architecture guidance.
- New
dirac-*repositories should integrate by adopting message conventions and FED-owned contracts instead of creating bespoke integration surfaces. - Repo-local implementation detail remains in the owning repository.
- Future override ADRs must explain why a repo cannot follow messaging-first integration for a specific case.