Decision at a glance
A durable record for the choice that was made
Fictional example: The Harborlight product team chose asynchronous event delivery for a non-critical inventory-summary update. This record shows how to preserve the reasoning so maintainers can understand the choice later.
An architecture decision record captures a concluded decision and its rationale. It is not an open proposal or a task queue. The key outcome here is to keep the inventory update from slowing the requesting workflow, while accepting the added work of handling delayed or repeated events.
Scope: delivery of a summary update after an inventory change. The decision does not define inventory correctness, customer-facing availability promises, or a broader event-platform standard.
Context and constraints
What the team was solving
In the fictional example, the product workflow records an inventory change and then updates a separate summary view. The team wanted the original workflow to finish without waiting for that summary update. The summary can arrive later; it is not the transaction that records the inventory change.
The decision assumes the summary can tolerate delay and that maintainers can identify, retry, and investigate events that are not delivered as expected. If either assumption stops being true, the rationale needs review.
Alternatives considered
Illustrative comparison for the fictional inventory-summary update; not a live system record.
| Option | Benefit | Trade-off | Reason |
|---|---|---|---|
| Direct synchronous call | The summary update is attempted within the original request. | The request waits on the summary dependency; dependency delays can affect the caller. | Not selected because the summary does not need to hold up the inventory-change workflow. |
| Asynchronous event | The original workflow can finish without waiting for the summary consumer. | Adds delivery, retry, duplicate-handling, and observability responsibilities. | Selected because delayed summary updates are acceptable in this example and the team accepts the additional operational complexity. |
| Scheduled batch refresh | Groups summary work into periodic processing. | Updates wait for the next batch and the batch process needs monitoring. | Not selected because the team wanted updates to follow changes without waiting for a scheduled run. |
Worked example: the decision and its consequences
Why asynchronous delivery fit this case
The team records an inventory change and emits an event for the separate summary view to consume. The original workflow does not wait for that consumer. The decision is appropriate only while the summary can be delayed and the team can operate the delivery path.
Consequences for maintainers:
- Track whether events are produced and consumed, and make delivery failures discoverable.
- Design the consumer to handle a repeated event without applying the same summary change twice.
- Make retry and recovery behavior understandable to the people supporting the service.
- Accept that the summary may temporarily lag behind the recorded inventory change.
Not solved by this decision: the authoritative inventory record, the correctness rules for the summary, and the product response when the summary is delayed. Those questions need their own context and decision if they become consequential.
Revisit triggers
A trigger starts review; it does not automatically change the decision
- Traffic changes: measured event volume or consumer load no longer fits the team's operating assumptions.
- New latency need: a product requirement makes the current delay in the summary unacceptable.
- Repeated delivery failures: incident or support records show recurring failures that the current recovery approach does not address.
- Dependency changes: the event broker, consumer, or delivery path changes in a way that invalidates the original trade-off.
- Scope changes: the summary becomes part of a workflow that cannot safely tolerate delayed updates.
When a trigger occurs, compare the current conditions with the recorded assumptions, then capture any new decision and rationale as a separate, linked record in the organization's chosen knowledge location.
Questions maintainers ask
Use the record to understand the choice, then follow the appropriate team handoff.
How is this different from a proposal?
A proposal asks people to evaluate options before a decision is made. This record describes a concluded choice, why it was selected, what it means for maintainers, and what conditions could prompt review.
What makes the rationale useful later?
Name the problem, scope, constraints, alternatives, trade-offs, and assumptions in terms a maintainer can check. In the example, the central assumption is that the summary may lag and is not part of the inventory-change transaction.
What should I do if a trigger occurs or the record seems wrong?
Bring the changed condition or correction to the team accountable for the affected system or decision record. Compare it with the recorded assumptions; do not treat a trigger as automatic authorization to change the architecture.
Does this record prove that a decision was approved or implemented?
No. This page explains a decision and its reasoning. It does not record an approval workflow, implementation status, or live system state.