Skip to content

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

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: event-driven, events, traceability

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

  • Amended 2026-10-09. The product owner accepted ADR-0014, which defines the port-level envelope with tenant/project/run/step/attempt identity, a Cancelled state and no replay promise. This ADR stays in force except where ADR-0014 changes it; read the two together.
  • Verified: the envelope in code (AgentEventEnvelope) carries event id, time, agent id, trace id, blueprint id, origin and workflow step only; AgentLifecycleStage has no Cancelled value; nothing is event-sourced and no replay mechanism exists; Platform's JSON task/event schemas are a third dialect.
  • Provenance: Date is the 2026-06-17 bulk-commit value.

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.