Services | C4 Technical Design Diagrams

The C4 Model for Visualizing Software Technical Design was developed as a way to help software development teams describe and communicate software technical design both internally and with non-technical stakeholders, both to document up-front design intentions and to retrospectively document an existing codebase. It’s a way to create maps of your systems and source code with all-important context, at various levels of detail and abstraction (Context > Containers > Components > Code), in the same way you would use a tool like Google Maps to zoom in and out of a geographical area of interest.

Level 1, the System Context diagram, is a good starting point for understanding a software system, allowing you to step back and appreciate the big picture. The diagram shows the system being described as a blue box in the center, surrounded by its users and the other systems with which it interacts.

Detail isn’t important here as this is a zoomed-out view, showing a “50,000-foot view” of the system landscape. The focus is on people (actors, roles, personas, etc), software systems, and the ways they interact rather than technologies, protocols and other low-level details. It is primarily for non-technical audiences but also proves to be very useful for technical teams in thinking through dependencies, troubleshooting, testing, project scope, etc.

Once you understand how your system fits into the overall environment, a really useful next step is to zoom in to view internal system boundaries in Level 2, a Container diagram.  A “container” is something like a single-page web, mobile, or desktop application, its server-side application services, a database and/or file system, etc.  Essentially, a container is a separately runnable/deployable unit (e.g. a separate process space) that executes code or stores data.

The Container diagram shows the high-level shape of the software technical design and how responsibilities are distributed.  It also shows the major technology choices and how the containers communicate with one another.  It’s a simple, high-level technology-focused diagram that is useful for software developers and support/operations staff alike.

Next you can zoom in more, decomposing each container further to identify its major structural building blocks and interactions as needed.  Level 3, the Component diagram shows how a container is made up of a number of “components”, what each of those components are, their responsibilities and the technology/implementation details.  The Component diagram isn’t always necessary.  Many C4 Models stop at Level 2.

Finally, you can zoom in to each component to show how it is implemented as code, using Unified Modeling Language (UML) class, entity-relationship, activity or sequence diagrams, etc.

This is an optional level of detail, which is sometimes available on-demand from tooling such as integrated development environments (IDEs).  Ideally this diagram would be automatically generated using tooling (e.g. an IDE or UML modeling tool), and you should consider showing only those attributes and methods that allow you to tell the story that you want to tell.  This level of detail is not recommended for anything but the most important or complex components.

Let’s document your technical design intent and existing system components and interactions enabling clear communication with business stakeholders and technical teams!