Skip to content
@structurizr

Structurizr - C4 models as code

Visualise and document your software architecture with the C4 model
README.md

Structurizr - "models as code"

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.

Structurizr is a collection of tooling to create software architecture diagrams and documentation based upon the C4 model for visualising software architecture. 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.

tl;dr

Structurizr lets you create a single model with multiple views, which can be rendered with a number of tools. If you just want to create some software architecture diagrams quickly:

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

Authoring tools

In Structurizr terminology, a "workspace" is a wrapper for two things:

  1. Model: your software architecture model, consisting of elements and relationships.
  2. Views: views onto the model, which will ultimately be rendered as diagrams.

Workspaces are described using an open JSON data format (an OpenAPI 3.0 definition; see structurizr/json), which allows model authoring to be decoupled from diagram rendering.

There are a number of tools for creating a Structurizr compatible workspace.

There are also a number of ports of structurizr/java, including:

The Structurizr DSL is the recommended authoring tool for most teams, with the code-based tools being useful 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. It's also possible to use a hybrid approach, with DSL and code.

Rendering tools

There are number of tools that can be used to render diagrams in a Structurizr workspace, each offering a different set of features and integration options.

  • Structurizr Lite/on-premises/cloud service: A browser-based diagram and documentation rendering tool with interactive diagrams, "double-click to zoom", etc.
  • c4viz: A browser-based diagram renderer, with diagram navigation and "click to zoom".
  • Structurizr Site Generatr: Generates a HTML microsite with diagrams, documentation, and a UI to explore the model.
  • Kroki: Kroki generates diagrams from a number of text-based formats, including the Structurizr DSL.
  • Git for Confluence | Markdown, PlantUML, Graphviz, Mermaid: A Confluence plugin that will render a specific diagram from a Structurizr DSL file stored in your git repo.
  • structurizr/export: A collection of Java classes to generate diagrams as PlantUML, Mermaid, DOT, and WebSequenceDiagrams. An export to Ilograph is also available.
  • structurizr/cli: A command line utility for Structurizr, designed to be used in conjunction with the Structurizr DSL, supporting the ability to push a workspace to the Structurizr cloud service/on-premises installation, and export views to PlantUML, Mermaid, DOT, WebSequenceDiagrams, etc formats.

All of the above diagram rendering tools use an automatic layout algorithm, with the exception of the Structurizr cloud service/on-premises installation/Lite, which provides both automatic and manual layout facilities.

Custom tooling

Workspaces are described using an open JSON data format (see structurizr/json), so 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.

Structurizr tooling overview

Although JSON is an easy data format to work with, using one of the code-based authoring tools (see above) will provide a quicker starting point. For example, you can load a JSON workspace definition using structurizr/java 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"));
}

Getting started

The separation of workspace authoring from diagram rendering makes it possible to use the Structurizr tooling in a number of ways:

The easiest way get started is:

Documentation

Since there are a number of ways to use the Structurizr tooling, there are a number of places to find documentation.

Pinned

  1. dsl Public

    Structurizr DSL

    Java 1k 239

  2. java Public

    Structurizr for Java

    Java 887 259

  3. examples Public

    Structurizr examples

    Java 18 30

  4. export Public

    Export models and views to external formats.

    Java 13 20

Repositories

View all repositories

People

This organization has no public members. You must be a member to see who’s a part of this organization.