← back

The architectural compiler

AI slop is code nobody can place anymore. An architectural compiler turns a codebase into a system map derived from source, lets a model explain only what the map can verify, and fails the build when an agent's change drifts from it.

10 min read
  • architectural compiler
  • AI slop
  • agentic engineering
  • software architecture
  • knowledge graphs

Background

All software engineers now (unless you live under a rock) are being forced to merge with autonomous coding agents in their day-to-day work. This is supposed to result in incredible productivity gains and at first it always seems like so.. near-instant features, functionality, and green checks passing.

but without a proper set of well thought out constructions, this usually devolves into a grown pile of software riddled with antipatterns, bugs, and slop.

AI coding agents firing code at a tangled pile of software: AI slop with no architectural compiler to stop it

AI slop is not bad code. It is code nobody can place anymore: a dependency nobody decided on, a second path to the same table, a doc that describes last month. Each change looks fine. The system stops being explainable.

My answer is a tool I call an architectural compiler.

What is an architectural compiler?

An architectural compiler is a deterministic program that takes a codebase and its declared architectural decisions as input, emits a verified system map as output, and fails the build when the two disagree.

Every architecture diagram is a claim about a codebase, and almost none of them are checked. Someone draws it once from memory, the code moves, and nothing fails. Agents make that worse, because they move the code faster than anyone redraws anything.

So stop drawing it. Compile it.

Source goes in. A system map comes out. The build fails when the two disagree, whether a person or an agent wrote the change.

I have been running architectural compilers across a few monorepos. The implementation is specific to each codebase; the shape is general. It has three parts that stack, plus one gate underneath them.

Prefer slides? The same argument is in The architectural compiler, in eight slides, the deck this essay grew out of.

1. The mechanical map

What a deterministic program can prove from source.

  • Every claim carries provenance. Not "this handler writes that table" but "rule usage.store_method followed store.saveThing( from routes.ts:220 into store.ts:88". A claim that knows where it came from can be re-derived, so it can go stale in a way a build can see.
  • Decisions are declared, never inferred. An architectural compiler cannot know whether a package is a library or a system you talk to. So it refuses to guess: package X is imported by two files and is neither a declared system nor a declared library. Every architectural change is a two-line diff, the code and the declaration that admits it.
  • Blind spots fail loudly. For each idiom the extractor reads, a counting pass finds every attempt at it and compares that with what was parsed. The map is never "missing a route". It is complete for the idioms it knows, or the build is red.
  • Two compiles of one tree are byte-identical, and the compiler imports nothing outside the standard library. That is what lets it run on any commit, including ones older than the project's current toolchain.

The rules are lexical on purpose: regular grammars over source text, following imports by name. A type checker would be more accurate and could only run sometimes. An honest map you can always build beats an accurate one you can build on a good day.

2. The enriched layer

The map says what and where. People want why, and that is prose. A model writes it, under four constraints.

  • Prose is validated data. Each construction gets a record with a closed schema for its kind. A record that says a namespace writes a table is rejected unless an extracted edge connects them. The model may only say what the map can check.
  • Words are bound to lines by hash. Every record cites the lines it was written from. Change a cited line and the record is stale, which fails the pull request until it is rewritten. A sentence cannot outlive the code it describes.
  • Flows are paths. A flow tells the story of one user action as steps, and every step must be an edge the map already draws. Remove the edge and the flow is broken.
  • Vocabulary is declared. A glossary lists the product's terms and the words that must not stand in for them. A wrong synonym rejects a record the same way a wrong table does.

The model never roams the repository. It gets a bounded packet per construction, returns JSON, and anything the validators reject is dropped with the reason printed.

3. Invariants, and the ratchet under them

A map can be wrong in exactly three ways, so the invariants come in three layers. Each failure tells you which kind of problem you have.

Keep the policy layer small. Three or four rules someone would miss if they broke. Thirty means it is being used as a linter.

The ratchet exists because every rule above is a line in a file, and whoever is blocked by a rule can edit the file. An agent that hits a red build has two moves: fix the code, or loosen the declaration. The ratchet makes the second move visible and human-gated. Everything else can be automated.

How an architectural compiler stops AI slop

Slop gets in through four doors. Each one is a build failure here.

What slop looks likeWhat the architectural compiler does
A dependency or service nobody decided onRefuses to compile until it is declared as a library or a system
A second, unplanned path to the same dataDraws the new edge, so it shows up in the change's diff of the map
Docs and comments that describe old codeMarks the record stale when its cited lines change, and fails the pull request
A rule quietly weakened so the change passesThe ratchet rejects it without a human-applied label

