How to document software architecture?
Tags: Documentation, Software Architecture, DevOps, Application, Software

Context Diagram

It is all about the big picture. We don’t need to know the technical details here. What is important for us are people (actors, who are using the system) and software systems that are part of a business solution.

Context is a diagram that we would show a business person explaining what kind of a system we’re building, what integrations it has, and who is going to use it.

With our invoicing system, it could look like this.

Container Diagram

The second level is a Container Diagram. This time, our focus is on separately running/deployable parts of our system. We could compare it to Docker containers.

Each separate service/database/storage is a separate container on that diagram.

Let’s go back to our Invoicing System. It will have an API, a Frontend, a database, but also a caching layer and file storage. Each of those will be a separate container.

What is important on this level is to describe the technology that is used for that specific container and also how communication between the containers looks like. Is it HTTP? Or maybe is it gRPC? That information needs to be on a diagram.

As you can see, we have much more technical information on this diagram. We can see what type of storage we use, what technologies are used for frontend and backend software development, and how those two systems communicate with each other. We can also see all the integrations between specific containers and external services, yet we know nothing about the actual implementation.

This is what the next diagram is about.

Component Diagram

On this level, we are going to focus on the major building blocks of a specific container. This is where much more implementation details are going to be visible.

Services, repositories, command handlers, external services clients and even endpoints — all of those might be put into this diagram. What is important is to show not only the building blocks but also the communication/relationship between these.

So what would it look like in our Invoicing System? Let’s focus on Invoicing API. The main components are going to be different command handlers, clients to communicate with Keycloak, and Slack. We would also need a few repositories, a PDF management service, and webhook integration for JIRA.

Let’s see that on a diagram.

As you can see, a component diagram is not about putting every implementation detail, but focusing on those that are the most important. At ScaleTech, we also follow a few rules:

every arrow needs to have a description,

every name we use needs to be a name that is used in a code (basically when we call something a PDF Generator, there needs to be a thing in the code for that),

every endpoint/way of communication needs to be visible,

every color has a meaning (usually we also add a legend for that).

Those simple rules make it easier to follow and design new diagrams since everyone in a company does it in the same way.

Code Diagram

The last diagram that is part of a C4 family is a Code Diagram. This is the one that will be updated the most often, but also is the optional one. At ScaleTech, we don’t really use this diagram. However, the key here is to generate it from the code itself.

It isn’t as hard as it might sound. In reality, we might use some annotations/documentation properties to generate a pretty good UML class diagram that will describe our code and how everything is connected with each other.

A good example of a class diagram could be:

Image source: uml-diagrams.org

It goes so much into the details that with every pull request it will look different, that’s why there is no way to create those manually.

What’s next?

C4 is a relatively simple model to describe your architecture. There is a pretty good benefit of using such an approach — the whole system is easier to understand, making onboarding of new developers faster and easier.

By using C4 everyone can understand the system to the level that is useful for them. Not everyone needs to know about implementation details, however, everyone should be able to understand the high-level goals of a system and what services are used to make it work.

Obviously, C4 is not the answer to everything. In a more complex system, we would need additional types of diagrams — ERD, sequence, flowcharts, etc. However, C4 is an excellent starting point.