Architecture docs series: 1. arc42, C4 and docs-as-code · 2. ADRs, quality requirements and an address component example
Part 1 set up the document frame (arc42), the C4 diagrams, and the runtime and deployment views. This part covers three things code never says on its own: why this design was chosen (ADRs), how much it has to deliver (quality requirements), and which risks the team accepts (the risk and technical-debt register). It ends with a sample solution design for an address component, with a schema run on PostgreSQL 16.
At a glance:
flowchart LR
D[Decision] --> ADR["ADR (Accepted)"]
ADR --- C["Context, Decision, Alternatives, Consequences"]
ADR -->|change of mind| N["New ADR: Supersedes"]
Q[Quality requirement] --> M["Measurable: load, p99, errors"]
M --> A[Actual column]
A -->|misses target| R[Risk register]
R --> O["Owner + review date"]
1. ADRs: recording decisions and their reasons
Key idea: an ADR (Architecture Decision Record) captures one architectural decision with its reasons, the rejected options and the price paid, so later readers understand why the system is the way it is.
- Michael Nygard’s original format: Title, Status, Context, Decision, Consequences.
- The course template collects ADRs into a table: order, title, the decision with its trade-off, positive and negative consequences, status, and a link to the details.
- The example ADR-004 picks generic administrative-level columns over per-country columns, and skips a fourth level on YAGNI grounds (“you aren’t gonna need it”: don’t build it until it’s needed).
Full sample ADR: ADR-004 storing addresses by generic administrative levels
# ADR-004: Store addresses in generic administrative-level columns, not per-country fields
Status: Accepted (2026-11-10)
## Context
Addresses are captured in several countries, each with a different administrative hierarchy
(province/district/ward, state/city, province/city/barangay). The old design had dedicated
columns per country, so every new market meant schema and code changes in 4 services.
## Decision
Use admin_level1..3 columns (level 1 is the largest) plus country_code; what each level means
per country lives in master data. No admin_level4: no market needs it yet (YAGNI); adding a
nullable column later is a compatible change.
## Alternatives
- Per-country columns: self-explanatory, but every new country is a migration.
- One free-form JSONB column: the most flexible, but loses constraints, is hard to index and validate.
## Consequences
+ Opening a new country only needs master data, no schema change.
+ One API and one validator for every country.
- Column names aren't self-explanatory; readers need the per-country mapping table.
- A country with more than 3 levels needs a migration (accepted, see risk R-03).
Where ADRs live: in the repo or on a wiki
Another short sample ADR, written after a disagreement in code review: exercise 2 of Code review: resolving disagreements and two worked reviews records the decision to use a 2-second timeout for the fraud check on a synchronous payment flow, with the context in numbers (a 2 s p99, 200 worker threads), the rejected options and why, and the conditions for revisiting it.
2. Quality requirements: measurable, or they don’t exist
Key idea: “fast and stable” can’t be tested, so it can’t drive any decision. Every quality requirement needs a number, the conditions and the way it’s measured.
The course template uses a table: context, source, metric, expected, actual. The original row “Payment | end users | TPS | 1500” is missing a lot; a measurable version:
| Context | Source | Metric | Expected | Actual | How it’s measured |
|---|---|---|---|---|---|
| Create payment, peak hours | End users via mobile | Throughput sustained for 15 min | ≥ 1,500 TPS | 1,720 TPS | k6 load test on staging sized like prod |
| Create payment, peak hours | End users | Latency | p99 ≤ 300 ms at 1,500 TPS | p99 = 410 ms | Same test; histogram at the API gateway |
| Create payment | End users | 5xx error rate | ≤ 0.1% | 0.02% | Same test |
| Payment Service | Ops | Monthly availability | ≥ 99.95% (≈ 22 min downtime/month) | 99.97% | SLO from synthetic probes |
| Primary DB failure | Ops | RPO / RTO | RPO = 0, RTO ≤ 5 min | Not yet drilled | Quarterly failover drill |
The Actual column turns the table from a wish list into a check. The latency row is missing its target and the failover row hasn’t been proven: both go into the risk register in the next section. (RPO: the most data you may lose; RTO: the longest you may take to recover.)
Quality requirements are one of the four groups of architectural drivers; a table of how much infrastructure each extra “nine” of availability costs is in Pragmatic software architecture: architectural drivers. The Expected column should come from a back-of-the-envelope estimate (average QPS, peak, storage), not a guess. To make the availability row operational, turn it into an SLI, an SLO and an error budget, as in Design principles: scalability, performance and availability.
arc42 recommends writing each requirement as a quality scenario: who triggers what, under which conditions, how the system responds, and how that’s measured.
arc42’s six-part quality scenario and an example
The six parts: source (who), stimulus (what happens), environment (under which conditions), artifact (which part is affected), response (what the system does), response measure (how it’s measured).
Example: “When a Kafka broker (artifact) dies (stimulus) during peak hours (environment), payment creation (response) keeps working and no acknowledged event is lost (measure: 0 lost events, p99 rises by no more than 2× for 1 minute).”
3. The risk and technical-debt register
Key idea: the register records what the team knows isn’t right yet, so “everyone knows, nobody acts” becomes owned work with a deadline.
The template: description, priority, impacted stakeholders, solution, status. Technical debt is a shortcut taken now that must be paid back later.
| ID | Risk / debt | Priority | Impact | Solution | Status |
|---|---|---|---|---|---|
| R-01 | Payment creation p99 is 410 ms, above the 300 ms target | High | End users, Payment team | Move the synchronous fraud-check call to async | In progress |
| R-02 | DB failover never drilled, RTO unproven | High | Ops, every customer | Drill on staging, then on prod in off-peak hours | Scheduled |
| R-03 | Countries with more than 3 administrative levels need a migration | Low | Market-launch team | Add a nullable admin_level4 when needed |
Accepted |
| TD-01 | Email sent inside the booking transaction | Medium | End users (wrong emails) | Move to a transactional outbox | Backlog |
The table only helps when every row has an owner and a review date. “Accepted” is a valid status, but it must say who accepted it and why.
4. Example: a solution design for an address component
Key idea: a solution design goes from problem, goals and scope to schema and contracts; every special column in the schema answers a specific risk.
Rebuilt from a real-world document, with identifying information removed.
- Problem: every country and channel captures addresses differently; the data is inconsistent, hard to verify, and needed in several flows.
- Goal: one standardised, localisable address component that is the single source of truth and validates against administrative-area master data.
- Scope: mobile and web, the onboarding and profile-update flows (both need addresses). Out of scope: geocoding, delivery addresses.
- Assumptions: administrative master data exists and is correct; no new infrastructure is needed.
What’s worth learning (the original’s data-type mistakes are in the folded block at the end of this section):
- Generic administrative-level columns (
admin_level1..3) instead of per-country names (ADR-004 in section 1); the decision not to add a fourth level is recorded with its reason. - A UNIQUE
request_idso the capture flow is safe when the client retries (see Idempotency part 1). verify_statusandcapture_methodas explicit states rather than boolean flags; see how to store enums in Enums in the database and the API.versionfor optimistic locking (write only if the version hasn’t changed) when the user and the verification job edit the same address.verify_attemptsandfailure_reasonso operations can answer “why has this address never been verified?”.
The PostgreSQL 16 schema as run, the results and the API/event contracts
The original document has all the parts discussed so far: context and container views (current and target), sequence diagrams for the two capture methods (manual entry, and extraction from a proof-of-residence document), fetching an address, the database design, the API contract and the event contract.
The schema, rewritten for PostgreSQL and run on PostgreSQL 16:
CREATE TABLE address (
id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
request_id uuid NOT NULL UNIQUE, -- idempotency: a retry can't create a second row
owner_type text NOT NULL, -- CUSTOMER, MERCHANT...
owner_id bigint NOT NULL,
capture_method text NOT NULL CHECK (capture_method IN ('MANUAL', 'PROOF_OF_RESIDENCE')),
verify_status text NOT NULL DEFAULT 'UNVERIFIED'
CHECK (verify_status IN ('UNVERIFIED', 'VERIFIED', 'FAILED')),
channel text NOT NULL, -- MOBILE, WEB, BACK_OFFICE
country_code char(2) NOT NULL CHECK (country_code ~ '^[A-Z]{2}$'), -- ISO 3166-1 alpha-2
admin_level1 text, -- province / state
admin_level2 text, -- district / city
admin_level3 text, -- ward, commune / barangay
address_line1 text NOT NULL, -- house number, building
address_line2 text, -- street, village
postal_code text,
latitude numeric(9,6) CHECK (latitude BETWEEN -90 AND 90),
longitude numeric(9,6) CHECK (longitude BETWEEN -180 AND 180),
verify_attempts smallint NOT NULL DEFAULT 0,
failure_reason text,
version int NOT NULL DEFAULT 0, -- optimistic locking
created_at timestamptz NOT NULL DEFAULT now(),
updated_at timestamptz NOT NULL DEFAULT now()
);
CREATE INDEX address_owner ON address (owner_type, owner_id);
-- Optimistic lock: only update if nobody changed it first
UPDATE address SET verify_status = 'VERIFIED', version = version + 1, updated_at = now()
WHERE id = 1 AND version = 0; -- test run: 1 row; a second statement with version = 0: 0 rows
Test run results:
- Re-inserting the same
request_idis blocked byaddress_request_id_key. country_code = 'vn'is rejected by the check constraint.- Of two updates with
version = 0, only one succeeds.
API and event contracts:
POST /address-service/v1/addresses(with anIdempotency-Keyheader orrequest_idin the body) returns the address with itsverify_status.GET /address-service/v1/addresses?owner_type=&owner_id=.AddressVerified/AddressVerificationFailedevents on Kafka keyed byowner_idto keep per-owner ordering; the payload carriesaddress_idandversionso consumers can ignore stale events.
Reviewing the original schema: coordinates, country_code, time zones
Exercises
Exercise 1: Write an ADR for a decision in your pet project
Task (paraphrased): pick a decision you’ve made in your project (for example, UUID vs bigint primary keys) and write an ADR with Context, Decision, Alternatives and Consequences.
Sample solution for exercise 1: ADR-002 bigint and UUIDv7
Sample solution (abridged):
# ADR-002: Internal bigint identity keys, UUIDv7 as the public id
Status: Accepted
## Context
Ids appear in URLs; sequential ids reveal order volumes and let people probe other users' ids.
UUIDv4 primary keys cause random writes into the B-tree and bloated indexes.
## Decision
bigint identity for primary and foreign keys; a UNIQUE public_id uuid column (v7, generated in
the app) used in the API.
## Alternatives
- bigint only: simplest, but leaks information through URLs.
- UUIDv4 only: leaks nothing, but large indexes and fragmented inserts.
- UUIDv7 only: near-sequential so inserts are fine; still 16 bytes in every foreign key.
## Consequences
+ The API doesn't reveal volumes; internal joins use 8-byte keys.
- Two identifiers per row; every API must look things up by public_id.
Exercise 2: Turn a vague requirement into a quality scenario
Task: product says “the homestay search page must be fast and survive the Tết holiday traffic”. Rewrite it as a measurable quality requirement.
Solution for exercise 2: a quality requirement for homestay search
“At 2,000 search requests per second sustained for 30 minutes (4× last year’s peak), with 200,000 homestays and 50 million availability rows, GET /homestays has p95 ≤ 400 ms, p99 ≤ 800 ms and a 5xx rate ≤ 0.1%, measured by a load test on staging sized like production; when database reads slow down, the system serves cached results no older than 5 minutes instead of failing.”
Then go back to product to confirm each number.
Remember
- Name the parts of an ADR and explain why one without Alternatives isn’t an ADR.
- Know what to do when you change your mind about an
AcceptedADR. - Rewrite “it must be fast” as a requirement with a percentile, load level, duration and measurement environment.
- Explain the Actual column and how a row that misses its target ends up in the risk register.
- Say why the address schema has a UNIQUE
request_id, aversioncolumn and generic administrative levels.
Interview questions
Junior
What is an ADR and what does it contain?
A short note about one architectural decision, so later readers understand why the system is the way it is.
It contains: title, status, context (the problem and constraints), the decision, the alternatives considered, and both positive and negative consequences.
What is a risk and technical-debt register for?
It records what the team knows isn’t right yet, turning “everyone knows, nobody acts” into owned work.
It covers risks (an undrilled failover, latency above target) and technical debt (shortcuts taken), with priority, who is affected, how to fix it, status, an owner and a review date. “We accept the risk” becomes a decision someone signed off.
Mid
Why is “the system must handle 1,500 TPS” not yet a good requirement?
Because without measurement conditions it can’t be verified.
It’s missing the request type, payload, how long it’s sustained, a percentile latency threshold, error rate, data volume and the measurement environment. A system doing 1,500 TPS for 10 seconds with a multi-second p99 still “passes”. Write it as a quality scenario with a concrete response measure.
What do you do when you change your mind about a decision that already has an ADR?
Write a new ADR marked Supersedes the old one, set the old one to Superseded, and leave its content untouched.
That way the history of reasoning survives: anyone can see what was decided back then, why, and why it later changed.
Senior
In what order do you present a solution design to reviewers?
From the problem and requirements to the decisions, then risks and open questions; reviewers should spend their time on requirements and decisions, not class names.
- Problem, goals, scope and out of scope, constraints.
- Measurable quality requirements, because they drive the architecture.
- Context, containers, runtime views for the main use cases including failure paths, deployment.
- ADRs with the rejected alternatives and trade-offs.
- Risks, technical debt, and the open questions I need reviewers to decide.
Give an example of a quality requirement that changes the architecture.
“Payment creation p99 ≤ 300 ms at 1,500 TPS” when the synchronous fraud-check call alone takes 200 ms at p99.
That requirement forces the fraud check to go async (let it through, check afterwards, reverse if needed) or a latency budget per hop. Similarly, “RPO = 0” forces synchronous replication, at the cost of higher write latency. Quality requirements are what choose between options, so they must be settled before the design.
Useful phrases for interviews
- “This ADR records the decision, the options we turned down, and what we’re giving up.”
- “We never rewrite an accepted ADR; a new one supersedes it so the history stays intact.”
- “‘Fast’ isn’t a requirement; give me a percentile, a load level and how long it has to hold.”
- “The actual column shows we’re missing the latency target, so that went straight into the risk register.”
- “Accepting a risk is fine, as long as it has an owner and a review date.”
- “We modelled addresses with generic administrative levels, so a new country is a master-data change, not a migration.”
- “Six decimal places is about eleven centimetres, which is more than enough for an address.”
- “Whether verification fails open or closed is a business call, so product signs off on it in an ADR.”
Notes based on the Advanced Backend course (Ronin Engineer), rewritten in my own words.