About

Software architecture diagrams are a great way to explain and document how a software system works. Static diagrams, whether drawn on a whiteboard or with a general purpose diagramming tool such as Microsoft Visio, tend to get out of date quickly and often don't reflect the real structure of the code. On the other hand, automatically generated diagrams, such as UML class diagrams created by reverse-engineering the code, typically show far too much detail, limiting their usefulness.

The goal of Structurizr is to allow software developers to easily create software architecture diagrams that reflect the code. Here's how Structurizr compares to other tools.

Structurizr vs other tools

Whiteboard

Sketching out software architecture diagrams on a whiteboard is probably the starting point for many of us. Although it's quick to get started, the resulting diagrams are often erased because somebody else needs to use the whiteboard. Taking a photo of the whiteboard allows you to at least capture the sketches, but that resulting photo isn't something you can update easily.

Whiteboards are a great tool for sketching out ideas, but the result is a collection of transient, static diagrams.

A whiteboard

General purpose diagramming tools

There are a number of popular general purpose diagramming tools available that software teams typically use for creating software architecture diagrams. These include Microsoft Visio, OmniGraffle, draw.io, Creately, Gliffy, Lucidchart, etc. The key strength of a general purpose diagramming tool is that you can create almost any type of diagram you can imagine. You usually also have full control over what every element on your diagram canvas looks like because aspects such as element size, element alignment, line thickness, font size, text alignment, etc are all almost infinitely customisable. General purpose diagramming tools give you a lot of power.

A general purpose diagramming tool

The trade-off here is that unless you're using a pre-built template, you're effectively starting with a blank canvas. In order to create a software architecture diagram, you need to figure out what notation you'd like to use, create boxes on the diagram canvas, resize them, add text as appropriate, set the font size and text alignment, link boxes together with lines, specify which end of the line should be an arrowhead, add text to the lines, etc. There are some exceptions, but generally each diagram is exactly that, a static diagram rather than a view onto a single model. This means changes to the name of a box or an element style on one diagram will not automatically propagate to other diagrams.

General purpose diagramming tools give you a lot of power, but the responsibility to keep the resulting diagrams consistent and up to date is yours.

Static analysis tools

This category of tools allows you to perform static analysis of your codebase. Popular examples include Structure101, Lattix, NDepend, Sonargraph, JDepend, JArchitect, etc. The primary focus of these tools is to let you explore and refactor the structure of you code, typically using rich visualisations that depict the structure of your code. Although these diagrams help you explore your code, they're not really "software architecture diagrams". Many of the static analysis tools are expensive and difficult to use, which doesn't make them as popular as they perhaps should be.

A static analysis tool

Static analysis tools are very powerful for exploring a codebase, but they don't really generate diagrams that are useful for explaining how a software system works at multiple levels of abstraction, such as those you might want to use in a presentation or documentation.

Modelling tools

There are many modelling tools available, both free and commercial, that support a number of different modelling languages and notations such as UML, ArchiMate, SysML, etc. Popular examples include Enterprise Architect, MagicDraw, Rational Software Architect, Visual Paradigm, Archi, ArgoUML, etc. There are also modelling plugins for many IDEs. The purpose of a modelling tool is to let you build a rich model of your software system, which you can subsequently visualise using a number of different views.

Reverse-engineering a codebase

The power of a model is that it provides consistent naming of elements between diagrams, as well as introducing a set of rules to describe elements and their relationships. The downside of many traditional modelling tools is that it takes some effort to create the model and keep it up to date, plus such tools can sometimes seem overly restrictive or heavyweight if you simply want a quick diagram. Although some modelling tools will let you reverse-engineer a model from code, the resulting model is usually very detailed. If you point a modelling tool at a Java codebase, that modelling tool will see the basic constructs that you use to build your software; namely interfaces, classes and packages. Unless you provide some rules, reverse-engineering tools will see classes rather than components.

Tooling aside, there's still the question of notation, and specifically UML. UML provides a standard set of abstractions with which to think about and describe a software system, along with a standard set of boxes and lines (the notation) to represent those abstractions. Anecdotal evidence suggests that UML usage is on the decline, with notational complexity and a lack of UML knowledge commonly being cited by teams that no longer use it.

Modelling tools are also very powerful but it can take a lot of effort to keep the models up to date, and reverse-engineering a model from code often produces results that are too detailed.

Text-based tools

There has been a trend towards the use of simple, single-purpose, text-based tools in recent years, that provide a way to convert a textual representation of something into a diagram. Examples include PlantUML, nomnoml, yUML, WebSequenceDiagrams, Graphviz, etc. These tools are very easy to use and the source text can be easily version controlled. Also, it's relatively straightforward to automate the use of these tools in order to generate diagrams and documentation during the build process.

Text-based tooling

In essence these are domain-specific languages (DSLs) to describe diagrams, which therefore provide some rules and a degree of structure as to what can be included on each diagram that is generated. However, the underlying model cannot be queried and the textual diagram definitions aren't connected to the code, unless you build some tooling to automatically generate it.

Text-based tooling is quick and easy to use, but it still doesn't create a real model of the code that can be queried.

Structurizr

Structurizr combines the power and richness of having a model, with the ease of use we get from text-based tools.

The C4 model provides a way for software developers to create a relatively rich, yet simple, model of a software system, which can be visualised using a simple collection of hierarchical diagrams. The software architecture model is created by writing Java or C# code in conjunction with the client library for Java or .NET, which means the majority of the software architecture model can potentially be extracted from your code. Integration of this process with your continuous build environment means that your software architecture model remains up to date.

Structurizr

Structurizr is a collection of tools to visualise, document and explore your software architecture.

Simple

No more endless hours spent messing with drawing tools, manually drawing boxes and lines. You create a software architecture model using code, Structurizr visualises it for you.

Versionable

The software architecture model is created using code, so it can be easily versioned alongside your production code.

Scalable

Static diagrams are hard to change and work with once they start to get large. Having the software architecture model as code puts you in control.

Up-to-date

Integration with your build process means your software architecture model can be continuously kept up-to-date, especially if you extract parts of the model from your codebase.

More information

Simon Brown's "Visualise, document and explore your software architecture" talk from the NDC London 2017 conference provides a great introduction to software architecture diagramming and the tooling provided by Structurizr.