Recommended resources
The freely available resources this lesson will direct you to.
Hello again. Last lesson, we mapped the invoice pilot across customer integration, intake, and reporting. We also identified an important seam: intake can confirm that it accepted an invoice, but only the reporting side can confirm that the invoice is searchable. The teams still need an agreement about what crosses that seam and how they will detect failures.
Today we will turn that seam into a well-framed architecture decision. We will document the problem and its boundaries, separate firm constraints from open questions, describe viable alternatives, and define how those alternatives should be judged. We will not select a design yet. A useful decision frame lets the affected teams challenge the same assumptions before anyone argues for a preferred technology.
Decide what question deserves an architecture decision
Not every implementation choice needs an architecture decision record (ADR). Changing a Java class name is unlikely to alter team responsibilities or a system quality. Choosing how invoices move from intake to reporting may affect reliability, tenant isolation, operational recovery, and the interface between two teams. It is consequential enough to document.
Microsoft’s Maintain an architecture decision record (ADR) offers a useful test for significance: record choices that affect system structure or important qualities, or that will be difficult to reverse. Read its guidance with the distinction between framing a decision now and recording an accepted decision later in mind.
Maintain an architecture decision record (ADR)
Microsoft Learn explains which choices merit an ADR and what a concise record needs to preserve.
In “Implement an ADR,” begin with the significance test. Continue through “Suggested characteristics of an individual record,” ending at the advice to keep records factual and on-topic. Focus on the problem statement, options, status, and rationale; we will leave the outcome open in this lesson.
A good frame is narrower than “design the invoice pipeline” but broader than “choose a queue.” For this pilot, the question is:
How should an invoice accepted by intake be handed off for reporting so the teams can make progress toward the customer-visible timeliness objective and recover when the handoff fails?
That wording identifies the boundary and the desired behavior without presupposing HTTP, a broker, or a reporting implementation. It also avoids assigning the entire 15-minute customer journey to the handoff. Time before API acceptance and time after reporting receives the invoice still count toward the customer’s experience.
An ADR template makes the distinction between a question and its eventual answer visible. The following MADR illustration shows where context, decision drivers, options, outcome, and consequences belong. We are working mainly in the context, drivers, and options portions; filling in “Decision Outcome” now would be premature.
Read the corresponding explanation in The Markdown ADR (MADR) Template Explained and Distilled. Its warning about comparing options at different levels of abstraction is especially relevant when a discussion mixes a handoff design with a particular cloud product.
The Markdown ADR (MADR) Template Explained and Distilled
Olaf Zimmermann explains the MADR sections we need to prepare a decision before choosing an option.
Under “Template Walkthrough,” read the template introduction through “Context and Problem Statement.” Then read the “Decision Drivers” and “Considered Options” subsections, from drivers through options. Stop before “Decision Outcome.” Notice why options must address the same problem at the same level of abstraction.
Write context that another team could verify
The context is not a history of every invoice service. It is the small set of facts and uncertainties that would change this choice. A proposed record for the pilot could begin:
Status: Proposed. Intake accepts invoices for two pilot customers. The product objective is for at least 95% of submitted invoices to be searchable in customer reports within 15 minutes. Intake and reporting are separately owned. This decision concerns the handoff of an accepted invoice to reporting, including acknowledgment and recovery when delivery or processing fails. It does not choose the customer integration method or the reporting query engine.
This paragraph gives the decision a boundary. It also exposes a measurement problem from earlier lessons: “submitted,” “accepted,” “received by reporting,” and “searchable” are different events. If we only timestamp API acceptance and delivery to reporting, we cannot demonstrate the customer-visible objective. The Product Manager and customer-integration owner must confirm the start event; the reporting team must confirm the query and timestamp that establish visibility.
Next, separate what is known from what must be checked. Otherwise, a plausible architecture diagram can quietly turn assumptions into requirements.
| Item to document | Current framing for the pilot |
|---|---|
| Objective | At least 95% of submitted pilot invoices searchable within 15 minutes; confirm the measurement window, exclusions, and customer-visible query. |
| Affected boundary | Intake hands accepted invoice information to reporting; both teams must agree on invoice and tenant identity, acknowledgment, and failure states. |
| Required controls | Preserve tenant isolation and auditability across the handoff. Security and privacy owners must confirm the applicable controls and evidence. |
| Operating constraints | The pilot has delivery and cost limits, but the relevant dates, capacity, and cost ceiling must be confirmed rather than invented in the ADR. |
| Material unknowns | Peak submission pattern, current reporting import behavior, available platform capabilities, and which team can initiate a replay or repair. |
A constraint rules out an option if it cannot be met: for example, an applicable tenant-isolation requirement cannot be traded away for faster delivery. A decision driver distinguishes acceptable options: lower recovery effort may matter greatly even if more than one design can meet the required controls. Some items need discussion before they can be classified. The 15-minute objective is a measurable end-to-end target; the teams still need evidence about how much of that time the handoff can consume. It is not automatically a 15-minute allowance for the intake team.
For each consequential unknown, record who can resolve it and what evidence would settle it. “Reporting supports timely ingestion” is too vague. “Reporting owner will demonstrate when a pilot invoice becomes visible through the authorized query, using correlated invoice IDs and timestamps” is verifiable. The Tech Lead can coordinate that evidence without claiming authority over reporting’s service or Product’s definition of success.
Describe alternatives without smuggling in a winner
Options should answer the same question. “Use a managed message broker” versus “use Java” is not a comparison: one is an infrastructure choice, the other a programming-language choice. Nor is “reliable design” a meaningful option unless its mechanism and responsibilities are described.
At the handoff boundary, two provisional alternatives are worth investigating:
| Candidate handoff | What the teams would build and operate | Viability question |
|---|---|---|
| Direct delivery with persisted retry | Intake retains an accepted invoice in a recoverable pending state and delivers it to a reporting-owned API. The teams define acknowledgment, bounded retries, duplicate handling, and escalation when delivery cannot complete. | Can reporting provide and operate an appropriate API, and can both teams demonstrate recovery within the end-to-end time budget? |
| Durable asynchronous channel | Intake durably records work to publish, while reporting consumes it from an agreed channel. The teams define publication and consumption failures, duplicate handling, retention, replay, and channel ownership. | Is a supported channel available for the pilot, and can the teams own and observe it without unacceptable cost or delivery risk? |
Both are candidate designs, not claims about the systems already in place. Persisting pending work matters for the direct option: comparing a fire-and-forget HTTP request with a durable channel would make the former a straw man. Likewise, the asynchronous option is not automatically reliable. It still needs a credible account of what happens if intake accepts an invoice but fails to publish it, or if reporting repeatedly cannot process it.
An existing scheduled reporting import might be a third candidate if discovery confirms it exists and can meet the required behavior. Until then, do not present it as an established option—or dismiss it merely because it sounds less modern. The earlier ownership map tells us whom to ask and which handoff behavior to inspect.
Keep solution details proportional to this decision. The frame needs enough detail to distinguish failure and ownership implications, but it need not choose retry intervals, a broker product, or a Java client library. Those choices may require separate decisions after the handoff approach is settled.
Define evaluation criteria before scoring designs
The product objective tells us why the decision matters, but not yet how to compare the candidates. Mark Richards’s Lesson 145 - Analyzing Tradeoffs illustrates the intermediate step: translate a business driver into architectural qualities, then inspect concrete situations in which options behave differently. His payment-service example is not a design recommendation for invoices; watch for the method of reasoning.
Lesson 145 - Analyzing Tradeoffs
In “Lesson 145 - Analyzing Tradeoffs,” Mark Richards connects a business driver to architectural qualities and uses scenarios to reveal costs that a simple pros-and-cons list could miss.
Watch business to qualities for the translation from time to market into testability, maintainability, and deployability. Then watch scenario tradeoffs for how changing requirements expose different strengths and weaknesses. Apply the method, not the payment-service conclusion, to the invoice handoff.
For the pilot, a criterion should say what matters, under what condition, and what evidence would reveal it. “Scalable” alone gives reviewers nothing to examine. “During the forecast submission burst, can accepted invoices continue to reach the searchable state within the agreed time budget?” is a question the teams can test. The forecast and budget remain open inputs until their owners confirm them.
The following criteria establish an evaluation plan, not scores:
| Criterion | Question for both options | Evidence to seek |
|---|---|---|
| Customer-visible timeliness | How does handoff delay affect the proportion searchable within 15 minutes of submission? | Correlated submission, acceptance, handoff, and authorized-query timestamps; agreement on the denominator. |
| Reliability and recovery | What happens if reporting is unavailable, a delivery is duplicated, or one invoice repeatedly fails? | Failure-path walkthroughs and tests showing retained work, safe retry or replay, and a way to identify stuck invoices. |
| Tenant isolation and auditability | Can the correct tenant be established and enforced throughout the handoff, with an adequate record of processing? | Interface review and security-approved tests and audit evidence for the affected trust boundaries. |
| Burst capacity | Can each stage handle the forecast burst without silently losing work or exhausting the time budget? | Representative load results and relevant service or platform limits. |
| Operability | Can on-call teams find an invoice’s state and determine which team should act? | A trace across team boundaries, alerts for stalled progress, and an agreed support route. |
| Cost and delivery feasibility | What infrastructure, implementation, and ongoing operating work does each option require within the pilot’s limits? | Platform cost estimates, team estimates, dependency commitments, and confirmation of the actual limits. |
Some criteria will become pass/fail gates once their requirements are confirmed—for example, applicable security controls and an acceptable path to the product target. Others distinguish options that pass: operational complexity, cost headroom, or ease of delivering the pilot. Do not give a criterion a numerical weight merely to make a comparison look objective. First ask Product, Security, Platform, Intake, and Reporting which requirements are mandatory, what evidence they will accept, and who has authority to approve a change.
Concrete scenarios make this frame useful in a design review. A normal invoice should become searchable for the correct tenant. A burst should not conceal growing handoff delay. If reporting is unavailable after intake acceptance, work must remain discoverable and recoverable. If a retry repeats an invoice, reporting must not produce an incorrect customer result. These scenarios apply to both candidates; the next lesson will examine their differing responses in depth.
Conclusion
An architecture decision is well framed when reviewers can identify the exact question, the affected boundary, confirmed constraints, consequential unknowns, viable alternatives, and evidence-based criteria—without needing to guess which answer the author favors. For the invoice pilot, the handoff decision cannot be separated from the customer-visible clock or from the teams that will detect and repair failures.
Keep this record Proposed while its assumptions and options are checked with the relevant owners. In the next lesson, we will use these criteria to evaluate the alternatives across scalability, reliability, security, cost, operability, and delivery constraints. Only after that comparison will we be ready to state and justify a decision in an ADR.