C4 Model

The C4 Model is a diagramming framework. Over the years, we've had many practitioners request C4 features in D2. There's even a community-maintained exporter from the C4 creator's tool, Structurizr, to D2.

The C4 Model is a loose framework. Unlike UML, which says these symbols always and must mean certain things, the C4 model is a set of diagramming concepts. It's language and tool agnostic, and these powerful concepts have proven to provide software projects with clean, mature architecture diagrams.

With the latest 0.7 release of D2, we filled the gaps in the language to have first-class support of these concepts:

1. A new suspend keyword which, along with existing D2 features, lets you define one model and reuse them across different views.
2. Markdown labels on shapes allow you to give richer textual descriptions with font hierarchy.
3. A new c4-person shape that is more conducive to holding longform labels.
4. A C4 theme for diagrams to be conveniently on-brand recognizable.
5. A new d2-legend variable to easily make beautiful legends.

Whether you choose to use these new features specifically for C4 model diagrams is up to you. Much of this feature set was requested for other purposes. What's important are the good practices it enables, which can be applied broadly across all sorts of diagrams.

In this article, I'll demonstrate how you can make C4 diagrams in D2. If you'd like more detail on using a specific feature, you'll find dedicated sections in the docs.

One model, multiple views

Let's take a look at how the new suspend keyword can be used to slice and dice a model into a variety of views.

First we define a medium-sized diagram using the new C4 theme, c4-person shape, and markdown labels.

Show only relationships to API Application

Let's say we want to create a view for the API team that only includes what's relevant for them. We'll use the same code as the above, but add 2 sections:

1. "Suspend" all models

Use globs to target everything declared so far and suspend them. These will be removed unless "unsuspended" later on. Suspended objects and connections are effectively the models.

2. Unsuspend models we use for our view

Now we use globs to declare which models we want to show up. We do this by "unsuspending" them.

Result

Runnable code:

Show high-level overview

Let's make a high level overview with the same concepts. The only change here is how we unsuspend things.

And since there are connections between inner shapes of Internet Banking System to other components, we'll make some connections that capture the general dependency.

Runnable code:

Tags and filters

Let's say your repository of models is large; maybe everyone in your cross-functional team is pushing their own models to this file.

To give an example of a small repository:

To reuse these models for a specific domain, we can filter by their classes (tag in C4 vernacular). Assuming the models are in their own file, we can create something like a CustomerInterface.d2 file, which imports these models, suspends all, and unsuspends the ones that have the customer-facing class.

Now we can add some connections to create a diagram out of these pre-existing models.

Legend

To create a legend for this diagram, we declare it as a variable under d2-legend.

Think of d2-legend as a mini diagram of its own, but with a special layout where every shape and connection is deconstructed into a table. If something has opacity 0, it is excluded in the table (this way we can have legends that only show connections, for example).

Notice the legend in the bottom right corner.

Google Maps zooming

Lastly, a core concept of C4 diagrams is this notion of zooming in and out of different levels of abstraction. The 4 in C4 stands for the 4 levels of abstractions that it recommends. Let's take a look at how that can be achieved. For this example, we'll define two diagrams of code that represent a zoomed in view of the components.

Example code diagram for ATM Banking System

Example code diagram for Notification System

Linking together

Now let's link these up using the layers feature.

All that's needed is to declare the 2 code diagrams as layers and add the link property to whichever shape we want to be able to zoom into them.

We can export this to a PDF format. If you download it and click on notification or banking, it'll take you to those respective zoomed-in code views.

To recap, you'd split it out into those 4 files and use imports for modularity:

1. models.d2: where models are defined
2. customer-components.d2: where you import models
3. banking-code.d2: code diagram for banking system
4. notification-code.d2: code diagram for notification system

You can easily flesh this out further by having files for the styling, for higher levels of abstraction (e.g. for context diagrams).