Why use code to create a software architecture model?

There has been a trend over the past few years towards text-based tooling, with popular examples including PlantUML and WebSequenceDiagrams. With these tools, the diagram source is provided as text using a simple domain-specific language, which the tool then visualises. 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 very easily.

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.

In essence, rather than writing a static text file, you're writing one or more short programs that create a software architecture model during their execution. Using code rather than a static domain specific language makes it much easier to automatically extract model elements from a codebase and manipulate the model in a number of ways. Here's what a typical "software architecture as code" program might do.

Why use code to create a software architecture model?


In summary, some benefits of using code to create software architecture models are:

  • 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.