pa-10 — Architecture in Practice: ADRs, Design Reviews & Fitness Functions

The Apple JD's through-line is the architect's job: "software architecture and systems design," "software quality methodologies, including design review, code review, and testing strategies," and "mentor engineers and build consensus across teams on cross-cutting technical decisions." This capstone is about doing architecture — the practices that turn good designs into durable, evolvable systems other engineers build on.

The runnable artifact is fitness functions: automated architecture tests (no dependency cycles, layering rules, coupling budgets) that run in CI so the design's key properties are enforced mechanically, not policed by hand. The written artifacts are the ADR, RFC, and design-review templates in steps/ — the architect's tools for capturing decisions and building consensus.

1. What is it?

Being an architect is three loops:

1. Decide and record. Make cross-cutting decisions and capture them as ADRs (Architecture Decision Records): context, options considered, the decision, and consequences — so the why outlives you. Bigger or contested decisions get an RFC circulated for input.
2. Review and align. Run design reviews that pressure-test a proposal (surfacing the failure mode the author missed), and high-quality code reviews that teach and raise the bar. The goal is consensus, reached by argument + data + prototypes, not authority.
3. Enforce evolution. Encode the design's invariants as fitness functions — automated tests of architectural properties — so the system stays coherent as it grows ("evolutionary architecture"). A paved road + a fitness function beats a review bottleneck.

