Diagrams as code Diagrams as text Rendering tools Usage recommendations

This is structurizr.org - the community site. If your tooling is compatible with the Structurizr JSON format, let us know and we'll add it to this page.
Looking for the Structurizr cloud service/on-premises installation?

Introduction

There has been a trend over the past few years towards text-based tooling, with the most popular examples including PlantUML, WebSequenceDiagrams and Mermaid. With these tools, the diagram source is provided as text using a special domain-specific language, which the tool then visualises, typically with an automatic layout algorithm. These tools generally have a low barrier to entry, and the source text is easily version controlled. Also, it's relatively straightforward to automate the use of these tools in order to generate diagrams and documentation during your build process.

However, each diagram needs to be defined separately, typically in a separate text file. If you have the same element on two diagrams, and you want to change the name of that element, you need to make sure that you change the name everywhere it's used. The global search and replace features in most developer tooling does make this less of a problem, but it's just one way that a collection of diagrams can easily become inconsistent if not managed properly. To solve this problem, we can create a single model, and visualise multiple views of it.


tl;dr

If you just want to create some software architecture diagrams:

  1. Read the 5 minute introduction to the C4 model
  2. Start with the Structurizr DSL
Structurizr DSL screenshot

What is Structurizr?

Structurizr is a collection of tooling to create software architecture diagrams and documentation based upon the C4 model. Structurizr was started in 2014 by Simon Brown (the creator of the C4 model), and has grown into a community of tooling, much of which is open source. In Structurizr terminology, a "workspace" is a wrapper for a software architecture model (elements and relationships) and views. Workspaces are described using an open data format (OpenAPI 3.0 definition), which decouples model authoring from diagram rendering.

Overview


Structurizr is "model-based", making it possible to generate multiple diagrams from the same model to ensure consistency, with details being in sync across all diagrams. And since the models are created using code/text, they are also versionable alongside your codebase in your source code repository.

Authoring tools

There are a number of tools for creating a workspace; including a text-based DSL and code-based client libraries.

Diagrams as text

Diagrams as text

The Structurizr DSL (as mentioned on the ThoughtWorks Tech Radar - Techniques - Diagrams as code) allows you to create multiple diagrams, in multiple output formats, from a single DSL source file. The DSL is designed to be used in conjunction with the Structurizr CLI. A number of VS Code extensions are also available, and the Structurizr cloud service/on-premises installation provide a web-based DSL editor, with diagram previews and real-time collaboration. The Structurizr DSL is the recommended authoring option for most teams.

Alternatively, Arch as code is a command line utility to create software architecture models as YAML.

Create content using code

Diagrams as code

Libraries are available for a number of programming languages, all compatible with the Structurizr JSON format for defining a workspace. This authoring option is recommended for teams who want to use code to help build their software architecture model (e.g. component discovery via static analysis, parsing distributed log files, etc). The following libraries are available, all of which are open source.

Rendering tools

Similarly, there are number of tools that can be used to render diagrams in a workspace, each offering a different set of features and integration options. All of the diagrams below are rendered from the same Structurizr DSL source file - see example.


Structurizr cloud service and on-premises installation

The Structurizr cloud service and on-premises installation provide a web-based renderer, with diagrams that are interactive, animatable, and embeddable. It can also publish Markdown/AsciiDoc documentation and architecture decision records (ADRs).

Structurizr

Structurizr

Structurizr

PlantUML

A text-based diagramming tool - export available via the Structurizr CLI.

PlantUML

C4-PlantUML

Mermaid

A text-based diagramming tool - export available via the Structurizr CLI.

Mermaid


WebSequenceDiagrams

A text-based diagramming tool - export available via the Structurizr CLI (dynamic views only).

WebSequenceDiagrams


Ilograph

A text-based modelling tool - export available via the Structurizr CLI.

Ilograph

Here are some of the key differences between the various rendering tools.

Structurizr PlantUML Mermaid WebSequenceDiagrams Ilograph
Shapes
PlantUML

C4-PlantUML
 UML Boxes
Automatic diagram key/legend
(colours only with C4-PlantUML)
Double-click to zoom
Interactive/animations
Rendering Web browser Server Server Server Web browser
PNG export
SVG export
PDF export

Other tools

Here are some other related tools.


Structurizr Puppeteer

A command line utility to automate the export of diagrams in PNG/SVG formats from the Structurizr cloud service/on-premises installation.

Structurizr macros for Atlassian Confluence Server

Macros to embed diagrams from the paid Structurizr cloud service/on-premises installation into Atlassian Confluence Server.

Structurizr macros for Confluence on Atlassian Cloud

Macros to embed diagrams from the paid Structurizr cloud service/on-premises installation into Confluence on Atlassian Cloud.

Usage recommendations

Teams tend to ask how many workspaces they should create/use. There are a number of ways to think about workspaces, and how they align with your organisation:

Here are some example scenarios.

Example 1: single software system (monolithic), single team

A software development team is building a software system comprised of a monolithic application and a database. Since the single team owns and is responsible for the entire software system, the recommendation is to document this in a single workspace.

Example 2: single software system (N microservices), single team

A software development team is building a software system comprised of N microservices (plus their corresponding data stores, if applicable). Since the single team owns and is responsible for the entire software system, the recommendation is to document this in a single workspace.

Example 3: single software system, multiple feature teams/squads

As examples 1 and 2, but multiple feature teams/squads are contributing to the software system. In this scenario, treat the feature teams/squads as an orthogonal concern. The recommendation is to document this in a single workspace, so that all of the documentation for the software system resides together.

Example 4: multiple software systems, multiple feature teams/squads

As example 3, but the feature teams/squads are contributing to N software systems. Again, in this scenario, treat the feature teams/squads as an orthogonal concern. The recommendation is to document each software system in a separate workspace.

Example 5: microservices development, multiple teams

An organisation is building a software system comprised of N microservices (including their corresponding data stores, etc if applicable). Each microservice is owned by a separate software development team. Due to the separate team boundaries, the recommendation is to treat each microservice as a separate software system, and to therefore document each microservice in a separate workspace. An additional workspace can be used to model the system landscape (i.e. the people and software systems).

In summary, you have one workspace documenting the system landscape, and one workspace per microservice.