The C4 model: levels, elements, and how ArqAtlas implements it

What the C4 model is for

One of the most common ways to describe software architecture is a box-and-arrow diagram where every architect uses their own notation, and no two diagrams of the same system agree. The C4 model, created by Simon Brown, is an easy to learn, developer-friendly approach to software architecture diagramming (c4model.com).

Its purpose is to describe a system with a small set of concepts at different levels of zoom: the same elements tell different stories to different audiences. You can show a non-technical stakeholder the big picture and a developer the technology detail, from the same model.

This isn't a new problem: when diagrams live in one tool, documents in another, and decisions in a folder, none of them know about each other, and renaming a service means updating every copy by hand. The C4 model proposes a shared notation for that problem; ArqAtlas goes one step further and unifies the data behind the notation into a single model.

Four levels: System Context, Container, Component, Code

The C4 model is named after its core set of static structure diagrams: (system) context, container, component, and code (c4model.com/diagrams). A system context diagram is a good starting point for documenting an architecture: it puts your system at the centre and shows the people and other systems it interacts with, without technical detail, so it can be shown to a non-technical audience too (c4model.com/diagrams/system-context).

The container diagram zooms in one level and shows the high-level shape of the software architecture, how responsibilities are distributed across it, the major technology choices, and how containers talk to one another. In C4, a container is an application or a data store: a server-side web application, a client-side single-page application, a desktop or mobile app, a database schema, and so on (c4model.com/diagrams/container).

The component diagram opens up a single container to show the components inside it, their responsibilities, and their technology/implementation details; its audience is architects and developers (c4model.com/diagrams/component). The code diagram then shows how a component is implemented at the class or entity level; c4model.com considers this level unnecessary for most long-lived documentation, since most IDEs can generate it on demand (c4model.com/diagrams/code).

As c4model.com notes, component diagrams are worth creating only when they add value, and worth automating for long-lived documentation (c4model.com/diagrams/component); the code diagram is an optional level of detail, often available on demand from tooling such as IDEs (c4model.com/diagrams/code).

Element types: Person, Software System, Container, Component

The C4 model works with a small set of elements, which is part of what makes it easy to learn (c4model.com/abstractions). A Person represents someone who interacts with a system: a user role, a persona, or a named individual. A Software System is the top-level building block, made up of one or more containers; each container holds one or more components, and components are in turn implemented by code elements (c4model.com/abstractions).

ArqAtlas adds two elements on top of these: Data Store and Queue. Both are concrete examples of C4's container concept; a database or a message queue is a container with its own responsibility in the architecture. ArqAtlas also uses an External System type to mark systems outside your boundary; that's ArqAtlas's counterpart to an external Software System in C4. When you create an element in ArqAtlas, you choose one of Person, Software System, Container, Component, Data Store, Queue, or External System.

Elements are connected by directed relationships, each with a description and, where relevant, the technology or protocol used. Elements are also hierarchical: a Software System can be broken down into one or more Containers, and a Container into one or more Components — the same hierarchy that lets you double-click down a level.

Views vs. the model

In C4, the model and a diagram (view) are different things. The model is the single source of truth holding elements and the relationships between them. A view is a particular slice of the model at a particular level; it carries no data of its own, only the elements it selects from the model and their layout.

In practice, this means the same element — say, an Order Service — can appear in a Container view and in a Component view embedded in three different documents. Rename the element once, and every view showing it stays current, because none of them holds its own copy; they all look at the same model.

In ArqAtlas, this distinction also shows up in the Model Explorer panel, which lists every element in the model independently of any view. Select an element there and you can see which views, documents, and decisions use it.

The same distinction shows up in the difference between removing an element from a view and deleting it from the model: removing it from a view only affects that view, not the element itself or any other view showing it. Deleting an element from the model is a separate action, and ArqAtlas first lists the views, documents, and ADRs that use it and asks for your confirmation.

C4 in ArqAtlas

ArqAtlas is built on top of this model/view distinction.

Wrapping up

The C4 model is a way to describe an architecture with a small set of concepts at different levels of zoom. ArqAtlas implements that by drawing everything from a single model, so diagrams, documents, and decisions never drift apart. Open an account to build the System Context view of your own system.