Project 02. The ADR Pack and Reference Architecture

At a different engagement, a security reviewer read the model ADR and the topology ADR back to back and caught what six separate authors, on six separate days, had missed: the model ADR named a first-party vendor API, and the topology ADR — written two weeks later — pinned every prompt to a private endpoint inside the client's own tenancy. Nobody had checked the two files against each other before the review. The review stalled for three weeks while the architect traced every downstream decision that had assumed the wrong one was true, and the client's security team started asking, reasonably, what else in the pack disagreed with itself.

Illustrative composite. The engagement, the three-week stall and its cause are assembled for teaching, not a report of a real review.

Six decisions have accumulated in your Dossier since Lesson 04, and right now they live in six separate files written on six separate days. A buyer, a security reviewer or the engineering team that inherits the system will read them together, and they will find the places where one decision quietly assumes another was taken differently: a model chosen for a first-party API and a topology that forbids it, a retrieval design that needs an index in a region the ADR never mentions. This project closes the Decide stage by making those files agree and drawing the system they describe. You hand over three ADRs (model, augmentation, topology) and a reference architecture for your case: context and container diagrams in mermaid plus one request sequence, all in the Dossier. Work your own case if you have one; Harbor Mutual is the model answer, given in full below.

Brief

You are the architect for Harbor Mutual's claims-correspondence assistant, or for your own case with an equivalent set of inputs. The decisions taken in Lessons 04 to 09 are summarised here as inputs; your job is to record them as three consistent decision records and three consistent diagrams.

Constraint register excerpt (from 02-constraints.md):

R-03  Every outgoing letter cites the policy clauses it relies on.       owner: legal
R-04  Legal signs off the first release and wants "why this sentence".   owner: legal
R-05  Adjuster bookings write to a calendar owned by field operations.   owner: field-ops
R-06  Every customer-facing action is attributable to a named approver.  owner: audit
R-07  EU policyholder data is processed in the EU; UK under the group's
      transfer assessment (counsel, dated).                              owner: counsel
R-08  Claim documents are confidential; no vendor default retention.     owner: DPO
R-09  Platform team of four; no GPU operations experience.               owner: platform lead
R-10  Policy archive stays on-premises for the pilot.                    owner: archive owner

NFR budget excerpt (from 01-nfr-budgets.md): p95 time to a visible draft of eight seconds; citation accuracy measured on the golden set from Lesson 10; a per-letter cost ceiling the cost model in Lesson 11 will fill; availability for office hours in two time zones.

Decisions already taken, one line each, which your ADRs must record without contradiction:

• Model (Lesson 04): a mid-tier model from a family available on the private endpoint for drafting and evaluation; the smallest tier of the same family as the router; chosen by the citation eval, not the leaderboard; reversed if the eval on the endpoint's model version drops below the budget.
• Context (Lesson 05): a stable cached prefix carrying the letter-class instructions and output schema; per-request claim summary and clauses; structured output at every boundary.
• Augmentation (Lesson 06): retrieval over the policy wording with document-level access rules and a freshness rule; no fine-tuning; long context rejected because the archive exceeds any window and freshness would break.
• Pattern (Lesson 07): routing into a prompt chain with one evaluator step, a conditional booking branch, human gates on book_adjuster_visit and send_letter.
• Boundaries (Lesson 08): calendar and email as MCP servers with on-behalf-of tokens; a read-only broker for the legacy claims system; one gateway in the tenancy.
• Topology (Lesson 09): a private endpoint in the tenancy's EU region, in-geography fallback only, single tenant with two populations separated by access rules.

The Rule This Lab Tests

Use the topology ADR to pin the model ADR's choice when the constraint register carries a residency or retention line naming a region; otherwise the model ADR chooses freely by the citation eval and the topology follows it. Y is observable in your own register: does a row cite a residency, retention or data-processing-location obligation with an owner, or not?

Harbor Mutual's register carries R-07 and R-08, so the topology ADR governs: ADR 0001 below is written around the EU private endpoint's model family, not the leaderboard leader, and its Rejected section says so.

Steps

1. Write adr/0001-model.md. Use the ADR skeleton below. The Context section quotes the NFR budget lines the model must meet; the Decision names the family, the tier per role (router, drafter, evaluator) and the platform it runs on; Rejected names the leaderboard leader and the budget it broke; the Review condition is an eval score on the endpoint's current model version.
2. Write adr/0002-augmentation.md. Context quotes the register lines about citations and the archive; Decision records retrieval with access rules and freshness; Rejected covers fine-tuning (freshness, no clause-level provenance) and long context (archive size, cost per letter); Review condition is a retrieval metric from Lesson 06 falling below its budget.
3. Write adr/0003-topology.md. Reuse the Lesson 09 skeleton. Its Context must quote R-07 to R-10, and its Decision must place every container the diagrams draw: gateway, index, logs, endpoint, MCP servers.
4. Draw diagrams/context.mmd. A flowchart LR with the people and external systems around one node for the system. Every edge is labelled with what moves, and nothing crosses a boundary the integration specification does not name.
5. Draw diagrams/container.mmd. A flowchart TB with the tenancy as a subgraph and every container from the ADRs inside it: service, workflow runtime, gateway, index, ingestion, MCP servers, traces, endpoint. External systems sit outside the subgraph. No container appears here that no ADR placed.
6. Draw diagrams/request-sequence.mmd. A sequenceDiagram for one request end to end, showing the router, the retrieval, the draft, the evaluator and the gate, with the identity each call carries.
7. Cross-check. Read the six files together and fix every place where a name, a region, a model tier or an identity differs between an ADR and a diagram. Add one line per ADR to the Dossier's index in README.md.

Model answer: Harbor Mutual

The three ADRs are compressed here to their load-bearing sections; the topology ADR is given in full in Lesson 09 and is not repeated.

