Software architecture

Architecture diagrams help in easier understanding and communication about software among different groups of people, including clients and the programming team.

Diagrams allow the translation of business requirements into technical software descriptions. They are particularly useful for non-technical clients and product owners who need help understanding code.

Architecture diagrams allow for quick feedback, among others, from programmers and other architects, which allows for faster correction and improvement of the solution. Architecture diagrams also allow for consultation of the solution with other architects and team members, enabling a focus on the business problem rather than technological nuances.

Who are architecture diagrams for

Diagrams are created for various recipients:

• Customers, product owners - generally non-technical people who need help understanding code. When presenting architecture to people who have to “sign off” on it, presenting diagrams is crucial. The diagram is a bridge between business requirements and code.

• Developers can see on the diagram whether the solution designed by the architect makes sense and fits together. Developers can provide feedback, and the architect can make changes (sometimes quickly, even at the same meeting with developers). When you work directly on code, making changes is more challenging than on diagrams.

• Architects draw the diagram for themselves. The diagram immediately shows whether the solution makes sense or not. Operating on the level of diagrams is faster than on the code level and allows you to focus on the business problem rather than on technological nuances. In addition, consulting a solution with other architects and team members is easier when you can show a drawing.

Types and Levels of Diagrams

You can find examples of many diagrams on the internet, such as deployment architecture diagrams, integration diagrams, etc. You can draw anything on a diagram; what matters more is how you draw it. In my work, I use a diagramming technique called the c4 model.

c4 model

In the c4 model, systems are described at four different levels:

1. Context

2. Container (not to be confused with Docker containers)

3. Component

4. Code

These levels differ in their level of detail. They can be compared to a map that you can zoom in on. The more zoomed-in the map, the more details you see. Similarly, in c4 diagrams, at the context level, you see the general outline of the system and what it does.

At the container level, you see what elements the system contains. Here you will already see, for example, the database, web application, backend applications, etc.

These two levels are perfect for showing the system to non-technical people, as they show what it looks like and how it should work without going into implementation details. (The container level may require some technical knowledge, while the context level should be understandable even to non-technical people.)

The next two levels show more technical details and are great for discussions with programmers. At this level, each container is zoomed in so that you can see what components it is built of.

At the last level, code, we already have the “meat” for programmers, such as classes, interfaces, and relationships. These are typical UML diagrams.

Interestingly, this level is usually not required or drawn.

You can read more about the c4 model here: https://c4model.com/

Sequence diagrams

A sequence diagram is another type of diagram that is very useful in understanding how something should work. To create these diagrams, I used this tool:

https://sequencediagram.org/

Advantages of sequence diagrams

• They are linear and show how something works from top to bottom and from left to right. Individual steps can be numbered and easily presented and discussed.

• Even very difficult scenarios can be shown on them.

• They work at every level (in c4 notation).

• They are great for teamwork.

• They also serve as documentation later on.

Diagramming tools

In addition to sequencediagram.org which I mentioned earlier, I recommend using Miro for drawing diagrams. It is easy to use and has a free version for starting.

Problem with diagrams

Unfortunately, there are also some drawbacks to using architecture diagrams. Some of them include:

• Possibility of distorting reality - architecture diagrams may only show a part of reality, not the entire system. This can lead to a wrong interpretation, which in turn can lead to design or implementation errors.

• Difficulty in updating - architecture diagrams are static and do not reflect changes in the system, which happen frequently. Updating diagrams can be time-consuming and labor-intensive.

• Lack of standards - the lack of standards for creating architectural diagrams can lead to difficulties in interpreting diagrams by different people.

• Complexity - architecture diagrams can become very complex and difficult to understand, especially for people unfamiliar with the system.

Architect astronauts

The term refers to “architects” who spend too much time and energy creating perfect diagrams and plans rather than working on code and solving business problems.

In other words, the architect focuses more on design than implementation, which can lead to project delays, costs, and customer dissatisfaction. It should be remembered that diagrams are a tool, not an end in themselves.

Another problem is that stereotypical architects have often moved so far away from programming that they may be detached from reality. How can someone who does not work with code daily design a system in isolation from reality?

An architect cannot sit in a corner and draw diagrams that will later be ignored and useless. Communication and continuous feedback collection, preferably through developer teamwork, will make the diagrams valuable for your team. I say no to astronaut architects!

Even the best-drawn diagram can be useless for one simple reason: it will not be properly explained to others, which means it will not be understood or used in work.

---

Summary

Architecture diagrams are a tool that facilitates understanding and communication about software among different groups of people. Their advantage is the ability to translate business requirements into a technical software description easily. It is particularly useful for people not associated with the technology industry, such as customers and product owners.

Moreover, diagrams allow for quick feedback, which enables faster corrections and improvement of the solution. However, it should be remembered that diagrams should be a supporting tool, not an end.

It is worth considering their disadvantages when using diagrams, such as the possibility of distorting reality, difficulty updating, lack of standards, or complexity. Therefore, it is important to use diagrams properly and focus primarily on working on the code and solving business problems.

And do you use diagrams in your daily work?