https://structurizr.org/

StructurizrStructurizr
Authoring tools Rendering tools Custom tools Usage recommendations

Diagrams as code 2.0

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


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

Structurizr DSL screenshot

An example

This Structurizr DSL example creates two diagrams, based upon a
single set of elements and relationships.

workspace {

    model {
        user = person "User"
        softwareSystem = softwareSystem "Software System" {
            webapp = container "Web Application" {
                user -> this "Uses"
            }
            container "Database" {
                webapp -> this "Reads from and writes to"
            }
        }
    }

    views {
        systemContext softwareSystem {
            include *
            autolayout lr
        }

        container softwareSystem {
            include *
            autolayout lr
        }

        theme default
    }

}

Multiple diagrams from a single model
Multiple diagrams from a single model
[workspace {      mod] [Try this example]
Authoring tools

There are a number of tools for creating a Structurizr compatible
workspace; including text-based DSLs and code-based client libraries.
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.


                     Mentioned on the ThoughtWorks Tech Radar -
                     Techniques - Diagrams as code, the Structurizr
Structurizr DSL      DSL provides a way to author a Structurizr
                     workspace using a straightforward text-based
                     domain specific language.
Arch as code         A command line utility to create software
                     architecture models as YAML.
Structurizr for Java A Java library to create Structurizr workspaces.
Structurizr for      A Clojure wrapper over Structurizr for Java.
Clojure
Structurizr for .NET A C# .NET port of Structurizr for Java.
Structurizr for      A TypeScript port of Structurizr for Java.
TypeScript
Structurizr for PHP  A PHP port of Structurizr for Java.
Structurizr for      A Python port of Structurizr for Java.
Python
Model                A Go port of Structurizr for Java that also
                     includes a diagram editor.

Rendering tools

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


Structurizr cloud service, on-premises installation, and Lite
A web-based rendering tool, with diagrams that are zoomable,
interactive, animatable, and embeddable. It can also publish
Markdown/AsciiDoc documentation and architecture decision records
(ADRs).
Structurizr Structurizr Structurizr
C4Viz
A web-based rendering tool that renders a zoomable set of
C4-PlantUML diagrams.
C4Viz
Ilograph
A web-based modelling tool that provides an interactive way to
navigate a hierarchical model. The Structurizr CLI can be used to
convert a Structurizr DSL/JSON workspace to Ilograph format.
Ilograph
PlantUML
A text-based diagramming tool. The Structurizr CLI can be used to
convert the views defined in a Structurizr DSL/JSON workspace to
PlantUML and C4-PlantUML formats.
PlantUML C4-PlantUML
Mermaid
A text-based diagramming tool. The Structurizr CLI can be used to
convert the views defined in a Structurizr DSL/JSON workspace to
Mermaid format.
Mermaid
DOT (via Graphviz)
A text-based diagramming language, with Graphviz used for rendering.
The Structurizr CLI can be used to convert the views defined in a
Structurizr DSL/JSON workspace to DOT format.
DOT (via Graphviz)
WebSequenceDiagrams
A text-based diagramming tool. The Structurizr CLI can be used to
convert the dynamic views defined in a Structurizr DSL/JSON
workspace to WebSequenceDiagrams format.
WebSequenceDiagrams
structurizr2csv
A tool to convert the views defined in a Structurizr DSL/JSON
workspace to the diagrams.net CSV format.

Custom tools

Workspaces are described using an open JSON data format (OpenAPI 3.0
definition), 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.


Overview


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:

  * A workspace is used to document a single software system, which
    is perhaps owned by a single team.
  * A workspace is used to document a single service, which perhaps
    resides in its own source code repository.


Here are some example scenarios to help you decide how to structure
your software architecture 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

C4 model for visualising software architecture