Why code?

Although there are many tools that will allow you to create diagrams via a user interface by dragging and dropping elements onto a diagram canvas, there has been a trend over the past few years towards text-based tooling. The diagram source is provided as text using a simple domain-specific language, which the tool then visualises. Popular examples include PlantUML and WebSequenceDiagrams. These tools are fantastic for quickly creating simple static diagrams, but they are typically used in a standalone manner, are not necessarily connected with the code they describe and can therefore become out of date.

Architecture description languages

The idea of using text isn't new, and attempts have been made in the past to create a more formalised approach using something called an architecture description language. Some, like Darwin for example, offer a text-based language that you can use to describe the architecture of a software system. Diagrams are then created using supporting or additional tooling such as Graphviz. Using a text-based language is certainly appealing for us as software developers, but architecture description languages have never really seen mainstream adoption.

Software architecture as code

The software architecture model used by Structurizr is represented as a JSON document, which can be easily created by writing code using the open source Structurizr for Java or Structurizr for .NET client libraries. Creating a software architecture model as code provides a number of interesting opportunities for creating the model and communicating it.

  • Code is familiar: Code is familiar to us as software developers, so let's take advantage of this rather than creating another language with which to represent a software architecture model.
  • Flexibility for creating models: In addition to manually writing code to create a software architecture model, we can also write code to extract architectural concepts (e.g. components) from our production codebase using techniques such as reflection, introspection and static analysis.
  • Flexibility for visualising models: Writing code to create the views of a software architecture model provides you with the ability to slice and dice the model as needed. For example, showing all components for a large system will result in a very cluttered diagram. Instead, you can simply write some code to programmatically create a number of smaller, simpler diagrams; perhaps one per vertical slice, web controller, user story, etc. You can also opt to include or exclude any elements as necessary.
  • Versionable: Since the models are code, they are also versionable alongside your codebase.
  • Living documentation: The code to generate the model can be integrated with your automated build system to keep your models up to date; providing accurate, up-to-date, living software architecture diagrams that actually reflect the code.

In essence, Structurizr is an implementation of an executable architecture description language, specifically focussed around the C4 model.