The Cathedral is the architectural specimen most likely to appear on a whiteboard, least likely to appear in production, and most useful when it appears on neither but on a piece of paper labelled “design document, status: draft.”
It is the complete, beautiful, internally consistent system that solves all known problems, several unknown ones, and a few that the cathedral itself invented during its design phase. It has wings. It has chapels. It has, in the more advanced cases, flying buttresses connecting its own subsystems to itself across architectural voids that nobody asked for and that the cathedral cannot, on close inspection, justify.
The Cathedral is what the Squirrel sees when riclib says “we should clean up the sidebar.”
“The cathedral was not wrong. The cathedral was early.”
— The Lizard, being uncharacteristically generous, The Two Decembers
The Three Fates
Software cathedrals divide, in approximately equal proportion, into three fates and a fourth category that nobody talks about because nobody is sure it counts.
Approximately seventy-three percent of all software cathedrals collapse during the laying of the foundation. This is the sinking cathedral. It is correct in concept, internally elegant, and structurally incompatible with the ground it is built on. The most studied case in the lifelog is documented in The Two Decembers, in which a markdown-as-form-DSL was extended for six days, attempted to describe forms, attempted to describe configs, attempted to describe everything, and sank under the weight of the forms it could not describe.
Of the remaining twenty-seven percent, most are abandoned at the nave. This is the partially built cathedral, also known as “the architecture you’re stuck with.” It works, mostly. It is too expensive to finish and too useful to demolish. Engineers walk through it daily, ducking under unfinished arches, grateful that nobody has asked them to extend the transept. Maintenance budgets keep these standing in approximately the same way that hope keeps relationships standing.
The seventeen software cathedrals known to have been completed are all empty. Nobody is sure why. The leading hypothesis is that any architecture sufficiently complete to be called complete is also sufficiently complete to have outlived the problem it was designed to solve. The structure remains. The use case has moved next door. Visitors are admitted on Sundays.
The Fourth Category
There exists a fourth category of cathedral that is rarely counted in surveys because it is rarely visible.
Cathedrals which are drawn but not built.
These cathedrals exist on paper. In design documents. In Notion pages tagged “architecture.” In the second half of pull request descriptions that nobody read. They are complete on paper. They have wings, chapels, and flying buttresses. They have, in a few notable cases, spires that nobody attempted to engineer because nobody attempted to engineer anything.
The fourth category is, by some measures, the only category that actually delivers value.
THE CATHEDRAL ON THE MAP
IS NOT THE CATHEDRAL THAT WILL BE BUILTTHE CATHEDRAL THAT WILL BE BUILT
IS THE DOOR, THIS QUARTERTHE NAVE, PERHAPS NEXT QUARTER
THE CHAPELS, WHEN THEY EARN THEIR PLACETHE FULL CATHEDRAL, PERHAPS NEVER
OR PERHAPS, EVENTUALLY,
BY PEOPLE WE HAVE NOT MET— The Lizard, The Cathedral as Map
The fourth-category cathedral is a vision instrument, not a construction project. It is consulted, three quarters later, by an engineer who notices that the problem they are about to solve already has a name in a document they have been instructed not to delete. The engineer reads the document. The engineer notes that what they need to build is an entrance — possibly a corridor — and that the cathedral surrounding the entrance has, helpfully, not been built.
The engineer builds the entrance. The cathedral remains drawn. Liberato’s Law is satisfied. Nobody pays the Discovery Tax twice.
The Rule
The mythology has, over time, settled on a single operational guideline:
Draw the whole. Build one chamber.
This is not a slogan, although it sounds like one. It is the answer to the question “what do we do with the architecture we’ve designed but cannot build?” The answer is: keep the design, ship the chamber, name what is deferred, and trust the next quarter to bring its own use cases.
The architecture document becomes a permission to build small. The cathedral on paper says: here is what the generalisation will look like, after we have built two solutions and the third forces it through — see The Second Consumer. It is not a promise. It is a coordinate.
“All of it stays in the doc. Only one wing gets built.”
— riclib, The Cathedral as Map
Distinguishing Cathedrals from Buildings
The Squirrel, when this distinction is explained, asks the obvious question: how do we tell, looking at a design document, whether we are looking at a fourth-category cathedral (good) or a sinking cathedral (bad)?
The Lizard answers, with characteristic brevity:
THE CATHEDRAL THAT IS DRAWN
AND ACKNOWLEDGED AS DRAWN
IS A MAPTHE CATHEDRAL THAT IS DRAWN
AND ALSO ACTIVELY UNDER CONSTRUCTION
IN ALL EIGHT WINGS SIMULTANEOUSLY
IS A WARNING🦎
Documents help. Status headers help. Sections labelled “Deferred to follow-up projects” help enormously. The cathedral that knows it is a cathedral is, on average, much less likely to sink than the cathedral that thinks it is a sprint.
See Also
- Liberato’s Law — Why the cathedral must be drawn even if it cannot be built
- The Discovery Tax — What the cathedral costs in lines of working code
- YAGNI — Why the cathedral should not be built today
- Gall’s Law — Why the cathedral cannot be built first
- The Two Decembers — The first documented cathedral sinking in the lifelog
- The Cathedral as Map — The lesson learned from drawing one without building it
- The Second Consumer — When the cathedral earns its construction permit
- Boring Technology — The materials the door is built from
