Skip to content
mif-docs

Skill reference: c4-model-diagram

Skill reference: c4-model-diagram

Section titled “Skill reference: c4-model-diagram”

The c4-model-diagram skill authors one document genre: a C4 model architecture document — Simon Brown’s four levels of abstraction rendered as notation-independent Mermaid C4 diagrams plus an element catalog. This reference describes what that document type is, how the skill produces one, when it earns its place, and the provenance and sources behind it.

PropertyValue
AuthorsA C4 model document (diagrams + element catalog)
Purpose groupArchitecture design
MIF conceptTypesemantic
Target MIF level3
Primary sourceThe C4 model

What this document type is

Section titled “What this document type is”

The C4 model describes software architecture as a hierarchy of four levels of abstraction, each a zoom step into the level above. System Context shows the system as a single box among its users and the other systems it talks to. Container opens that box into separately deployable or runnable units — web apps, services, databases, message brokers. Component opens one container into its major structural pieces and their responsibilities. Code — used sparingly — drops to class-level detail where it adds value. The model’s discipline is that each diagram answers exactly one question at one zoom level, so a reader is never shown too much or too little at once.

C4 is deliberately notation-independent: the levels are the model, and any notation can render them. This skill renders them as Mermaid C4 diagrams so the source is plain text that lives and diffs alongside the docs, paired with an element catalog that names every person, software system, container, and component with its responsibility. A C4 document is not a decision record — a choice belongs in an adr — and not a single sequence or deployment view in isolation. Because it is structural knowledge, it projects to MIF as semantic content at Level 3.

How the skill produces one

Section titled “How the skill produces one”

c4-model-diagram is a genre skill: it carries the C4 pattern as durable instructions plus exemplars, and writes the artifact over a MIF floor so the result is at once human-readable diagrams and a machine-conformant unit.

  • Pattern, made operational. The skill encodes the four levels, the one-question-per-diagram discipline, and the paired element catalog, and refuses anti-triggered work (a decision belongs in an ADR; a lone sequence or deployment view belongs in its own diagram genre).
  • Exemplars set the bar. Like every genre in the suite it ships good-l1.md (the MIF Level-1 floor), good.md (the Level-3 target), bad.md (a counter-example), and evals/evals.json. The check-exemplars gate proves good-l1.md validates at L1 and good.md at Level 3, keeping the taught pattern continuously verified.
  • MIF projection. The document is authored with MIF frontmatter (via the shared mif-frontmatter substrate) and a conceptType of semantic, and the Mermaid diagrams round-trip as plain text. mif-validate proves the Markdown ↔ JSON-LD round-trip is lossless before the document is considered done.

When it is beneficial

Section titled “When it is beneficial”

Reach for c4-model-diagram when you must communicate architecture to a mixed audience at the zoom level each viewer needs: a System Context diagram for executives and product, Container and Component diagrams for engineers. The hierarchy lets one document serve everyone without drowning non-technical readers in detail or starving engineers of it, and the text-based Mermaid source keeps the diagrams version-controlled and reviewable.

Do not use it to record a point-in-time decision and its trade-offs — that is an adr. Do not use it when the goal is a single sequence/data-flow or a deployment-only view; reach for the matching diagram genre instead. When you need the whole-system narrative around the diagrams, the arc42-arch-doc genre embeds C4 views inside its context and building-block sections, and a machine-first spec belongs in ai-architecture-doc. The cost of C4 is upkeep: diagrams drift from reality fastest, so keep the level count small and the catalog current.

Example

Section titled “Example”

A C4 document titled “MIF docs platform — C4 views” opens with a System Context diagram placing the platform between authors, readers, and the MIF validator, then a Container diagram resolving it into the docs site, the conversion CLI, and the schema store, then a Component diagram of the converter’s parser, projector, and round-trip checker. An element catalog table lists each box with a one-line responsibility, and the Code level is omitted because nothing at class level needs explaining.

Provenance & citations

Section titled “Provenance & citations”