Architecture Diagrams

Hi, my name is Ray, and I’m a software architect.

Example container diagram

According to my old boss Jeroen van Rotterdam, this means that I draw boxes and lines. In practice, it’s only a small part of what I do, but I do think it’s an important part.

Some people may wonder why, in the age of working software over comprehensive documentation, one would still spend time on creating pretty pictures. Didn’t we leave all this up front, non-code fluff behind? Well, I do value working software more than comprehensive documentation, but that doesn’t mean there is no value in documentation.

I work with several “central” teams that provide shared services to “local” teams. In such discussions, it’s quite often useful to be able to point to a high-level architecture of the system. Something like the context diagram of the C4 model. Such context diagrams were also of great value during the due diligence phase of the recently announced sale of our division. Drawing a context diagram takes very little time, provides clear benefits, and requires little maintenance, so it’s really a no-brainer.

What about other types of diagrams?

The C4 model has several other diagrams. Which ones you need depends on your context. If all your code goes into a single war that you deploy to an application server, for instance, there is little point in creating a container diagram, but a component diagram may be useful. If, on the other hand, your system consists of quite a few microservices, then a container diagram that shows how they are connected may be very valuable, but a component diagram would probably be overkill.

If you work in a larger organization, with lots of teams building lots of systems, then having a diagram standard in place like the C4 model is a great way to reduce the time needed to explain a system to others and to prevent misunderstandings.

You will probably want to “personalize” that standard to make it more expressive for your particular context. For instance, we use color coding of elements on container diagrams to indicate their status: red for things we are ready to remove, orange for things we want to migrate away from, yellow for things we want to review, green for things we’re happy with, and blue for things we’re planning to build in the future.

Such an adaptation of the C4 standard doesn’t reduce the value of the standard if most or all of you communication is within your organization where everyone uses the same adaptation. If, however, you routinely use diagrams in communication with outsiders, you may want to minimize your adaptations, or at the very least provide a legend with your diagrams.

Also use your diagram standard on whiteboards.

The standard should be used everywhere you draw visual representations of your systems, like in whiteboard sessions and in Architecture Decision Records. Consistent use of the standard turns it into a ubiquitous language for visually representing your systems, eliminating ambiguities.

If you have a standard that all your diagrams must adhere to, then you can build tooling around that. For instance, you could write a tool that generates a diagram from a simple YAML file that describes your system. This way, you bring the diagram closer to the code, improve consistency, and reduce the maintenance burden. I’ll come back to tooling in a later post.

There are other types of diagrams besides those in the C4 model that are useful in certain situations. For instance, sequence diagrams are great for showing complex interactions between systems. I’ll talk about some other diagram types in future posts.

Do you use C4 model diagrams? Are they worth the investment? Please leave a comment.

Update: C4 Model author Simon Brown got some answers to the above questions on Twitter:


Target Architecture

In the last two posts, we looked at generic architecture diagrams and security-specific diagrams. These diagrams reflect the current architecture of a system. This time we will look at using diagrams to depict a desired future architecture, or target architecture.

The point of a target architecture is to paint a picture of the desired state that will act as the North Star (or Southern Cross, depending on your hemisphere), in the sense that it guides all the little decisions we make every day when working on our system. This doesn’t mean we’ll always be moving straight towards the target, but we do want to make sure we don’t stray too far of the path.

However, a target architecture is not a static thing.

Assuming you don’t have a crystal ball, it will be hard to predict how circumstances will develop over the years. So think of a target architecture more as a moving target than as something set in stone. We need to keep an open mind at all times, and always react appropriately to changes, and one such reaction could be to update the target architecture as we learn more about our system, the customers it supports, the team that builds it, the evolution of the technologies it uses, etc.

Moving towards a target architecture usually doesn’t happen in a straight line.

So how do we come up with a target architecture in the first place?

One starting point is to look at the diagram that reflects your current state and identify things that give you trouble. Few systems are optimal, so you’re likely to find some things that you would do differently if you had a chance to start all over.

Another source of ideas comes from future requirements, i.e. requests on your backlog. The fact that the current architecture supports the current requirements doesn’t necessarily mean that it will be able to support all future requirements. Sometimes we need to create some architectural runway.

Once you’ve identified an area for improvement, you need to make a decision about whether it’s actually worth fixing. Some things are very costly or risky to fix compared to their benefit.

Next, write up your decision in the form of an Architecture Decision Record (ADR). The structured format of an ADR, which lists the positive and negative consequences of the decision, will help with getting everyone on the same page. It will also give you a nice historical record, which is especially important for any newcomers as the team evolves over time.

Every ADR records a decision. Each such decision constrains the solution space of the system in its own way. As the number of decisions grows, the resulting viable part of the solution space shrinks. The target architecture is a picture of a single point in this viable part of the solution space. Note that there could be other points that are viable as well, i.e. alternative target architectures.

Obviously, the solution space is multi-dimensional. But if we project it in two dimensions, we can visualize the relationship between target architecture and ADRs as follows:

Architecturally significant decisions constrain the viable solution space in which a target architecture lives.

If you find your team arguing about two different options in the viable solution space and you want to resolve this ambiguity, then hopefully the picture above will suggest the solution: you’re missing an ADR that shrinks the viable solution space to exclude one of the options.

What do you think? Do you find a target architecture a useful tool to guide your team’s day to day technical decisions? Do you use ADRs to document why the target architecture looks the way it does? Please leave a comment below.