Decide now: the citation eval on the golden set has two live candidates for the drafter and evaluator roles — the leaderboard-leading model, reachable only through a first-party API, and the mid-tier model in the same family already running on the EU private endpoint ADR 0003 places. Before reading the ADR below, pick one and name what choosing it costs.

The leaderboard model scores highest on raw citation accuracy, but reaching it means sending prompts outside the tenancy ADR 0003 has already fixed to the EU region under R-07, or waiting on a vendor integration with no committed date; at pilot volume it also runs over the per-letter cost ceiling NFR-05 sets, for a citation gain the golden set does not show once the mid-tier model catches up. Choosing it would cost Harbor Mutual its EU residency guarantee — not a rounding error on a budget line. The mid-tier model on the private endpoint gives up that small accuracy edge and keeps every prompt in-region and under the cost ceiling: the trade the model ADR actually takes.

# ADR 0001 · Model selection — Harbor Mutual claims correspondence
Status: accepted · Date: 2026-09-09 · Owner: solutions architect

## Context
NFR-02 citation accuracy on the golden set; NFR-03 p95 draft under eight seconds;
NFR-05 cost per letter under the ceiling in 08-cost-model.md. R-07/R-08 restrict the
platform to the private endpoint chosen in ADR 0003.

## Decision
Drafter and evaluator: the mid-tier model of the family available on the EU private
endpoint, at the version current on the decision date. Router: the smallest tier of the
same family. Prompt caching on the stable prefix from 03-context-spec.md.

## Rejected
The leaderboard-leading model: over the latency budget on the endpoint and over the
cost ceiling at pilot volume, with no measurable citation gain on the golden set.
Open-weight self-hosting: excluded by ADR 0003 (R-09).

## Review condition
Citation accuracy on the endpoint's current model version falls below NFR-02 on the
weekly eval, or the endpoint retires the version with no equivalent within one quarter.

# ADR 0002 · Augmentation — Harbor Mutual claims correspondence
Status: accepted · Date: 2026-09-09 · Owner: solutions architect

## Context
R-03 every letter cites its clauses; R-10 the archive is on-premises; the archive
exceeds any context window and policy wordings are versioned.

## Decision
Retrieval over policy wording: nightly ingestion from the archive (parse, chunk by
clause, embed, record document version), document-level access rules per population,
freshness rule of 24 hours, hybrid search with reranking, clause identifiers returned
with every chunk so the evaluator can verify citations.

## Rejected
Fine-tuning: no clause-level provenance, and a wording change would require retraining.
Long context: the archive does not fit, and cost per letter would exceed the ceiling.

## Review condition
Recall at the configured depth on the retrieval golden set falls below the Lesson 06
budget, or a superseded wording is cited in production more than once in a month.

The context diagram shows who touches the system and which external systems it touches; nothing inside the system appears yet.

The container diagram opens the system node. Watch for the subgraph boundary: everything that holds prompts, logs or vectors sits inside the EU tenancy, and the three external systems sit outside it.

The sequence follows one coverage-position letter from request to the gate. Every call to the model passes the gateway, every read of the claim carries the adjuster's token, and the letter is never sent inside this sequence.

Acceptance

• adr/0001-model.md, adr/0002-augmentation.md and adr/0003-topology.md exist, each with Status, Date, Owner, Context, Decision, Rejected and Review condition sections.
• Every Context section quotes at least one register line or NFR budget by identifier.
• Every Rejected section names the option and the observable fact that eliminated it.
• Every Review condition is a measurement or an event, not a date alone.
• Vendor terms in the topology ADR carry the date they were checked.
• diagrams/context.mmd has one system node, every actor and external system, and a labelled edge for every crossing.
• diagrams/container.mmd places every container named in any ADR and no container named in none; the tenancy is a subgraph.
• diagrams/request-sequence.mmd shows the identity on every read and stops at the gate for any high-risk tool.
• All three diagrams parse; every label is quoted; no style or classDef.
• Model tier, region, gateway placement and identity mechanism are named identically across the six files.
• README.md lists the three ADRs with one line each.

Rubric

Exercises

1. Hand your six files to someone who has not read the lessons and ask them to draw the container diagram from the three ADRs alone. Every container they place that your diagram lacks, or fail to place that your diagram has, is an ADR that does not say where its decision lives.
2. Pick the review condition in any of your ADRs that is hardest to measure today and write the one dashboard panel or contract calendar entry that would surface it. If no such panel can exist, the condition is a wish, and the ADR needs a measurable one.

Key Takeaways

• Record each decision with the register line that forced it and the measurement that would reverse it.
• Make the three ADRs and three diagrams agree on every name, tier, region and identity.
• Draw the context first, then open the system into containers, then follow one request through them.
• Place a container only where an ADR put it; a diagram is not the place to make a new decision.
• Write tensions between decisions into both files they touch, with a review condition in each.

What You Have Now

Three ADRs (model, augmentation, topology) and a reference architecture for your case: context and container diagrams in mermaid plus one request sequence, all in the Dossier. They live at dossier/adr/0001-model.md, dossier/adr/0002-augmentation.md, dossier/adr/0003-topology.md, dossier/diagrams/context.mmd, dossier/diagrams/container.mmd and dossier/diagrams/request-sequence.mmd, indexed from the Dossier's dossier/README.md; the lab's checker looks for all of those at those paths. Together they close the Decide stage of the Frame / Decide / Prove / Run loop: every design decision is now written down with the condition that reverses it, and the system is drawn at three levels of detail. Module 3 opens the Prove stage on this pack: Lesson 10's eval plan tests the review conditions, Lesson 11's cost model prices the containers, and Lesson 12's threat model redraws the container diagram as trust boundaries and maps controls onto its edges.