C4 diagrams
Draw C4 diagrams in the UIGraph diagram editor, nest them so readers can drill down, and move them in and out as Mermaid.
Where to find it
Open a diagram, then open the Modeling panel on the left. It has three sections:
- C4 Model for the elements and boundaries below
- Sub Diagram for drilling down into another diagram
- Sequence Diagram for message flows
Drag any tile onto the canvas to place it.
Elements
| Tile | Use it for |
|---|---|
| Person, External Person | The people who use the system. |
| System, External System | A whole software system. |
| Container, External Container | A deployable or runnable thing inside a system. |
| Component, External Component | A grouping of code inside a container. |
| Database | A container drawn as a cylinder. |
| Queue | A container drawn as a pipe. |
| Bucket | A container drawn as object storage. |
| Directory | A container drawn as a folder. |
| Web Browser | A single-page application. |
| Terminal | A server-side application. |
| Component (UML) | A component drawn with the UML symbol. |
| Infrastructure Node | A machine, cluster, or other piece of infrastructure. |
The external tiles are the same elements with External already turned on, so they come out in the muted grey C4 uses for anything outside your control.
Shapes
Every element is drawn from one of nine shapes. The tiles above are shortcuts that place an element with a shape already chosen, and you can change it at any time from Shape in the properties panel.
| Shape | How it is drawn |
|---|---|
| Box | A plain rectangle. The default for every element. |
| Database | A cylinder. |
| Pipe / Queue | A horizontal pipe with rounded caps. |
| Bucket | An open bucket, for object storage. |
| Folder | A rectangle with a tab, for a directory. |
| Web Browser | A window with a browser bar across the top. |
| Terminal | A window with a title bar across the top. |
| Component (UML) | A rectangle with the two UML tabs down its left edge. |
| Ellipse | An oval. Used for infrastructure nodes. |
Shape and Element Type are independent, so any element can take any shape. A system drawn as a cylinder is still a system, and it still reads [Software System] on the canvas.
The one exception is Person. An element whose Element Type is Person is always drawn as the person figure, and its Shape setting has no effect.
Elements are drawn as outlines rather than filled blocks, the way c4model.com draws them, so the colour you pick is the outline and the label.
Boundaries
Drop a boundary first, then drag elements inside it.
| Tile | Use it for | Label |
|---|---|---|
| Enterprise Boundary | Everything your company owns. | [ENTERPRISE] |
| System Boundary | The edge of one software system. | [SYSTEM] |
| Container Boundary | The edge of one container. | [CONTAINER] |
| Deployment Node | Where things run, such as a region, cluster, or host. | [NODE] |
| Group | Any grouping that is not one of the above. | [BOUNDARY] |
A boundary is drawn as a dashed outline with its name and type in the bottom left corner, which is where C4 puts them. Group is drawn dotted instead, to set it apart from the boundaries that carry meaning.
Boundaries take connections on all four sides, so you can draw a relationship to a whole boundary rather than to one element inside it.
Select a boundary to get its own properties:
| Field | What it does |
|---|---|
| Background Color | The fill inside the boundary. |
| Border Color | The outline and the label colour. |
| Hide Details | Collapses the boundary down to its name and type, so a busy diagram reads as a few blocks. |
| Auto Layout | Arranges the elements inside the boundary for you. Unavailable while details are hidden. |
A boundary also carries its own collapse button in the top right corner, so you can hide and show details straight from the canvas without opening the panel.
While details are hidden the boundary shrinks to a small block, the elements inside it disappear, and any relationship that crossed into it now points at the boundary itself. Relationships that only ran between hidden elements are put away. Turning details back on restores the boundary exactly as you left it, so collapsing is a safe way to present a large diagram.
Setting up an element
Select an element to open its properties on the right.
| Field | What it does |
|---|---|
| Element Type | Person, System, Container, Component, or Node. |
| Shape | Box, Database, Pipe / Queue, Bucket, Folder, Web Browser, Terminal, Component (UML), or Ellipse. |
| External | Marks the element as outside your control. |
| Technology | What it is built with, such as React, Go, or PostgreSQL. |
| Description | What the element does. |
| Color | The element colour. |
| Text Color | The label colour. |
On the canvas an element shows its name, then its type in square brackets, then its description. Setting Technology puts it in the brackets too, so a Go container reads [Container: Go]. Line breaks you type into Description are kept as you wrote them.
Changing Element Type or External recolours the element to the standard C4 palette. Pick a Color afterwards to override it. Infrastructure nodes and deployment nodes stay neutral grey, which is how C4 draws them.
Drilling down
A C4 diagram works best when it stays readable, so push the detail into another diagram instead of growing one canvas.
Open the Sub Diagram section in the Modeling panel, pick an existing diagram, and drag it on. The node shows that diagram's name and a preview of it. Open brings it up over the current diagram, and the arrow button opens it in its own tab.
A C4 element can point at another diagram as well. When it does, a small link button appears in its top corner and opens that diagram in a new tab.
Import and export
The Mermaid Diagram button in the canvas toolbar has two actions.
Import Mermaid asks for a Mermaid file. Select a .mmd or .txt file, and select a .json context file at the same time if you have one. These C4 diagram types are recognised:
C4Context
C4Container
C4Component
C4Dynamic
C4Deployment
Elements, boundaries and their nesting, relationships, and the style and layout overrides come across with the diagram.
Export To Mermaid downloads two files, <diagram name>.mmd and <diagram name>-context.json. When the diagram is C4 the Mermaid file is written as C4 Mermaid.
Those two files are the same pair uigraph-cli syncs, so you can commit them and point architectureDiagrams at them. See Mermaid Context.