> For the complete documentation index, see [llms.txt](https://pharos-production.gitbook.io/pharos-production-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://pharos-production.gitbook.io/pharos-production-docs/architecture-decision-records-a-receipt-worker-review.md).

# Architecture Decision Records: A Receipt-Worker Review

A worked receipt-worker ADR and W7/E3 evidence review separate design acceptance from release approval, with alternatives, recovery checks and review triggers.

An accepted architecture decision record can explain why a team chose a background worker while saying very little about whether today's worker is safe to release. The decision may predate a payload change, a new support requirement or an unresolved queue backlog. Its status remains historically accurate even when the evidence needed for the next deployment has changed.

For a production change, keep the architectural choice, its supporting evidence and the release decision connected through explicit references. Give each a different job. The ADR preserves the choice and rationale. Evidence shows what the team checked against a particular implementation. The release record identifies who authorized which change, with which conditions still open.

This guide develops that distinction through a fictional receipt-generation service. The proposed record and checks are a worked review example, not a report of a deployed system or a customer result. Use the structure to identify missing evidence in your own change; replace every assumption before applying it.

## Start with the decision that changes a promise

Suppose an order service currently creates a receipt during the request that confirms an order. A team proposes moving receipt generation to a background worker. The order can then become confirmed before the receipt is available. That changes what a successful response means to the customer, even if the API's fields remain unchanged.

Write the decision around that boundary: permit order confirmation before receipt completion, subject to an explicit pending state and a recovery path. Selecting a queue product comes later. A document titled after a queue can hide the more consequential choice about when the business considers its work complete.

The fictional example assumes that a receipt records an already confirmed order and does not itself authorize a payment. Receipt generation also does not determine inventory ownership. If either assumption is false in the actual system, the proposed boundary needs a different review. An asynchronous receipt must not silently become an asynchronous payment authorization.

This is where an architecture decision record earns its place. It captures a significant choice whose rationale would otherwise disappear into implementation tickets. [AWS's ADR process](https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/adr-process.html) identifies context, the decision and its consequences as the minimum content. Keep those elements visible while adding the evidence references needed for this particular production change.

## Compare alternatives against the same constraint

The team should inspect plausible alternatives before selecting the worker. Retaining synchronous generation may be adequate if receipt creation is fast enough under the real workload. A scheduled sweep might recover incomplete receipts without introducing an immediate message-delivery path. A queued worker makes another trade: more independent processing, with additional state and operating responsibilities.

| Alternative                         | What it preserves or changes                              | Decisive question                                                                     |
| ----------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| Keep receipt generation synchronous | Receipt completion remains part of the request's result   | Can the complete request meet the agreed response and recovery requirements?          |
| Add a scheduled recovery sweep      | Incomplete receipts can be found and retried separately   | Can customers tolerate the sweep interval and the associated pending state?           |
| Introduce a queued worker           | Confirmation and receipt completion become separate steps | Can the system durably discover unfinished work and prevent repeated receipt effects? |

Avoid invented measurements in this comparison. The table does not establish that the worker is faster or cheaper. A real review needs representative request traces, failure observations and operating costs. Until those inputs exist, record the relevant statements as assumptions and leave the proposal open.

Include the strongest reason to reject the preferred option. For the worker, that could be an inability to reconcile orders with missing receipts after a delivery failure. A favorable throughput demonstration would not answer that objection. Different alternatives may satisfy the same user requirement with different operational costs; use that requirement as the comparison's common reference.

## Write a compact proposed ADR

The following record deliberately stays Proposed. It describes the intended boundary and the conditions a reviewer must resolve. It is not permission to deploy.

**ADR-001: Separate order confirmation from receipt generation**

**Status:** Proposed. **Owner:** the order-service engineering lead. **Reviewers:** the service operator and product owner, with security or privacy review where the payload requires it.

**Context:** Receipt creation currently participates in order confirmation. The proposed change allows a confirmed order to have a pending receipt. Payment authorization and inventory ownership remain outside this change. Evidence about actual response time and recovery behavior is still required.

**Decision:** Use a background worker only if a confirmed order's unfinished receipt work remains durably discoverable, retries preserve the identity of the intended receipt, and support can distinguish pending work from a terminal failure. Keep the customer-facing order state explicit.

**Alternatives:** Retain synchronous generation or add a scheduled recovery sweep. Compare both against the same completion promise and measured workload before accepting the worker.

**Consequences:** Customers may see a confirmed order before its receipt. Operations must inspect unfinished work and handle repeated delivery. Reverting the application version does not automatically remove work already accepted by the worker.

**Evidence and review conditions:** Link the chosen order schema and event contract, recovery checks, receipt-identity rule, support procedure and ownership agreement. Revisit the decision if receipt completion becomes a prerequisite for confirmation or if the recovery assumptions no longer hold.

Keep detailed design exploration in linked documents. The [Microsoft ADR guidance](https://learn.microsoft.com/en-us/azure/well-architected/architect-role/architecture-decision-record) recommends concise records and separate supplemental design material. A reader should understand the chosen boundary and its consequences without opening every implementation ticket.

## Give each assumption an evidence dependency

A list of test links is difficult to review when it does not explain which uncertainty each test resolves. Bind the decisive assumptions to evidence that could actually support them. The reviewer then has a reason to request a missing result or reject an irrelevant one.

| Assumption to resolve                                        | Evidence to request                                                                    | Change that requires another look                                          |
| ------------------------------------------------------------ | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| Every confirmed order needing a receipt remains discoverable | A trace covering confirmation, durable work recording and recovery after interruption  | A different write sequence, transaction boundary or persistence mechanism  |
| Repeated processing preserves one intended receipt effect    | A documented receipt identity rule and checks for repeated delivery and worker restart | A new identity field, uniqueness constraint or downstream receipt provider |
| Operators can distinguish delayed work from terminal failure | A support view and procedure showing states, ownership and escalation                  | A changed state model, alert route or support responsibility               |
| Stopping the new worker leaves an accountable backlog        | A bounded stop-and-reconcile rehearsal with the outstanding work identified            | A new consumer version, message format or replay procedure                 |

These are proposed evidence requests. A completed row needs a result, its relevant inputs and the person who reviewed it. A screenshot of a passing test suite does not establish that it covers the interrupted write sequence in the first row. Name the specific behavior the evidence exercises.

Store sensitive logs in a controlled evidence location and link an appropriate summary from the ADR. The architectural record needs enough information to justify the decision; it does not need customer payloads or credentials. Access to a document and permission to operate a production system are separate responsibilities.

## Read a candidate evidence pack without filling its gaps

Suppose the fictional team presents a candidate worker revision, W7, using payload contract E3. Its evidence pack contains an interruption check, a repeated-delivery check and a support procedure. These identifiers are illustrative. They let us inspect the relationship between records without pretending that any checks ran.

Start with the inputs rather than the result label. An interruption check for W7 and E3 may be relevant to the candidate, provided that its environment and persistence boundary also match the behavior under review. A repeated-delivery result for W6 and E2 needs another explanation. The team may show that the changed fields do not affect receipt identity, or it may need to repeat the check against the candidate.

The result cannot establish its own applicability.

| Proposed pack entry                                            | What the reviewer can conclude                                   | What remains unresolved                                                    |
| -------------------------------------------------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------- |
| Interruption check names W7, E3 and its write boundary         | The check identifies the candidate inputs it intends to exercise | Whether its observed result demonstrates discoverable unfinished work      |
| Repeated-delivery check names W6 and E2                        | An earlier implementation was considered                         | Whether identity and downstream effects behave equivalently in W7 and E3   |
| Support procedure names a pending state but no receiving owner | The author has described a state operators may encounter         | Who responds, what access they need and how unresolved work is handed over |

Do not collapse these rows into a completion percentage. They answer different questions, and the weakest decisive assumption can block the change even if most documents are present. A missing receiving owner is not repaired by another successful developer test. Likewise, assigning an operator does not prove that the interruption path preserves work.

Ask for a narrowly scoped amendment to the evidence pack. The implementation owner can identify the exact difference between E2 and E3 and map it to the receipt-identity rule. The service operator can confirm the receiving role and access needed for pending work. Each amendment should state what it resolves and leave other unknowns visible.

If the comparison establishes that a prior result remains relevant, preserve the result under its original inputs and add the applicability reasoning beside the candidate review. Do not rewrite W6 as W7 in the old report. If another check is required, keep the earlier result and link the new one when it exists. Historical results and current conclusions need different identifiers.

A bounded review can therefore end with an accepted architectural direction and an unresolved release. That is a useful outcome when it prevents a design discussion from concealing an implementation gap. The release record can state that evidence about repeated effects and the receiving support owner remains outstanding, while the ADR continues to explain the chosen boundary.

The reverse outcome is also possible: the evidence may show that the proposed worker cannot satisfy the completion promise. In that case, revisit the alternative comparison. A request to improve the document would be inadequate because the missing capability belongs to the design or implementation. The record should make that distinction easy to see.

## Follow the missing-work and duplicate-work paths

Consider an interruption after an order becomes confirmed but before the system records receipt work. If the proposed design cannot discover that order later, the worker has introduced a missing-work path. The queue's normal delivery behavior cannot recover a job that was never recorded. The evidence request must therefore include the boundary between the order write and the work record.

Now consider an interruption after receipt creation succeeds but before the worker records completion. The next attempt may repeat the request to the receipt provider. A delivery identifier alone might identify that attempt while saying nothing about the business receipt it is allowed to create.

Define the intended receipt identity within the actual business rules. A candidate could involve the order identity and receipt type, but corrections, replacements and jurisdiction-specific documents may need different identities. Decide how those cases work before claiming that a unique key solves duplicate processing. The example does not prescribe a universal schema.

Ask the implementation team to demonstrate both interruption paths with observable business state. Record whether the check stops at an internal database or includes the downstream effect. If the provider's behavior is unknown after a timeout, retain that uncertainty and define reconciliation. Automatically issuing another create request is a decision with consequences, not a neutral retry.

## Keep design acceptance and release approval distinct

Accepting ADR-001 would mean that the responsible reviewers agree with the architectural direction under its recorded context. It would not prove that a particular worker version implements the direction. It would not authorize a production operator to ignore an unresolved recovery check.

Use a separate release record that points to the accepted ADR revision and the implementation being considered. Include the deployment scope, relevant configuration and the evidence reviewed for that candidate. The person authorized to release the service should be identifiable independently of the person who wrote the ADR.

An evidence mismatch should narrow or stop the proposed release. For example, a recovery check against an earlier payload format cannot establish behavior for a changed format without an explanation of what remains equivalent. Keep the earlier result as history; request another check for the changed behavior instead of relabeling the old result.

This separation also makes a limited rollout easier to explain. A team might accept the overall design while authorizing only a restricted customer cohort and a defined operating window. The release record carries that restriction. It must not quietly change the ADR's architectural scope or imply that all customers have been validated.

<figure><img src="https://content.gitbook.com/content/k1OAV65qwhRKyz2SLBtA/blobs/7n94ENri9ZJ70TjMHzcC/assets/decision-evidence-release.png" alt="Three connected records: the accepted ADR preserves the architectural choice; candidate evidence binds checks to an implementation revision; the release decision records authorized scope and owner. A changed implementation returns to evidence review." width="1200"><figcaption><p>Proposed review structure for the fictional receipt worker. The diagram describes document relationships, not an executed release.</p></figcaption></figure>

## Plan reversal around work already accepted

Turning off the worker does not answer what happens to jobs it has already received. Some may be waiting, some may be in progress and some may have created a receipt without recording completion. A code rollback changes software; it does not necessarily reverse those effects.

For the fictional service, define a stopping boundary before changing the traffic route. Identify which component stops accepting new receipt work and how operators establish the outstanding set. Choose a deliberate treatment for each state: allow compatible work to finish, hold it for reconciliation or move it through a reviewed recovery procedure.

Check whether the previous application version understands the states introduced by the new worker. Returning old code to production while leaving new state behind can create another recovery problem. If the versions cannot coexist, the release plan needs an explicit compatibility or migration boundary rather than a generic rollback instruction.

Do not convert unresolved work into a completed status merely to close the change. Preserve its identity and ownership. When external effects cannot be safely reversed, describe the compensating process and the human authority required for it. That may be a reason to defer release even after the architectural approach has been accepted.

## Make review triggers observable

A review date can remind the team to inspect the record, but a date alone does not describe what would invalidate its reasoning. Attach triggers to the assumptions that carry the choice. A changed business completion promise is one trigger. A changed message contract or receipt provider may be another.

State who sees the trigger and what they must do. The order-service owner might open a replacement proposal when a requirement makes receipt completion mandatory before confirmation. A payload change might instead require an implementation evidence review while leaving the architectural choice intact. Both require attention, but they are different decisions.

Use thresholds only when the team has defined them from real operating requirements. A maximum pending age, recovery interval or backlog limit should have an owner and a reason. This example supplies no universal number because an unverified threshold would make the record look more complete while leaving its operating promise undefined.

Some changes need no new ADR. A refactoring that preserves the significant boundary may only need normal implementation review and updated evidence. Explain that relationship in the release record. Requiring another architectural vote for every internal change can turn a useful decision log into a queue of routine tickets.

## Preserve the decision when circumstances change

Michael Nygard's original ADR article makes the historical boundary explicit:

> If a decision is reversed, we will keep the old one around, but mark it as superseded.

Michael Nygard, *Documenting Architecture Decisions*, Cognitect, November 15, 2011. [Original source](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions).

Apply that rule when the fictional product changes its completion promise. Create a replacement ADR explaining the new requirement and the options considered under it. Link the old and new records so a future maintainer can follow the change without confusing the old decision with the current one.

Keep the accepted decision text stable. Separate later evidence results, incident observations and implementation status from the original rationale, using versioned supporting records. The status and supersession link can identify the replacement while the earlier decision remains readable in its original context.

For a system that already exists, distinguish known history from reconstructed reasoning. If nobody can verify why an earlier team chose a design, say that the historical rationale is unknown. Document the present review and the evidence available now. A polished retrospective explanation should not be presented as a contemporaneous decision record.

## Run the review as a bounded working session

Send the proposed record and its decisive evidence before the meeting. Ask each reviewer to identify the assumption they can assess and the one they cannot. That keeps a product disagreement about completion semantics from being mislabeled as a queue-configuration issue.

1. Confirm the decision boundary and the requirements it changes. Stop if participants are evaluating different business promises.
2. Compare the serious alternatives using the same constraints. Record the strongest unresolved objection to the preferred option.
3. Walk the missing-work and duplicate-work paths. Check that evidence covers the relevant implementation and downstream boundary.
4. Assign owners to unresolved conditions. Separate design acceptance from release authorization and any operating exception.
5. Record the outcome with its rationale. Keep the proposal open, reject it or accept the architectural direction; link any subsequent release decision separately.

The meeting's output should be a decision or a bounded set of missing inputs. Assigning an owner to a missing check does not make the check pass. If the unresolved issue changes the meaning of confirmation, leave that part of the proposal unresolved rather than accepting it through an unrelated implementation ticket.

When the team cannot agree on the boundary, external architecture review can help compare assumptions and options. Pharos Production's [IT consulting and architecture review services](https://pharosproduction.com/services/it-consulting-services/) describe written outputs covering options, trade-offs, recommendations, an implementation roadmap and a risk register. That service scope is relevant to an unclear change decision; this fictional ADR is not evidence of a completed consulting engagement.

## Keep the record usable after the meeting

Place the decision log where the people who implement and operate the system can find it. Version control is useful for preserving history, but some reviewers may need a readable documentation view. Choose a clear authoritative location and identify how any published view relates to it. Two editable copies with different statuses undermine the log's purpose.

Give every record a stable identifier and descriptive title. Link the affected implementation work and the replacement ADR when one exists. Keep a short index showing current status and ownership, so a maintainer can find the decision without remembering which meeting produced it.

Review access when staff or suppliers change. The receiving team needs the rationale and the relevant evidence, while customer data and secrets retain their own access controls. A handoff should identify unresolved conditions as clearly as accepted choices. A complete-looking document set is unhelpful if the next operator cannot see which recovery check remains open.

For ADR-001, the final question is concrete: can a reviewer explain why confirmation may precede receipt completion, what evidence supports that boundary and who can authorize the next release? Keep the proposal open until those answers can be traced to the actual system. Preserve the record when the answers change.

## Sources and review scope

Published October 19, 2026. Source pages were checked on the same date. The receipt worker, record identifiers and evidence-pack entries are fictional teaching examples. The procedures are proposed review guidance; no production validation result is claimed.

* [Documenting Architecture Decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions), Michael Nygard, Cognitect, November 15, 2011.
* [Architectural decision record process](https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/adr-process.html), AWS Prescriptive Guidance; publication date not stated.
* [Maintain an architecture decision record](https://learn.microsoft.com/en-us/azure/well-architected/architect-role/architecture-decision-record), Microsoft Learn; updated April 13, 2026.

## More insights to read

* [A Smart Contract Upgrade Needs an Evidence Bundle](https://hackmd.io/@dmytro-nasyrov/smart-contract-upgrade-evidence-bundle)
* [The Payment Recovery Fieldbook: Identity, Replay and Reconciliation](https://hackmd.io/@dmytro-nasyrov/payment-recovery-fieldbook-identity-replay-reconciliation)
* [One Payment, Several Event IDs: Define the Idempotency Boundary](https://hackmd.io/@dmytro-nasyrov/payment-event-idempotency-boundary)
* [Pause the Contract, Then Account for Messages Already in Flight](https://hackmd.io/@dmytro-nasyrov/pause-smart-contract-in-flight-messages)
* [Replay Payment Events Without Repeating the Business Effect](https://hackmd.io/@dmytro-nasyrov/replay-payment-events-without-duplicate-effects)

## About the author

<figure><img src="https://content.gitbook.com/content/k1OAV65qwhRKyz2SLBtA/blobs/PE9Ur7iAfuZccvsS4Ess/assets/dmytro-nasyrov-author-photo.jpg" alt="Portrait of Dmytro Nasyrov wearing a dark suit and light blue shirt against a dark background." width="128"><figcaption><p>Dmytro Nasyrov. Photo supplied by the author.</p></figcaption></figure>

*Written by* [*Dmytro Nasyrov*](https://pharosproduction.com/dmytro-nasyrov/) *PhD, software architect with 24 years of production experience. Dmytro is the founder and CTO of Pharos Production. He works on production software architecture for FinTech, AI, Web3 and blockchain systems.*