The whole story on one page

Everything below is one picture. Download it as a PNG for a post or a slide, or Print / Save as PDF for a handout — both buttons sit above the poster.

The same story in words

If you would rather read it, or you landed here without JavaScript:

  1. Start. Three doors, all free and all local: a blank editor, npx crayon-c4 . against a repository you already have, or the demo project to take apart. Nothing is uploaded until you ask. See Tour of the app.
  2. Decompose. Four levels, each one opening a single box from the level above — context, containers, components and code. One question decides where a thing belongs: can you deploy it on its own? → Container. Is it a unit of code inside one? → Component. Most systems never need the code level by hand, and only a few containers earn a component diagram. And you need not draw the ladder at all — the wand derives it from the elements you entered, then keeps it current: it only ever adds, so running it again after you add elements brings in the new ones and moves nothing you arranged.
  3. Connect. A relationship is a fact about the architecture, not about one picture. Draw it once and every diagram where both ends resolve draws it — rolled up onto the coarser pair where it has to be.
  4. Show how it behaves. F4 swimlanes are your C4 elements; the steps crossing them are the flow, with calls, returns and what happens on failure.
  5. Show where it runs. Define a thing once and place it into each environment — the same shape in dev and prod, so only the differences stand out.
  6. Record the decisions. Decision records link to the elements and connections they decide. Accepted is a one-way door: change course by superseding, never by rewriting history.
  7. Make it yours. Colour, icons and line styles, alignment guides and hand-routed connections.
  8. Hand it over. A read-only link that needs no account at the other end, a PDF, a markdown bundle, or per-diagram SVG and PNG.

Then it keeps up: re-run the extractor and your manual edits survive the merge — see Document from code.

Using the poster

  • PNG downloads at a fixed size, so it looks the same wherever you post it — resizing your browser window doesn't change the image.
  • Print / Save as PDF prints just the poster, without the surrounding site, and keeps each step together rather than splitting it across a page.
  • It's a long page — scroll through it, or print it as two or three sheets.

Where next