Capstone: The Design Document

You have been keeping a document since the start of Part III, one entry per chapter, and this is where it becomes the point. The task is to assemble Courtyard’s design document as a revision log: twenty entries, one per chapter, each with the same three fields you have been filling in all along.

• What ran out, the resource that forced the change. CPU, disk, read throughput, write throughput, certainty, entry points, statelessness, the origin, the speed of light, connections, the feed query, one region, coordination, the schema’s owners, engineer-hours, the failure budget, the request’s time budget, knowability, agreement itself.
• What changed, the one rung you added. A bigger machine; separated tiers; read replicas; sharding; quorums; a load balancer; externalised state; caching; the edge; a connection tier; fan-out; multi-region; services; data ownership; a gateway; resilience patterns; asynchronous work; observability; consensus.
• What can now fail that couldn’t before, the honest third field. Every fix bought capacity and introduced a failure mode, and this field names it. It is the field that separates someone who has read about systems from someone who understands them.

A revision log in this shape does something that a static architecture diagram cannot, which is to record why. Anyone can draw the final picture: a gateway, some services, sharded and replicated databases, a CDN, a queue, a consensus kernel. What the picture does not show is that every box was added under duress, to relieve a specific exhausted resource, at the cost of a specific new failure. The final architecture is not a design that someone chose. It is the accumulated residue of twenty forced moves, and the revision log is the only form that carries the forcing.

The log also protects against the two most common mistakes in architecture. The first is copying the final picture, building a fifty-microservice, multi-region, consensus-backed system on the first day because that is what real systems look like, when the resource that would justify any of it has not run out. The log makes visible that every box has a precondition: you do not add it until its “what ran out” is true. The second mistake is forgetting the third field, adding a capability and being blindsided by the failure it introduced, because nobody asked what could now go wrong. The log makes the third field mandatory.

There are two tests of whether you have done it well, and they mirror the tests of Part I’s capstone. The first is that every change traces to an exhausted resource. If a revision’s “what ran out” field is vague or absent, if you added something because it seemed like good practice rather than because a measured resource hit its ceiling, cut it, or find the real resource. Nothing in a good design document exists without a forcing function.

The second is that every change names its new failure. If a revision’s third field is empty, you have not finished thinking. There is no free move in this part. Chapter 1’s “no new failure” was the only one, and the point of that chapter was that it would be the last time. Every other change trades a solved problem for a new one, and if you cannot name the new one you do not yet understand the change, and you will meet the failure in production instead of on paper.

When every revision has a real resource in the first field and a real failure in the third, you have something better than an architecture. You have the reasoning behind one, and it is portable to any system you will ever build. The next system will not be Courtyard, and it will not need these twenty moves in this order, but it will run out of things, one at a time, and each time you will ask the same three questions. That habit is the whole of what this part had to teach.

There is one more chapter, a bonus, set after everything here has settled. Courtyard adds a feature unlike any payload in the book: a request that takes a minute to answer, on hardware too scarce to replicate, streaming its reply a piece at a time. It is not a new rung. It is the whole tower seen under a third kind of load, and it is worth reading last because you now have the other two kinds to compare it against.