c4-model-diagram

Produces a C4 model in Simon Brown's sense (c4model.com): a set of nested diagrams that describe a software system at four levels of abstraction, each zooming in one notch. C4 is abstraction-first and notation-independent — the value is the consistent set of boxes-and-lines abstractions (person, software system, container, component), not any particular drawing tool. Mermaid C4 is one rendering; the abstractions are the contract.

The four levels (zoom in one level at a time)

1. Level 1 — System Context. The system as a single box, surrounded by its users (people) and the other software systems it talks to. Audience: everyone, technical and not. Answers "what is this and who/what uses it".
2. Level 2 — Container. Zooms into the system box to show the deployable / runnable containers (web app, API, mobile app, database, message broker — not Docker containers specifically) and how they communicate. Audience: technical people inside and outside the team.
3. Level 3 — Component. Zooms into one container to show its major components (groupings of related functionality behind an interface) and their relationships. Audience: developers of that container.
4. Level 4 — Code. Zooms into one component (classes / functions). Usually omitted — it ages fast and is better generated on demand from the IDE. Most C4 docs stop at Level 3.

Pattern (each level is the same shape)

• A Mermaid C4 diagram in a fenced ```mermaid block using the matching block keyword: C4Context, C4Container, or C4Component. Declare people with Person(...), systems with System(...)/System_Ext(...), containers with Container(...)/ContainerDb(...), components with Component(...), group an in-scope system with a System_Boundary/Container_Boundary, and connect everything with Rel(...) labelled by what flows and how.
• An element catalog under the diagram: a short table or list naming each element, its kind (person / system / container / component), and its single responsibility. The catalog is the durable part; the diagram is its view.

Authoring rules (what keeps it a true C4 model)

• One level of abstraction per diagram. Never mix containers and components in the same picture — that is the most common C4 failure.
• People and boundaries are mandatory at Level 1. A diagram with only technical boxes and no actors and no system boundary is an arbitrary architecture sketch, not C4.
• Label every relationship with intent and (where useful) technology/protocol ("Reads from, via JDBC"), and keep the arrows directional.
• Consistent naming across levels: the container you zoom into at Level 3 is the same named container from the Level 2 diagram.
• Keep technology choices on containers and components, not on people or external systems.

MIF frontmatter

type: semantic — a C4 model is declarative architectural knowledge (what the system is), not a time-bound event or a how-to. Climb to L2 with namespace (e.g. architecture/c4/<system>), title, and tags when known. Gate every output with mif-validate at its target level; the floor is --level 1.

Why machine-readable — the point of MIF here

A C4 model is consumed as much by tools as by people: a docs pipeline checking whether an architecture view is stale, an agent tracing which larger document embeds it, a reviewer asking where the model came from. As prose with embedded diagrams (L1) every one of those needs reading and inference. The MIF layer makes them answerable from frontmatter alone:

The same document still reads as a human C4 model and projects losslessly to JSON-LD and back — one artifact, two readers.

The L1 -> L3 climb (two exemplars)

This skill ships the same model at two MIF levels so the climb is explicit:

• templates/good-l1.md — L1 floor: id, type, created + the body (diagrams + element catalogs). A complete, valid C4 model, but opaque to a machine consumer. Validate with mif-validate --level 1.
• templates/good.md — L3 (the highest this genre honestly supports): adds namespace, modified, temporal validity, an architecture-view ontology type, W3C-PROV provenance, and a typed relates-to relationship into the arc42 document genre. Validate with mif-validate --level 3.

Author at the highest level the context supports (grade down rather than fabricate). templates/bad.md shows the antipattern: a "C4" diagram that mixes abstraction levels and shows tech-only boxes with no people or boundaries.

Quoting the full document elsewhere (never escape the mermaid fence)

The finished document contains its own ```mermaid ... ``` fence. Any time that document is reproduced verbatim inside another markdown context — a transcript, a chat reply, a PR description, a code-review comment — that outer context is itself commonly wrapped in a fenced block. Nesting a 3-backtick fence inside another 3-backtick fence is invalid markdown, and the failure mode is not "it renders wrong" — it is that the model, trying to keep the outer fence intact, escapes the inner fence's backticks (\``mermaidinstead of mermaid `). An escaped fence is no longer a fenced code block at all: it reads as literal backslash-backtick characters, so any downstream consumer — a human, a renderer, a grader — looking for a real ` mermaid ` block will not find one, even though the diagram content is otherwise correct.

Never escape backticks to solve this. Instead, widen the outer fence so it cannot collide with the inner one:

• If you are wrapping the whole document in a fence to show it inline, open that outer fence with four backticks (````markdown) — one more than the 3-backtick mermaid fence nested inside it — and close it with four backticks too. The inner ```mermaid fence then passes through untouched, exactly as written in the delivered file.
• If the surrounding tool already forces a 3-backtick outer fence (some chat and PR-comment renderers do), do not wrap the whole document at all — quote only the prose around the diagram, and reference the mermaid block by pointing to the file/line instead of re-emitting it inside the same fence.
• The rule generalizes to any nesting depth: the outer fence's backtick run must always be longer than the longest backtick run appearing inside it.

This applies whether you are writing the primary output file (write it with a real, unescaped fence — never escaped, regardless of surrounding tool calls) or narrating/reproducing that file's contents afterward.