None of this asks the agent to be careful. It makes carelessness fail.

4. The map through time

Determinism buys one more thing. Run today's compiler at every past commit and you get a series of maps whose differences are differences in the code, never in the tooling.

  • One slider, every view. The system map, routes, tables, CI gates, infrastructure and the written layer all read one position. A view the history cannot move says so instead of quietly showing today.
  • A change is a diff of maps. One page lists what a commit added, removed and reworded across every view, with the prose diffed word by word. It opens on the latest commit.
  • Reviewers get the same diff per pull request. The map is compiled at the merge-base and at the head and compared record by record, never by line number, since a citation that only moved is not a change.

What running it taught me

Deleting is the best test. I retired a whole execution backend: about 3,600 lines across 66 files. The compile refused to run until the records describing deleted things were dropped. Two surviving records went stale and were rewritten. The ratchet flagged the removed external system as a loosening, so a human had to sign off. Nothing about the architecture changed silently.

A gate is only as good as the extractor's recall. I wanted a rule: no new background processors in the API process. Before writing it I checked what the map saw there. Eight periodic tasks. One was wrong and four were missing.

  • A bare indented call inside a function was read as a class-member header, which cut the function's body short and hid the timer registered after it.
  • A timer whose interval was a parameter was skipped as a helper.
  • Starters were followed one call deep, so createRuntimeFromEnv() → createRuntime() → new Service() was never reached.
  • Queue workers were not tasks at all.
  • The wrong one was a heartbeat that lasts one job and is cleared in its own finally. It is not a task the process runs for life.

Fix the extractor first. Then the rule is cheap: an allow list of the tasks each process may run, which the ratchet only lets shrink. That list is the next thing I am adding.

Read staleness from the compiled model. The stale flag committed beside a record is what the last writer believed. The compiler recomputes it from the cited lines. A reviewer page that trusted the committed flag reported "nothing stale" for a change that had staled a record without touching its file.

Exceptions keyed by line number drift. An exception list names file:line. Delete ten lines above and every entry looks new. The ratchet now treats an exception as moved, not added, when it is the same write in the same unchanged function.

Lexical matching over-reaches, and the map should show it. Matching store calls by method name means a task that calls claim() appears to use every table whose store has a claim. The records for those tables say so in their open questions. That is the honest state until the rule is tightened.

Default to folded. A process on the map is its entry point and its tasks. The dozens of in-memory collections it keeps fold to one row until asked for. A map nobody can read at default zoom gets discounted like the diagram it replaced.

Questions people ask

Is an architectural compiler a linter? No. A linter judges lines. An architectural compiler builds a model of the whole system (processes, routes, tables, external systems and the edges between them) and checks properties of that model.

Is it a knowledge graph? The output is one: nodes and edges with provenance. The difference is how it is built. Nothing enters the graph by inference or by hand. A rule read it from a cited line, or a human declared it.

Does it need an LLM? Not for the map. The map is deterministic and uses no model. A model only writes the explanatory prose, and that prose is validated against the map.

Does it slow coding agents down? It gives them a fast, specific failure in place of a slow review. The message names the missing declaration, the stale record or the broken flow, which is something an agent can act on.

What it does not do

  • It does not check that prose is true. It checks that prose is consistent with the map and written against the current lines. Intent is still a human's to read.
  • It does not produce a complete map. It produces one that is complete for the idioms it has rules for, and draws the rest as untouched.
  • It does not replace judgement. It makes decisions explicit, durable and checked.

The architectural compiler in three ideas

Provenance makes staleness observable. A claim that knows where it came from can be re-derived, and a claim that can be re-derived can fail.

Declarations turn drift into build failures. The compiler does not infer decisions; it demands them, and names the missing line.

Constrain the writer, not the reader. Machine-written prose is safe to publish when the writer may only say what the map can check, in words the glossary defines, about lines whose hashes it recorded.

Share this article

Copy an attributed link or download ready-to-post artwork.

Links

Share on XShare on LinkedIn

Instagram

Download artwork, then paste this URL into Instagram's Link sticker. This site never publishes to your account.

Suggested caption

AI slop is code nobody can place anymore. An architectural compiler derives the system map from source and fails the build when an agent drifts from it. Read: https://ethen.me/blog/architectural-compiler?utm_source=instagram&utm_medium=social&utm_campaign=article_share

Subscribe

New posts by email, when there are any.

Form not loading? Follow via RSS.

Back to room