EasyGraph: a new tool to create easily UML Class Diagrams and Cloud Architecture Charts

Introduction

Every time I would like to draw a technical diagram I always wonder why nobody seems to have created a tool to make it very simple.

For example, when I studied Object-Oriented Design, they taught me how to draw the Class Diagram in UML. This is a very useful tool to better design, discuss, learn and document a new piece of software. However nobody actually does it in the real world because the time spent to do it might not be negligible.

The first time I saw the importance of diagrams in the workplace was when I started working with Cloud Infrastructures in AWS. I remember clearly the time I spent just drawing the topology of our infrastructure on a slide. I soon realized it was not the quickest tool to use.

Then I tried Draw.io [1]. It has a good collection of symbols to use, but it was an online tool (I prefer a desktop application) and the drawing experience can still be improved (lack of automatic laying out, need to draw the lines one by one, not very good behavior when you move an element in a different position).

Last but not least you might have heard about Dia [2] (from GNOME) or the equivalent Umbrello [3] (from KDE). Dia is the closest to my ideal tool, but still it should require less effort if the goal is just to display a bunch of connected icons. I was able to use Dia proficiently but I had to import a custom collection of icons downloaded from AWS and prepared for Dia thanks to a script [4]) found on GitHub.

Another impressive tool is GraphViz [5] where you describe your network of nodes in DOT language and it produces an image with the graph automatically laid out. There are also some examples of how to use it for class diagrams 6 but customization of the appearance of the elements is limited and, if you work in a team, it is easier to adopt a tool that everyone can use without having to learn a new language (even though the DOT language for GraphViz is very simple).

In conclusion I haven’t found yet a tool that meets my needs. I would like to join the friendliness of Dia with the automation of Graphviz, but without compromising the space for the user to manual tuning.

I had this project on my TODO list for a while and recently one of the trainees in my company has asked me to provide guidance in improving his skills to become a good software developer. I clearly pointed him to SOLID principles [6] and Design Patterns [7], but the best way to learn them is when you try to apply the theory in practice. Finding a good exercise looks like a trivial task, but it is actually not that simple. When I was scanning in my head for a good project to do, my passion for the topic woke me up and I found new energy to start this project.

Functional Requirements

What are the features I would like to have in my graph tool? This is the list:

I want to be able to create well-organized graph as quickly as possible
Adding an element and connecting two elements should be possible with a small number of points and clicks.
It is possible to let the software automatically handle the layout, but it is always possible to manually move the elements.
the drawing of the lines between elements is fully automated (no need for manual intervention)
The number of interconnections for each node is not too high (probably 3 to 5 connections)
possibility to save the graph representation in PDF, PNG and JPEG
possibility to reload the saved graph for future editing (support at least one the output formats).
the main use cases are infrastructure and class diagrams, but more use cases will be added in the future
The software should work in Linux and Windows

As you can see I tried to imagine what I want to build. I have mixed functional and non-functional requirements and I have probably been vague and not complete in multiple aspects. That is how requirements look like in the real world :D

Like the real users, I tried my best to explain what I need and during development I will probably change my mind on some requirements. To cope with this I will not use a Waterfall approach, but I will develop the product with an agile mindset, user stories and feedback loops.

Technologies and libraries

Let’s see in this section if I already have a couple of ideas of the ingredients I will use in this project.

To be able to reload a graph saved in PDF for future editing, I can embed an attachment in the PDF [8] with the relevant data
To achieve the same goal as the previous point for PNG and JPEG I can use the fields in the metadata (any string can be saved there) [9] [10]
I have a bunch of technologies I would like to try, so the design of classes and modules should be independent of the framework
I might start implementing a graphical frontend for Graphviz since it could be the minimum viable product 12
For different reasons, the languages I will consider to use are: C, Java, Go (GoLang)

Software Architecture

I recently heard about the Clean Architecture of Robert C. Martin [11]. It can be seen as a variant of the traditional Layered Architecture where each layer is represented as a concentric circle. The outmost circle is basically the technologies we want to use, while the core represents the most intrinsic part of the business domain. The idea is to divide the parts of our application based on how frequently they are going to change during the evolution of the product. For example if the software should handle car maintenance, it is unlikely that a concept like car will go out of scope. On the contrary it is possible that we start developing the application with a fast prototype in python/sqlite for a quick demo with the customer and then we will replace the database with a more powerful MySQL or PostgreSQL.

Even if you already know your technological stack, it is a good practice to decouple the details of which framework, databases and UI you are using in order to improve the testability of the core functionality (entities and business logic).

At the moment I have experience in Java on a professional level, I have always loved the C language because it is the perfect tool to understand how stuff works and, recently, I started to learn Go (GoLang) which is becoming more and more popular.

The flexibility provided by the Clean Architecture will let me play and try different implementations using all the languages and technologies I want to try.

The class diagram of the entities and use cases will be the same for all the implementations.

My representation of the Clean Architecture

At first I didn’t find intuitive the circular representation and I have read online other people with the same opinion. Of course all of us eventually got it with a relatively small effort, however we might argue there is a better way to represent the layers:

Layer	Description
Core / Domain Invariants	What never change because it is an intrinsic part of the domain (Entities and few Behaviors)
Business Logic / Use Cases	What we want to do achieve with the Entities and their intrinsic behaviors
Adapters	How our abstract representation of the problem interact with the underlying technologies
Persistency / UI / Frameworks	The framework/technology dependent part of our software

If we represent with an arrow the source code dependencies, the original Dependency Rule says “the arrows can point only inward in the circle”, in our representation all the arrows point on the upper level.

You will find more examples on how to apply the Clean Architecture in multiple articles (for example [13] [14] [15])