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

Y-Statement (structured decision record)

Sentence

In the context of order, billing, and notification flows in production, facing synchronous coupling and retry incidents when downstreams lag, we have decided for publishing domain events for order lifecycle changes with async consumers in order to looser coupling and room to add subscribers without expanding core request chains, accepting that we accept eventual consistency, idempotency work, and better tracing requirements.

Fields (same content, for reviews)

Context: order, billing, and notification flows in production
Concern: synchronous coupling and retry incidents when downstreams lag
Stance / subject: for / publishing domain events for order lifecycle changes with async consumers
Intended outcome: looser coupling and room to add subscribers without expanding core request chains
Deliberate tradeoff: we accept eventual consistency, idempotency work, and better tracing requirements