Architecture diagrams made easy

When you're starting a new project it's crucial that you are able to understand quickly how the systems that you'll be working on connect to each other and the general idea behind their architecture. Then on a deeper level, you'll need to understand how the components of those systems works together.

A code generated container diagram

Often happens that they give you a general architecture diagram that's really neat but it doesn't tell you exactly what you need to know in order to be able to do your job.

Other times you have to implement or refactor some features that alter the way things are connected at the moment and you have to re-route them or connect to other systems.

On rare occasions, you start a brand new project in which you are responsible to define how the components of the particular software you're trying to build connects to one another.

Throughout the years I had the chance to experiment all of the aforementioned situations. In some of them I had more documentation at hand and in others... well... let's say that it had some room for improvement in that area.

At the time I was working for Southwest Airlines the diagrams (sequence, modules, etc) were made using WebSequenceDiagrams and/or Microsoft Visio. They looked really neat and everything. But there were a few problems from my point of view: 

• When the diagrams were done then the cost of updating them was really high. You needed to copy the source file if it was in Visio and change them using drag & drop with the mouse. A hideous task for a software developer.
• For some additional features it was necessary to have a premium account.
• The tooling was different from the everyday one.
• It was complicated to version them.
• Collaboration was limited.

That's me making a fool of myself...

 

So when we had to design a new login feature I decided to investigate how can that be done better. I definitely was looking for a tool that you can write the code and it would create the diagrams from it (Just like WebSequenceDiagrams but with versioning and open source). That's when I found PlantUML.

By using that tool it was really easy to maintain architecture diagrams as they where evolving alongside the features or the new requirements that we need to implement. Building a sequence diagram to visualize how particular services should interact had become an enjoyable task for developers and we also had that versioned in our code repository. Even when I had to document a card it was really painless to write a few lines and render the diagram (a sequence diagram for instance) on it just with the use of your favourite IDE.

A few years later when moved to LATAM Airlines project they were using PlantUML as well but they made a huge improvement. On top of PlantUML they decided to use the C4 Model for modeling software architecture. That is exactly what I want to show you in this post.

At this point you may be willing to get your hands dirty and start writing those beautiful diagrams, don't you? Well, the wait is over!

The first thing we need to do is clone this repository so we can have all the templates for the C4 software architecture model as foundation. You may also want to take a look at the README now that you are at it 😉

git clone https://github.com/plantuml-stdlib/C4-PlantUML.git

Note: There's no need to clone the repo because you can use directly by importing the web file from your diagram files. Nonetheless I think it's a good idea to take a look at it and play around with the templates.

Let's create our own project folder to start working on it. For simplicity I will call it "diagrams". Create the folder right next to the downloaded repository one.

Now download the PlantUML executable into it by issuing the following command:

wget https://github.com/plantuml/plantuml/releases/download/v1.2021.14/plantuml-1.2021.14.jar

At this moment we can start by creating our first dummy diagram. Copy and paste the following snippet into a dummy.puml file:

 

Now with the following command we'll generate the awesome image file:

java -jar plantuml-1.2021.14.jar .

And after a few seconds you should see a file called "My_First_Diagram.png" in the same folder.

Example diagram

 

I'm feeling that you are starting to think some ways in which you cant start using it in your project by now...

 

If you're using IntelliJ or VS Code there are fantastic plugins that'll render this as you type the code. The plugin for IntelliJ can be found here.

The invitation to start making your own beautiful architecture diagrams by code has been made! I think that with a little bit of scripting you can start adding this diagrams along with your codebase so you'll always have your architecture diagrams clean and updated.

I hope you find this post useful and entertaining 😁

 

See you next time!

Moved to The Netherlands!

It's been seven years since I did my last post in this blog. It's a completely different world now! At least for me many things happened in between: I changed my job, got my engineering degree, got married and moved to The Netherlands!

The last topic is precisely what I want to talk about it in this post.

I'm gonna tell you a little bit of our history on why this movement.

A few years ago, we had the chance to buy really cheap flights and travel to Europe. Since we're from Argentina it was something we really like to do and one of a kind opportunity. I have to give the credits for this to my wonderful wife Roberta because she was the one pushing to find the tickets. I only said the words "buy them" while taking a bus to Buenos Aires during a business trip. We had to make the purchase within a few hours, not much time to decide!

One of the places we stayed at that time was Amsterdam. The moment we arrived at the city centre was a turning point for us. We looked at each other to say:

We have to live here one day!

A tour we took around the canals

Fast forwarding into recent days, we were struggling about what are we supposed to do with our life. Because we knew we wanted to live abroad and we also had a relocation to Chile that got stuck in between bureaucracy and covid restrictions... For that we had the feeling that we were going nowhere...

Enjoying the afternoon

One day my wife found a job posting in Linkedin about a company that offered relocation to The Netherlands. This awesome company is called WAES 😉. So I decided to give it a shot. I posted my resume and waited for the recruitment process.

After a few days I got a message requesting for a videocall, which of course I replied. After that nice interview, a coding challenge and a technical interview I was offered a contract with a relocation package for me and my wife! We couldn't believe it!!! Our dream was finally becoming a reality!

So since about a month ago we're happily living in The Netherlands!👫

That's it for now so stay tuned! I will create new posts about living here and the whole process I had to go through!

See you soon! Hope in less than seven years... 😜

In the meantime, take this cookie 😁

A cookie from Van Stapele Koekmakerij