Blog
Notes on describing software systems: structure, behavior, and deployment. Most posts carry a live diagram — you can explore it in place, or open it in the designer and make it yours.
I kept redrawing the same three diagrams, so I built a tool
Every team I worked with needed the same three pictures — how the system is structured, how behavior flows through it, and where it runs. I got tired of redrawing them. CRAYON-C4 is the result, and it's now open for early users.
The C4 model, explained with one online store
What the C4 model is, why levels of zoom beat one big diagram, and how a context view and a container view answer different questions — walked through on a small web shop you can explore live.
Four diagrams, four questions — draw each to its intent
Each C4 diagram has one job — a question it answers and a kind of detail it must refuse. A close look at the context, container, component, and code diagrams, and the anti-pattern of letting deployment leak into an abstraction.
Structure diagrams don't answer "what happens when…"
Architecture diagrams tell you what exists. They can't tell you what happens. Why behavior needs its own view, what swimlanes still do best, and what changes when the lanes are bound to the architecture model.
The deployment story your architecture diagram isn't telling
The containers in your architecture diagram all run somewhere — and in most teams, "where" lives in heads and wiki pages that age. What a deployment view is for, and why it should reuse the containers your architecture already names.
Diagrams age. Code doesn't lie.
The half-life of an architecture diagram is about one sprint. The fix isn't discipline — it's deriving the structural facts from the repository, keeping human judgment as curation on top, and making the re-run non-destructive.
Inside CRAYON-C4: one model, four views
The full tour — how the one-model idea works, how the designer, flows, deployment views, and code extraction fit together, how I use it day to day, and what's free.
If you have to explain the diagram, the notation failed
C4 is deliberately notation-independent — which puts the burden on you. A diagram should be legible without you in the room, and that legibility isn't taste, it's consistency. Here's the craft of notation, and the surprisingly deep science under it.
C4 is too much, and too little
The name promises four levels; you almost never need four. And even at full depth, C4 can't tell the whole story. The trick is to treat it as a conversation starter — draw the one or two pictures that earn their place, and let the rest go.
What C4 leaves out: time and place
A structure diagram tells you how the parts fit together — not when they talk, and not where they run. Those are two separate questions with two separate diagrams. And the deeper lesson, thirty years old, is that no single view is ever complete.
The next viewpoint is AI
Kruchten's set of architectural views was never meant to be frozen. Security went from afterthought to first-class concern. The next perspective to add is AI — and the only way to carry that many viewpoints without drowning is one shared model, read differently per audience.
Diagrams can't keep up — so make them move with the code
The whole point of a diagram is a fast, cheap "will this work?" conversation — the Agile feedback loop applied to design. But AI now changes code faster than any diagram can be redrawn. The fix isn't discipline; it's deriving the picture from the code and knowing which parts actually change.
Code can't tell you why
You can regenerate a diagram from code, but never the reasoning behind it. Rationale lives in people's heads and evaporates. That gap is where a model earns its keep — and where it becomes the best context you can hand an AI, in a world where AI has flattened the old role ladder.
Structurizr Cloud is gone. Here's how to keep your model — and get a visual editor.
Structurizr's cloud service shuts down 30 September 2026 with no replacement. Here's how to get your workspace out, the real options, and an honest comparison — including where CRAYON-C4 fits and where it doesn't.