adr.zone

ADR Example: Event-driven order lifecycle and domain events (MADR 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

  • Status: proposed
  • Deciders: <team or role>
  • Technical story: <issue link> · Date: <YYYY-MM-DD>

Context and Problem Statement

Tight sync coupling between services causes outages and review drag. Billing and notifications should not sit on the same request chain as the core write forever.

Decision Drivers

  • Decouple side effects from core requests
  • Observable contracts for lifecycle changes

Considered Options

  • More sync APIs — fails the coupling problem
  • Outbox + domain events — matches scaling and org boundaries

Decision Outcome

Adopt domain events for lifecycle; sync only where user latency demands it, with a maintained allowlist.

Consequences

  • Subscribers can scale; ops must own ordering, idempotency, and traces
  • UI and downstreams accept eventual state

Pros and Cons of the Options (summary)

Events win for growth; cost is distributed systems operations.

Confirmation

Pending architecture review; pilot on read-side subscribers first.