ADR-[NNN]: [Short decision title in active voice]

Detailed architecture decision record combining the decision description fields proposed by Jeff Tyree and Art Akerman (IEEE Software, 2005) with Olaf Zimmermann's Y-statement summary. Use it for decisions that are costly to reverse or that several teams depend on. For everyday decisions, the shorter ADR or MADR templates are enough.

1. Summary (Y-statement)

In the context of [functional or architectural context, for example "the order service publishing events to five downstream consumers"], facing [the concern or non-functional requirement, for example "the need for at-least-once delivery without coupling release cycles"], we decided for [the chosen option, for example "a transactional outbox with a managed message broker"] and neglected [the rejected options, for example "direct synchronous calls and a distributed two-phase commit"], to achieve [the benefits, for example "independent deployability and no lost events"], accepting that [the drawbacks, for example "consumers must be idempotent and events arrive up to 5 s late"].

2. Issue

[Describe the issue. Example: "The order service currently calls the invoicing, shipping and loyalty services synchronously. Any outage of a downstream service blocks checkout; three incidents in Q2 caused 4.5 hours of checkout downtime. Two new consumers are planned for next quarter, which would make the coupling worse."]

3. Decision

[Example: "The order service will write domain events to an outbox table in the same transaction as the order change. A relay process publishes outbox rows to the managed message broker topic orders.v1. Downstream services consume from their own subscriptions and must handle duplicate events."]

4. Assumptions

5. Constraints

6. Positions

7. Argument

[Example: "Availability of checkout is the top quality goal (see quality scenario QS-03). P1 cannot meet it because any downstream outage still blocks the request path. P3 conflicts with constraint CO-1 and reduces availability further. P2 removes downstream services from the checkout path, satisfies CO-1 and CO-2 with the EU-hosted managed broker, and makes adding consumers a change on the consumer side only. Its costs, operating a relay and making consumers idempotent, are lower than one more hour of checkout downtime per quarter."]

8. Implications

• [Example: Every consumer must deduplicate by event ID; the platform team publishes a shared library for this by YYYY-MM-DD.]
• [Example: Operations adds alerts on outbox backlog older than 60 s.]
• [Example: The event schema orders.v1 becomes a public contract; breaking changes require a new topic version.]
• [Example: Reporting that relied on synchronous invoicing must accept a delay of up to 5 s.]

9. Related decisions

10. Related requirements

11. Related artifacts

12. Related principles

13. Notes

Standard and licence note

Based on the architecture decision description template by Jeff Tyree and Art Akerman ("Architecture Decisions: Demystifying Architecture", IEEE Software 22(2), 2005) and the Y-statement format by Olaf Zimmermann. This template is original text written for this collection and reproduces no text from those publications. Template licence: MIT.