What makes an architecture reviewable?

We review systems for a living, and the reviews vary strangely in cost. One estate yields its structure in a day: the claims are checkable, the diagrams match the deploys, the questions have owners. Another, no larger, absorbs a month and returns fog. The difference is not documentation volume. It is a property we have come to call reviewability, and it is worth defining, because teams can build it on purpose.

what is reviewability?

A system is reviewable to the degree that claims about it can be checked at a cost proportional to their importance. Reviewable does not mean documented; we have reviewed estates with wikis the size of novels where no claim could be verified short of archaeology. It means that when someone asserts "the queue absorbs bursts", there exists a place to look: a dashboard, a load test, an incident record, a limit in code. The claim has an address.

where do claims live?

In reviewable systems, three places, in descending order of authority. In the running system itself: limits, timeouts and budgets expressed in configuration a reviewer can read. In records of the system under stress: load tests, incident reviews, the latency histograms we keep insisting people read. And in decision records that state not just the choice but the conditions under which it was expected to hold, which is what a decision record owes you. The unreviewable estate stores its claims in a fourth place: the memories of specific senior engineers, addressable only by meeting.

what would have to be true for a review to take a day?

Three conditions, each cheap at build time and expensive to retrofit.

The boundaries name themselves. Every interface a reviewer crosses has a contract somewhere checkable: a schema, an SLO, an owner. The price is discipline, not tooling; a one-page contract per boundary, kept current, costs each team an hour a quarter. The payoff is that a reviewer, or an incident responder at 3 a.m., which is the same skill under worse lighting, can traverse the estate without an interpreter.

The numbers carry their provenance. "Handles 10k per second" is reviewable only if the 10k names its test: date, shape, duration. A number without provenance costs a review meeting to run down; a number with it costs a glance. We have watched a diligence exercise stall for a week over a throughput figure that turned out to be aspirational. The aspiration was fine. The missing label was not.

The exceptions are listed, not discovered. Every estate has them: the service that bypasses the queue, the tenant with the custom path, the tables that replicate specially. Reviewable systems keep the exception list next to the rule. Unreviewable ones let each exception be found the interesting way, and a review that keeps finding exceptions stops believing the rules, at which point its cost curve bends upward and does not return.

what does it cost?

The objection is familiar: this is bureaucracy, and the team is shipping. Our observed prices, for what they are worth. The disciplines above cost a mid-size team perhaps two hours a week, paid continuously. Their absence costs nothing at all, for a while, and then it costs a diligence process that discounts the company for opacity, or an incident lengthened by every claim that had to be re-derived under pressure, or a review, ours, that bills the month the fog demanded. Reviewability is not for the reviewers. It is the property that makes the system legible to its own future operators, and the review is merely the day that property gets priced.

We were wrong about this once, and it is worth admitting: early in the practice we scored a beautifully documented estate highly and a sparse one poorly, then watched the sparse one sail through an incident its documents never mentioned, because its claims lived in the running system where responders could touch them. The wiki is not the system. The system is the system. Reviewability lives there, or it does not live.