Skip to content
notes.vinhnq.com

Search

System DesignSenior16 min read

Architecture docs part 2: ADRs, quality requirements, the risk register and an address component example

Review 11 cards
On this page

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_id so the capture flow is safe when the client retries (see Idempotency part 1).
  • verify_status and capture_method as explicit states rather than boolean flags; see how to store enums in Enums in the database and the API.
  • version for optimistic locking (write only if the version hasn’t changed) when the user and the verification job edit the same address.
  • verify_attempts and failure_reason so 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_id is blocked by address_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 an Idempotency-Key header or request_id in the body) returns the address with its verify_status.
  • GET /address-service/v1/addresses?owner_type=&owner_id=.
  • AddressVerified / AddressVerificationFailed events on Kafka keyed by owner_id to keep per-owner ordering; the payload carries address_id and version so 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 Accepted ADR.
  • 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, a version column 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.

  1. Problem, goals, scope and out of scope, constraints.
  2. Measurable quality requirements, because they drive the architecture.
  3. Context, containers, runtime views for the main use cases including failure paths, deployment.
  4. ADRs with the rejected alternatives and trade-offs.
  5. 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.