Structure — building blocks and the coupling you forbid

Six to nine blocks at the top level, and stop. A second level earns its place in exactly one situation: a block is opaque to the people who have to change it, so its internals need a map that the code does not readily give them.

Three levels drawn and none maintained is the usual outcome, and the deeper the level the faster it rots — because the deeper the level, the more of it is recoverable from the code anyway. Depth is not thoroughness; it is a maintenance obligation you took on in exchange for something a directory listing already provides.

The corollary is that decomposition stops when the reason for decomposing stops. If nobody can say which question the third level answers, it is not documentation, it is diagram habit.

Write each block's responsibility in one sentence with no "and" in it. If the sentence needs an "and", you are looking at either two blocks or a boundary drawn along the wrong axis, and both are cheaper to fix on the page than in the repository.

The names that fail this test are always the same: utils, common, core, shared, helpers. Each names a location rather than a responsibility, which means nothing can be forbidden from depending on it and everything eventually does. A block nobody can be prevented from importing is not a block; it is a global variable with a directory.

Prefer names from the domain, and take them from the vocabulary concern rather than inventing a synonym here. Two names for the same thing across the spine is a small cost per document and a large one for anyone — or anything — searching the repository for where something lives.

What a block depends on is derivable: an import graph, a dependency-cruiser run, a trace. Tooling produces it faster than you can type it and cannot be out of date. What a block may not depend on is not derivable from anything, because it is intent — the boundary you are choosing to hold.

That column is also the only one a check can enforce. "The order domain must not import the payment provider SDK" is an import-boundary test, a lint rule, an ArchUnit test: a sentence that can fail a build. "Orders depends on payments" cannot fail anything; it merely describes what is.

So every boundary that matters belongs in guardrails with a check behind it, and the structure page names which guardrail defends which rule. A boundary defended only by a diagram is a boundary that will be crossed by whoever is under deadline pressure on a Friday, in good faith, without ever seeing the diagram.

Structure is the concern most likely to be confidently wrong, and a wrong structure page is worse than no structure page: it costs a reader the time to read it plus the time to discover it lied, and it burns the credibility of every other page in the spine.

Split the page accordingly. Generate what is derivable — the picture, the actual dependency graph — and author only the intent: responsibilities, ownership, the forbidden edges, and the decision behind each one. Authored content is small enough to keep true; generated content cannot be stale.

Cite the decision that drew each boundary. A rule with no ADR beside it looks arbitrary, and arbitrary rules get deleted by the next person who finds one inconvenient. The citation is what turns "we do not do that" into "here is what that boundary is protecting, and here is what it cost us to have it".

A service boundary was enforced by the network whether you liked it or not: you could not reach into another team's tables from inside your process. A module boundary is enforced by an import statement nobody blocked, which means the discipline that was structural is now procedural.

This is the trade the modular monolith asks you to make, and it is usually the right trade — provided the check exists on day one. Add the boundary test with the first boundary, not after the first violation, because the first violation is never one import; it is nine, spread across four merged pull requests, and by then the cheap fix is gone.

The signal to watch is not the count of violations but the count of exceptions in the rule's allowlist. A boundary with six exceptions is a boundary that has already been re-drawn without anyone deciding to re-draw it.

Two modules sharing a table are coupled far more tightly than two modules sharing a function, and no amount of code restructuring touches it. The schema is the contract, migrations are the release process, and whoever writes to a table owns every reader of it whether they know them or not.

So record data ownership per block: the tables, topics and buckets it writes. It takes a line per block and it answers the question that decides how expensive a future split will be — which is exactly the question a diagram of code dependencies cannot answer.

The common failure is a table that two blocks write. It reads as convenient until the day one of them needs a schema change, at which point both are in the migration and neither can ship independently. If two blocks must write the same data, one of them owns it and the other goes through an interface — the same rule the context concern applies to external systems, applied inward.

C4 remains a good notation and there is no reason to replace it; service maps and dependency graphs come free with any competent observability or build tooling. Let the tooling own the picture, and let it be the reason nobody hand-maintains a box diagram again.

Then spend the time saved on what tooling cannot infer: why a boundary exists, who owns each block, which dependencies are forbidden, and which check defends them. Roughly one page. That page is the artefact; the diagram is an illustration of it.

Blocks drift toward the shape of the teams that maintain them, and the drift is invisible until an ownership question forces it into the open. Writing the owner beside each block turns Conway's law from something that happens to you into something you can look at.

Two patterns are worth naming. A block owned by three teams is either one block too big or three boundaries not yet drawn, and it will be the slowest thing in the repository to change. A block owned by nobody — the shared library, the internal platform, the utils package — accumulates whatever anyone needs, and it accumulates fastest, because there is no owner to say no.

Ask an agent for a feature and it will reach for whatever makes the feature work, which is frequently a direct import across a boundary it has no way to see. The diff is competent, the tests pass, and the boundary is gone — not through carelessness but because the rule existed only as prose in a document the agent was not given.

Reviewing for this by hand does not scale. Fifty small correct-looking changes a week is exactly the volume at which humans stop noticing architectural drift and start noticing only whether the change works. A build check does not get tired, and it fails the pull request rather than the retrospective.

So the rule of thumb inverts: previously you documented the boundary and hoped for discipline; now you write the check first and let the page describe what the check defends. If a boundary is not worth a check, say so on the page and treat it as a preference.

"Where does this belong?" is the question an agent answers worst and answers silently. With no map it invents a location — a new folder beside the old one, a second http client, a helper module that duplicates something three directories away — and each invention is individually defensible and collectively a mess.

A block list with a path, a one-sentence responsibility and an owner per row answers the question in the terms the agent is already working in. It is small, it fits in every session, and it converts a guess into a lookup. Pair it with the forbidden column and the agent can check its own plan before writing: this change needs orders to call payments, which G-2 forbids, so either it goes through the adapter or it needs a decision.

Agents are also good at the reverse audit, which is the pass nobody schedules: blocks in the repository that are absent from the page, rows whose responsibility no longer matches what the code does, and forbidden edges with no check behind them.

Generating a small, well-bounded module is nearly free now, which removes the oldest excuse for putting something in the wrong place. The same economics also make the opposite failure more likely, because an agent working inside a file keeps working inside that file, and a module that was the right size in March is four thousand lines in June with no single change that looks wrong.

Express the limit as a check rather than as review vigilance: a size or file-count budget per block, an ownership rule, a fan-in threshold. Whatever the shape, it should be the sort of thing that fails a build, because the growth arrives as many small increments and no reviewer sees the curve.

When writing code is cheap, structure's remaining job is confinement: what can a change in here reach, what can a failure in here take down, and what data can it see. Those questions produce different boundaries than tidy layering does — a tenancy boundary, a blast-radius boundary around anything holding money or personal data, a boundary around the code an agent is allowed to modify unattended.

That last one is new and worth stating explicitly. A repository where a large share of the code is generated benefits from saying which blocks are open to that and which require a human author — the migration path, the permission model, the payment adapter. It is a structural statement about risk, it belongs beside the block it constrains, and like every other boundary on this page it is worth only as much as the check behind it.