The leverage of an architect is org-shaped: you make the right thing the easy thing for many teams (Conway's Law, Team Topologies).

2. Why does it matter?

• Decisions decay without records. Six months later, nobody remembers why you chose at-least-once + idempotency over a queue, so someone "fixes" it and reintroduces the bug. An ADR is cheap insurance against re-litigating settled decisions and against losing the reasoning when people leave.

• Architecture rots without enforcement. Every well-layered system drifts: a deadline-pressured PR adds a domain → infra dependency or a cycle, and reviews miss it. A fitness function in CI makes that regression fail the build — the same idea as pa-02's contract gate and pa-01's cycle check, generalized. This is how an architecture survives contact with 50 engineers.

• Consensus is the real bottleneck, and it's a skill. The hard part of a cross-cutting decision (the eventing standard, the SLO framework) is aligning teams with different incentives. Architects who mandate get ignored or routed around; architects who build consensus (write the RFC, prototype, let data win, run the review well) get adoption. The JD names this explicitly.

• Mentorship and reviews are leverage, not overhead. An architect who only ships code scales to one person's output; one who raises the bar via reviews and paved roads multiplies the whole org. "Enable other engineers to build better products, faster" is the role.

3. How does it work?

Fitness functions (architecture as tests)

A fitness function is an executable check of an architectural property. The engine here defines Rules — NoCycles, Layering, MaxFanOut — and Evaluate(graph, rules) runs them, returning a Report whose Passed is false if any rule is violated. Wire it as a TestArchitecture in CI and the build fails when:

• a dependency cycle appears (the distributed-monolith smell, pa-01),
• a layering rule is broken (domain → infra),
• a coupling budget (max fan-out) is exceeded.

These are objective, automated versions of things reviews try (and fail) to catch by eye. The same pattern enforces contract compatibility (pa-02), test coverage, performance budgets, and naming conventions.

ADRs and RFCs (capturing the why)

An ADR is a short, immutable record per decision (see steps/01-adr-template.md):

# ADR-NNN: <title>
Status: proposed | accepted | superseded by ADR-MMM
Context:   the forces and constraints (the -ilities in tension)
Decision:  what we chose
Alternatives considered:  with why we rejected them
Consequences:  what becomes easier/harder; what we'll revisit

ADRs live in the repo, are versioned, and form a decision log. An RFC is the heavier, pre-decision document circulated to build consensus on a big/contested choice.

Design & code reviews (raising the bar)

A good design review uses a checklist (see steps/02-design-review-checklist.md) to pressure-test boundaries, contracts, data/consistency, failure modes, rollout, and observability before code is written. Code review is where standards propagate and engineers grow — review to teach, not just to gate. Both are testing strategies in the JD's sense.

Building consensus (the meta-skill)

Authority doesn't scale across teams. The architect's toolkit: write it down (RFC/ADR), prototype to replace opinion with evidence, run the review so the room reaches the decision, give first-mover teams a paved road, and let the fitness function (not your nagging) enforce it afterward.

4. Core terminology

5. Mental models

• An ADR is a flight recorder for decisions. When something looks wrong later, you read the black box: what did we know, what did we weigh, what did we choose and why. Without it, every old decision is a mystery someone will "fix" into a regression.

• Fitness functions are unit tests for the architecture. You don't trust developers to remember not to break the null-check; you write a test. Same with "no domain→infra dependency": don't trust reviews, write the fitness function. Green build = the architecture still holds.

• An architect is a gardener, not a king. You don't command the plants to grow in rows; you set up trellises (paved roads), pull weeds (fitness functions), and prune (reviews) so the system grows the right shape on its own. Command-and-control architecture gets routed around.

• Consensus is cheaper than authority. Mandating a standard creates malicious compliance and shadow workarounds; building consensus (write, prototype, review, let data win) creates adoption. The slow way is the fast way at org scale.

6. Common misconceptions

• "The architect makes the decisions; teams implement them." That's the ivory-tower anti-pattern. Architects who don't build consensus get ignored; the role is influence + enablement, not command. The JD says "build consensus" for a reason.

• "Document the architecture in a big wiki." Big design docs go stale the day they're written. ADRs (small, per-decision, immutable) + fitness functions (executable, always current) beat a 60-page wiki nobody reads.

• "Reviews catch architecture violations." Humans miss cycles, layering breaks, and coupling creep under deadline pressure. Automate the objective checks (fitness functions); spend review time on judgment the machine can't make.

• "More standards = better architecture." Standards without paved roads and enforcement are ignored; standards that make the right thing harder than the wrong thing actively backfire. Enable, then enforce mechanically — don't just publish rules.

• "Architecture is up-front; then you build." Evolutionary architecture treats it as a continuously tested property — fitness functions let it change safely as requirements do, rather than ossify or rot.

7. Interview talking points

• "How do you make and record architecture decisions?" ADRs (context, decision, alternatives-with-why, consequences) in the repo for the decision log; RFCs circulated before big/contested decisions to build consensus. The value is the preserved why — so decisions aren't re-litigated or accidentally reverted.

• "How do you keep an architecture from rotting?" Fitness functions in CI: automated tests for no-cycles, layering, coupling budgets, contract compatibility (pa-02). The build fails on regression, so the architecture is enforced mechanically, not by hand. Cite evolutionary architecture.

• "How do you drive a decision across teams you don't manage?" Influence, not authority: write the RFC, prototype to make it concrete, run the design review so the room owns the outcome, give the first teams a paved road, and let a fitness function enforce it afterward. Let data settle contested points.

• "What makes a good design/code review?" Design review: a checklist pressure-testing boundaries, contracts, data/consistency, failure modes, rollback, and observability before build. Code review: teach and raise the bar, not just gate. Both are testing strategies; both are mentorship.

• "How do you mentor / scale yourself?" Paved roads (the right thing is the easy default), fitness functions (enforcement without bottlenecking), and reviews-as-teaching. The architect's output is other engineers' improved output, not just their own code.

• "Tell me about a wrong architecture decision." (Behavioral.) Own it, show the ADR/data that revealed it, and the migration (gw-12) that fixed it. Intellectual honesty + a recovery plan is the signal.

8. Connections to other labs

• pa-01 / pa-02 — the cycle/layering and contract-compatibility checks here are the same analyses, packaged as CI fitness functions.
• gw-12 — a wrong decision becomes a migration; ADRs record the call, the rollout ladder executes the change.
• pa-08 (GitOps) — PR review of git changes is the change-control / consensus mechanism for the running system.
• Every lab's docs/analysis.md — written as a model ADR/design- review ("tradeoffs worth flagging," "what production adds"): the decision-record habit applied throughout the book.