structurizr.org - introduction and open source tooling | structurizr.com - free and paid tooling to render diagrams, documentation, and architecture decision records

Introduction

There has been a trend over the past few years towards text-based tooling and "diagrams as code", with the most popular examples including PlantUML, WebSequenceDiagrams and Mermaid. With these tools, the diagram source is provided as text using a proprietary 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.

Diagrams as code 1.0
PlantUML, Mermaid, WebSequenceDiagrams, Graphviz, etc

Diagrams as code 2.0
Structurizr

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

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.

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.

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.

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 or desktop app
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"));
}