A picture is worth a thousand words. If you’ve ever joined a new project, you’d know exactly what we mean. Sure, most engineers are great at reading code, but when there’s so much of it, it’s tough to see the big picture. That’s when it’s a good idea to take a step back and look at the architecture.
If you’re lucky, you might find a nice architecture diagram from a few years ago when the product was shown to some important people or when the lead developer was leaving the company. The problem is these diagrams aren’t usually kept up-to-date, so they get old pretty fast. At Solsten we think making and updating diagrams should be easy and quick, so nobody gets stuck with outdated info.
What is C4
C4 stands for “Context, Containers, Components, and Code”. Those are four levels that should be enough to describe a complex system. Context level is a bird’s eye view of the system in the context of the world. The container level is a more detailed view of your system. Don’t confuse c4 containers with the Docker or OCI containers. In C4 container is an application or data store. If you have microservice architecture then each microservice would be a container. Having a container diagram will give a good overview of the system but you can go deeper to a component level. This will be useful for monolith applications. The last layer is the code level. Not sure how much value it brings but it’s there. We don’t go deeper than 2 layers.
The C4 concept is straightforward and it gives a good mental model for the architecture documentation. It’s blocks and arrows between them so you can obviously draw them on a whiteboard, in diagram editor, or in Rational Rose if you are old enough. However, the power of C4 comes with a diagram-as-code approach.
Diagrams as code
Diagram-as-code is a way of creating and maintaining diagrams the same way you treat your code. You don’t have to draw them by hand. All you need is a get familiar with a JSON-like syntax (DSL) and a tool to render it. Here is a basic example of a c4 diagram in DSL language.
workspace {
model {
user = person "User"
softwareSystem = softwareSystem "Software System"
user -> softwareSystem "Uses"
}
views {
systemContext softwareSystem {
include *
autolayout lr
}
}
}
this DSL snippet could be rendered into:
The DSL language is pretty simple. As long as you get used to it you will be able to create or update diagrams in no time. This is the main advantage of such an approach because quite often people don’t have time or discipline to keep diagrams up to date and they become irrelevant and useless.
The other benefit of the diagram-as-code approach is that you can keep them in a source control system and collaborate on them using the same approach that developers use for code. You can store them in source control, collaborate using pull requests and build pipelines using automation-friendly tooling.
Our experience
We use Github to host our code and we keep our diagrams in a separate repo where we have a Github Actions pipeline that verifies DSL syntax and renders diagrams into Mermaid format that Github can display.
Viewing diagrams in Github is handy but for a more interactive experience our pipeline uploads diagrams to Structurizr where you can interact with them. Definitely check it out.
Conclusion
Using diagrams as code has some awesome benefits that are tough to beat. They’re developer-friendly, easy to maintain, and you can collaborate on them just like you do with code. Sure, they might not look fancy in a slide deck, but they do a great job for documentation purposes. What’s even more valuable is that having this tool makes it easy for team members to see the big picture and make improvements. So, not only do they help keep everyone on the same page, but they also make it a breeze to keep everything up-to-date and easy to understand.
