Skip to content

Conformance: C4 ​

Release 0.24.0 (milestone 2, docs/diagrams/notes/milestone-2.md). Support is claimed by level (decision D3): render and edit on the subset below, its six view kinds each checking what it may show, and read from a Structurizr JSON workspace. Maps draw exactly as before: umlimator.py import still turns Structurizr DSL, C4-PlantUML and Mermaid's C4 diagrams into maps, and nothing converts a map to typed C4 (S12).

A view of a version-2 model ("schemaVersion": 2) whose diagram is c4.landscape, c4.context, c4.container, c4.component, c4.dynamic or c4.deployment is a C4 view. It is drawn by lib/umlimator-all.js (umlimator/all), which the CLI's page inlines; lib/umlimator.js, what a map host loads, draws it as plain cards with a warning. The vocabulary is docs/diagrams/model.md §2, row 23; the example is examples/bookshop-c4.json, five views.

The subset ​

C4 is notation-independent (c4model.com); the shapes are the map's card shapes (S11), and the text over them C4's three lines.

ConceptIn the modelDrawn as
Person, software system, container, componentc4.Person, c4.SoftwareSystem, c4.Container (parent a system), c4.Component (parent a container); props description, technology, external, shapethe card shape props.shape names, one of box, person, robot, browser, window, terminal, mobile, cylinder, pipe, folder, document or hexagon (not node, the deployment view's; any other name draws the default, person for a person and box for the rest), sized by its text: the name, [Container: technology], the description to four lines of 220 px; external grey
Deployment nodec4.DeploymentNode (parent a node or none)holding something shown, a solid box titled name over [Deployment Node: technology]; else the map's node shape with C4's three lines
Container instancec4.ContainerInstance (parent a node); props.container (a declared reference: deleting the container deletes its instances)drawn as its container
Relationshipc4.Relationship; label its description, props.technologya solid line with an open arrow, description [technology] on one line, cut at 280 px
Implied relationshipderived when drawn, never stored: a relationship whose end a view does not show, drawn between the nearest shown owners, one a pair, none where a relationship joins thema dashed line with an open arrow; selected and named, never edited
Boundarythe view's subject, when nodeIds lists ita dashed box titled name [Software System] or [Container], holding what it owns that the view shows
Dynamic view's stepsthe view's edges: relationship ids, each once, in time ordereach step k · description [technology], numbered among the steps drawn
Commentuml.Comment, uml.CommentLinka note, a dashed line; a link to what the view draws as a box is not drawn, and said (c4-note-box)

What each view may show (c4-level): a landscape or context view people and software systems; a container view containers too (its subject's and other systems'); a component view the components of its subject; a dynamic view what its subject's level draws; a deployment view deployment nodes and container instances. An element is not listed with its owner unless that owner is the view's subject.

Rules (src/c4/c4.js, src/c4/views.js): errors c4-level, c4-subject (a subject of the wrong kind, or one naming no element), c4-owner, c4-instance, c4-relationship, c4-steps (a step that is no relationship, or one listed twice); warnings c4-subject (a view with no subject; a context view that does not show its subject), c4-zoom, c4-description, c4-technology, c4-label, c4-title, c4-steps (a step whose end the view does not show, not drawn; a view with no step), c4-box-line (a deployment view's relationship with an end in or on a node drawn as a box, not drawn), c4-note-box (a comment's link to a boundary or to a deployment node drawn as a box, not drawn).

Departures: the shapes are the map's; an external element is grey, as c4model.com draws it, not dashed (dashed marks a boundary and an implied line). Deployment nodes' descriptions and technologies are not asked for.

Left out ​

notes/milestone-2.md §13: the code diagram (a component opens the package view instead); software system instances and infrastructure nodes; groups; environments as data (a deployment view's title names it); a step repeated or reworded in a dynamic view; parallel steps; relationships between instances derived from their containers'; filtered and custom views; a Structurizr JSON or DSL writer; conversion from a map. And copy and paste, per-type diff() writers, deleting a view.

The Structurizr JSON reader (readStructurizr) reports what it does not read: implied relationships (the type works them out; one a dynamic view's step names is kept as a relationship of the model when the view draws its ends), groups, perspectives, properties, urls, documentation, themes, positions, custom elements, software system instances, infrastructure nodes, filtered, custom and image views, and style fields other than shape.

Layout limits, measured on examples/bookshop-c4.json and tests/c4-stress.json:

  • Port repair and rerouting off (repair: false, reroute: false, §11); gap 48, rgap 64.
  • The example's crossings, as Node's check() counts them: the container view 3, the component view 2, the dynamic view 2 right (3, one label on a line and two labels cut to their step down), the deployment view 1 each way; pinned in tests/c4.test.mjs and tests/c4-views.test.mjs. Chrome counts 8 over the five views (CI's example loop pins it), and no line runs through a card, with the estimate's text widths or a host font 10% narrower. Laid out down, five of the container view's labels and the dynamic view's mail step found no spot and were left off with nothing said; since audit 6 they are drawn, the container view's on a looser spot, 6 labels on lines, which check() names. The dynamic view's steps 1 and 8 keep only their numbers laid out down (their words in the line's title and the details), which check() names since audit 23.
  • tests/m2-fixtures.test.mjs pins the stress file. Its six edge-case views (every shape, an implied line and one hidden by a direct one, another container's component, deployment nodes five deep with instances, twelve steps, a 300-character description) are clean (laid out down, the implied line's label and step 1's were left off before audit 6: drawn now). Its generated all container view (50 elements, 70 relationships) crosses 133 times right and 141 down; check() finds 3 other problems right and 5 down (pairs of lines sharing a line, labels on lines: the labels left off before audit 6, 9 right and 16 down, are drawn, the view laid out down with room for them; 136 crossings and 26 problems down till audit 32 placed again a label a later line ran across); no line runs through a card, every end is on its card and no label is over a card. A crowded container view is C4's weakest layout with repair off.
  • Deleting a container or component view's subject leaves a c4-subject warning on that view until a new subject is set, as composite structure's subject-shown does (audit 18, risks.md M15); a view whose subject is of the wrong kind is still an error. A context view with no subject, or one that does not show its subject, gets the same warning; a context view whose subject is not a software system is an error, as on the other levels (audit 35).
  • A description over four lines is cut with an ellipsis; its whole text is in the element's accessible name, describe() and the PDF.

Writers: what each shows of a C4 view ​

Measured on examples/bookshop-c4.json (0.24.0); the PDF's text read back by tests/cli.py.

What is drawnSVG: handle.toSVG(), umlimator.py stillsPNG: handle.toPNG(), umlimator.py stillsPDF: umlimator.py pdf
Elements in their shapes with three lines, boundaries, deployment boxes, relationships, implied lines, step numbersYesYesYes, in vectors, each view on a page of its own
The key of element types, shapes, the relationship and the implied lineNo: the key is a piece of the pageNoYes, under the picture
TextText, in the page's font family; not embedded unless fontCSS is givenPixelsSelectable text
Accessible namesEach node's aria-label kept; the lines' <title> removedNoneNone
TablesNoneNone"Elements": each element's type, technology and description, an external one marked external, an instance's container. "Lines": each relationship's description and technology (the type's text), a step's number

Accessibility ​

Every piece has a name: "Container Shop API, Python, FastAPI: Catalogue, basket, checkout and accounts as a JSON API"; "Software system Bookshop, a boundary holding 5 containers"; "Step 3: Relationship from Shop API to Payment provider: …"; an implied line says what it stands for and where to edit it. Text reads at 4.5:1, lines and outlines at 3:1 in both themes, on the stage and on each element's fill (tests/c4.html, tests/c4-views.html, tests/m2.html). Every gesture has a key: D makes a system's container view or a container's component view, T changes an element's type (or an instance's container), Alt + arrows reorder a dynamic view's steps (docs/editing.md).

Performance (P1) ​

tests/m2-fixtures.test.mjs on tests/c4-stress.json's all view (50 elements, 70 relationships), CPU time, best of seven after a warm-up, on an Apple laptop under other agents' load (14 Nov 2026): a full layout and its SVG 109 to 229 ms; an element's description (its node grows, laid out again) 117 to 237 ms; a container's technology, which moves nothing, 109 to 231 ms (two runs). tests/c4.test.mjs measured 132 to 201 ms and 135 to 191 ms for the first two on a lighter load, and the technology at 46 to 49 ms where it repaints only. Over the 100 ms target; under CI's 1 s ceiling, which the tests hold and print.

Tests ​

tests/c4.test.mjs and tests/c4.html (the static views, boundaries, implied lines, the rules each passing and failing, D, T, a 30-step session, every gesture by pointer and key); tests/c4-views.test.mjs and tests/c4-views.html (the dynamic and deployment views, steps reordered, instances deleted with their container); tests/c4-minimal.json and tests/c4-stress.json with tests/m2-fixtures.test.mjs and tests/m2.html; tests/notation.html (a relationship's solid open arrow, an implied line's dashed one); tests/structurizr.test.mjs; tests/import.py; tests/cli.py; tests/mcp.py.