structurizr.org - the open source community site
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 propriety 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

Structurizr lets you create multiple diagrams from a single model, and those diagrams can be rendered with a number of tools, reducing vendor lock-in. 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 JSON data format (OpenAPI 3.0 definition), which decouples model authoring from diagram rendering.

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.


Overview


If your tooling is compatible with the Structurizr JSON format, let us know and we'll add it to this page.

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) to create data-driven software architecture diagrams. 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


Ilograph

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

Ilograph

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


DOT (via Graphviz)

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

DOT (via Graphviz)


WebSequenceDiagrams

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

WebSequenceDiagrams



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

Structurizr (diagram) Structurizr (graph) PlantUML Mermaid DOT WebSequenceDiagrams Ilograph
Example
Shapes
PlantUML

C4-PlantUML
UML Boxes
Automatic diagram key/legend
(colours only with C4-PlantUML)
Click to zoom
Interactive/animations
Rendering Web browser Web browser Server Server Server Server Web browser
Diagram layout Manual & automatic Automatic Automatic Automatic Automatic Automatic Automatic
PNG export
SVG export
PDF export

Custom tools

Since workspaces are described using an open JSON data format (OpenAPI 3.0 definition), it's relatively straightforward to build your own custom tooling to consume that data; perhaps for rendering views with your own diagramming tool, or to integrate the data with your internal dashboards and service catalogs. Although JSON is an easy data format to work with, using one of the code-based client libraries (see authoring tools) will provide a quicker starting point. For example, you can load a JSON workspace definition using the Java client library as follows, with the resulting Workspace object providing an easy way to navigate/manipulate/translate/export the data:


public static void main(String[] args) throws Exception {
    Workspace workspace = WorkspaceUtils.loadWorkspaceFromJson(new File("workspace.json"));
}

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 to help you decide how to structure your software architectue models.

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 model this in a single workspace.

  • Number of workspaces: 1

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 model this in a single workspace.

  • Number of workspaces: 1

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 model this in a single workspace, so that all of the documentation for the software system resides together.

  • Number of workspaces: 1

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 model each software system in a separate workspace.

  • Number of workspaces: N

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

  • Number of workspaces: N + 1