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

ADR-0029: Introduce event-driven communication for order lifecycle updates

Status

Proposed

Context

Synchronous calls tie ordering, billing, and notifications. One slow call blocks unrelated work. Prior billing latency spiked and caused retry storms; we need side effects to decouple from the main write path.

Decision

Publish domain events for order lifecycle changes. Consumers react asynchronously. Synchronous calls are allowlisted for paths that must complete in a single user-facing request. Version events; breaking changes get a new name or a migration window.

Consequences

Positive: independent deploys; add subscribers (analytics, fraud) without changing the order service each time. Negative: eventual consistency, duplicate delivery, idempotency, and end-to-end tracing across hops. Observability: correlation IDs must cover async work.