I am moving the blog to https://sixro-on-software.blogspot.com/.
In the next months, I will close this one.
In this article, I’ll try to explain some software architecture diagram types. This will not be a comprehensive guide of all the types of software architecture diagram available, but I hope that it will help you in representing the architecture of your software.
What is a software architecture diagram?
First of all, we need to make clear what a software architecture diagram is: simply put, it is a representation of how things work in a software.
There are a lot of ways to represent a software architecture. I know 3 ways to do it:
- Conceptual Architecture Diagram
- UML Diagrams
- C4 Model
Conceptual Architecture Diagrams seem simple, but they are not. Basically, they represent the “big picture” of a software/system. Looking at it, the reader can immediately grasp how things work even in a very complex system.
UML (Unified Modelling Language) is really big (and probably this is the reason it is not used so often), but with just one or two diagrams we can do a great job in explaining our software architecture. Even today, when I need to explain how things work in a software, I draw an improvised Communication Diagram. In this way, I can give immediately an idea of the components, the relationship between them and how they interact each other. I am not a fan of Sequence Diagrams because I find they promote “procedural code” instead of allowing me to create “OO code”, but they are effective too (and by the way that was another story :D). In the last 10 years, I used just those 2 diagrams and sometimes the Use-Case Diagram. I don’t see a Class Diagram since 2005 and never seen used any of the other diagrams.
C4 Model is the most recent one. It represents the overall architecture using multiple views of it.
- Context diagrams: show just the systems and the relationship between each other. It gives you the “big picture”
- Container diagrams: decompose a system into containers (e.g. an application, …)
- Component diagrams: decompose a container into components, and relate the components to other containers or other systems
- Code diagrams: provide details about the design of a single component
To me, it seems an improvement of an old diagram called 4+1 architectural view model.
I have never used the C4 Model, so I won’t talk much about it, but I am pretty sure that combining a Conceptual Architecture Diagram with others diagrams mentioned in UML, you can reach almost the same result provided by C4 Model.
What should be included in software architecture diagram?
In a software architecture diagram, what you should include depends on the diagram and the type of diagram to choose depends on the audience.
Here some examples of what you should include.
This is an example of a Conceptual Architecture Diagram:
As you can see, at the center you have the core software mentioned as “Security Manager”, while on the edge you can see “external” parts such as (in this specific case) languages (on top left) that could use the software, databases (on the bottom), LDAP, etc… In the center, the software is composed by internal blocks that are shown in order to give the reader an idea of what the architecture contains. You can see also some interaction between some internal components and external parts (for example the arrows between “Cache” and the RDBMS) that could be used to reason implementation details worth to mention.
The following diagram is an example of Communication Diagram (that in older versions of UML was named Collaboration Diagram and even today you can find it with this name):
This diagram can be found on uml-diagrams.org (I suggest to take a look to that website, because it is really good in explaining UML).
The example contains a lot of blocks, labels, colors, etc…, but just to make things really simple, you have to remember one thing in order to draw a good Communication Diagram:
draw the main components of your software as blocks and connect them specifying also the sequence of execution
That’s it. Pretty straightforward. I never have the need to make it tool complex. Also because, if it becomes too complex, it means 2 things:
- you are explaining too many details
- your design is really too complex
For 1. I have one tip:
when you draw the components, this doesn’t mean that you have to draw all objects used by your software to work. You can draw just the main components. Leave the details to the code or to others diagrams (e.g. the Sequence Diagram, the Class Diagram, etc…)
For 2. pay attention, because sometimes a Communication Diagram can give you some hints on what is wrong in your architecture: maybe you can see in front of your eyes that there is a component that is not needed. On the other side, sometimes when you translate in code a design made on paper, it won’t work because coding is a totally different beast.
The last example is a Sequence Diagram:
This is a very simple Sequence Diagram, but it is good for explaining how it works.
On the left, you can see the operation checkEmail called on Computer. When this happens, Computer calls sendUnsentEmail of Server. After that, it calls newEmail of Server waiting for a response. The next steps can be read by the reader as an exercise.
I have always considered Communication Diagrams more maintainable when compared to Sequence Diagrams, if you like to draw them by hand. But nowadays, there are a lot of free software to draw Sequence Diagrams that can be updated in a couple of seconds (I’ll mention them in the next paragraph).
One thing that I noticed in my career is that, when people asked to see a Sequence Diagram of a piece of code, I could bet that the code was full of code smell or unmaintainable or unexpectedly complex 🙂
How to draw a software architecture diagram?
In order to draw a software architecture diagram you can use some software freely available, but I’d not refuse to draw them by hand. For example, I liked to draw a communication diagram while explaining the architecture of a software to a new team member.
In the next paragraphs, I’ll mention some free software I found pretty simple to use:
diagrams.net (online): it was known as draw.io few years ago. It is really good to draw all software architecture diagram types, but I’d use it mainly for Conceptual Architecture Diagrams and Communication Diagrams.
For Sequence Diagrams I found alternatives that are far simple than diagrams.net
Dia (installation): I would say that with Dia you can probably create any diagram. Really. If you look at the screenshots section of the website, you’ll see that I am telling the truth 🙂
Violet UML editor (Eclipse plugin): I used this in the past as an Eclipse plugin. I remember it was doing a good job, but I never had the chance to try it in my last job (so almost 7 years :D). I cannot give any feedback about the more recent versions.
ArgoUML (installation): I used ArgoUML a lot in the past. It is really good. You can write all UML diagrams with it. It is available since 1998… more than 20 years! The link I put is the Github project so that you can then find the right way to install it on you computer.
The UI is made with Java (I think Swing) so it can work on any desktop.
In conclusion
There are plenty of software architecture diagram types.
Choosing the right one is a matter of audience.
Non-technical people will be glad to view a Conceptual Architecture Diagram of your software. Technical people will be glad to view a Communication Diagram (or a Sequence Diagram) in order to understand how it works.