adr.zone

ADR Example: Event-driven order lifecycle and domain events (ISO 42010–inspired format)

Example of an ADR for moving cross-service work off synchronous call chains: domain events, idempotency, and observability across async hops. The sample status is Proposed so you can see how a team records intent before full rollout; switch the format to compare the same content across templates.

When this type of decision shows up

  • Synchronous request paths fan out to billing, notifications, and analytics and become a reliability choke point.
  • You are willing to own eventual consistency, duplicate delivery, and end-to-end tracing in exchange for looser coupling.
  • You need to add new subscribers (fraud, projections) without inflating a single “god” service API.

Format

Preview

Introduce event-driven communication for order lifecycle updates

Architecture description record (ISO/IEC/IEEE 42010–inspired). Lightweight, Git-friendly fields. Not a full conformance report to the standard—use the vocabulary of stakeholders, concerns, and views to align the decision with the architecture description.

Record ID (cross-ref): ADR-42010-0029

System / subject scope

Order monolith and adjacent services; event bus and consumers for lifecycle projections.

Stakeholders and roles

Order team, billing, notifications, SRE, observability owners.

Stakeholder concerns (to be addressed in the architecture description)

Coupling, availability under downstream failure, understandability of side effects, audit of what happened and when.

View and viewpoint (what is shown, and from which perspective)

Viewpoint: process / messaging. View: which transitions emit which events, schemas, and consumer SLOs.

Decision

Move cross-boundary work to events for lifecycle; keep a narrow sync surface for what must be immediate.

Rationale (with respect to the concerns and alternatives)

The architecture should expose where asynchrony is intentional so operators can reason about lag and ordering. Stakeholder concern is operability, not just code layout.

Architectural impact (elements, relationships, and operational follow-through)

Outbox or equivalent for reliable publish; versioned schema registry; runbooks for poison messages.

Traceability (requirements, policy, SLOs, other ADRs)

Link to prior incident post-mortem; per-topic ownership in catalog.