Skip to content

ADR-0010: Event-driven architecture with a canonical envelope

  • Status: Accepted
  • Date: 2026-01-01
  • Deciders: Event-Driven Architect, Enterprise Architect
  • Tags: event-driven, events, traceability

Context

The factory must correlate every artifact, agent task, commit, deployment, and runtime signal from business intent to running SaaS and back. Tight synchronous coupling between platforms would not scale and would break traceability and replay. A uniform message contract is needed so any consumer (Knowledge, Observability, Control Plane) can correlate and replay.

Decision

Adopt event-driven architecture as the primary integration style between platforms, with a single canonical Event Envelope wrapping every message. All events carry traceId/correlationId; integration events are versioned and registered in the Event Catalog. Envelopes are immutable once published, enabling replay.

Consequences

Positive

  • End-to-end traceability and replayability; loose coupling between platforms.
  • Uniform observability and idempotency model (dedup on eventId).

Negative / trade-offs

  • Eventual consistency must be designed for; debugging spans multiple services (mitigated by traceId).

Neutral

  • Synchronous APIs still exist for queries; events are the cross-platform contract.

Alternatives considered

Alternative Why not chosen
Synchronous request/response only Tight coupling; poor scale and traceability.
Per-team ad hoc message shapes Breaks correlation, replay, and catalog governance.