About

Structurizr is a web-based rendering tool designed to help software development teams create software architecture diagrams and documentation. It can render diagrams that are interactive, animatable, and embeddable. Structurizr can also publish Markdown/AsciiDoc documentation and architecture decision records (ADRs). Structurizr is available in a number of versions.

Lite

A single workspace version of Structurizr, providing a way to quickly view diagrams, documentation, and architecture decision records.

(open source)

On-premises

A multi-workspace version of Structurizr that can be run on your own infrastructure (local servers or cloud), providing a way to publish diagrams, documentation, and architecture decision records.

(open source)

Cloud service

The Structurizr cloud service, providing a way to publish diagrams, documentation, and architecture decision records.

(free and paid)

CLI

A command line utility designed to be used in conjunction with the Structurizr DSL, supporting pull/push via the web API and exports to a number of formats including PlantUML and Mermaid.

(open source)

Software architecture models as code

Structurizr builds upon "diagrams as code", allowing you to create multiple software architecture diagrams from a single model. There are a number of tools for creating Structurizr compatible workspaces, with the Structurizr DSL being the recommended option for most teams. This Structurizr DSL example creates two diagrams, based upon a single set of elements and relationships.

workspace "Name" "Description"

    !identifiers hierarchical

    model {
        u = person "User"
        ss = softwareSystem "Software System" {
            wa = container "Web Application"
            db = container "Database Schema" {
                tags "Database"
            }
        }

        u -> ss "Uses"
        u -> ss.wa "Uses"
        ss.wa -> ss.db "Reads from and writes to"
    }

    views {
        systemContext ss "Diagram1" {
            include *
            autolayout lr
        }

        container ss "Diagram2" {
            include *
            autolayout lr
        }

        // styling...
    }

}

Workspaces

In Structurizr, a workspace is the wrapper for your software architecture model, views and supplementary documentation. For the purpose of this tour, let's look at two workspaces.

Big Bank plc - System Landscape

This workspace (28201) contains a single system landscape diagram for "Big Bank plc".

system-landscape/workspace.dsl | SystemLandscape.java

Big Bank plc - Internet Banking System

This workspace (36141) contains a number of diagrams, documentation sections, and architecture decision records to describe the Big Bank plc "Internet Banking System".

internet-banking-system/workspace.dsl | InternetBankingSystem.java

Diagrams

Let's start our tour with a look at the core feature of Structurizr, which is the support for creating software architecture diagrams based upon the C4 model. Structurizr allows you to create a number of different diagram types, focused around static structure at different levels of detail, dynamic behaviour and deployment.


System Landscape diagram

System Landscape diagrams

System Context diagram

System Context diagrams

Container diagram

Container diagrams

Component diagram

Component diagrams

Dynamic diagram

Dynamic diagrams

Deployment diagram

Deployment diagrams

Features

While viewing a diagram, you can:

  • Open the diagram key/legend, which is automatically generated for you.
  • Toggle tooltips, to show you additional information about the element or relationship under the mouse pointer.
  • Start presentation mode.
  • Get the HTML code to embed the diagram in web pages, wiki pages, etc.
  • Export the diagram and key/legend to PNG (suitable for printing, inserting into slides, etc).

Diagram key/legend

A diagram key/legend is created automatically, based upon the styles in the workspace.

Navigation

A collection of diagrams can be navigated in a number of ways:

  • Select a diagram from the thumbnails on the left of the page.
  • Press the Up/Down or Left/Right cursor keys to move to the previous/next diagram.
  • Double-click on an element with a + symbol to open the first diagram at the next level of detail (e.g. a container diagram for a software system).
  • Double-click on an element with a # symbol to open the URL associated that element/relationship.
  • Press the Space key to open the quick navigation dialog; use the Up/Down cursor keys to select a diagram, or start typing to find a specific diagram. Press the Enter key to navigate to the selected diagram.

Quick navigation

The quick navigation dialog lets you easily navigate a large collection of diagrams.


This is a live embedded diagram showing the system landscape from the "Big Bank plc - System Landscape" workspace. Double-click the "Internet Banking System" and you'll be taken to the workspace/diagrams for the "Internet Banking System".


And this embed allows you to view all diagrams from the "Big Bank plc - Internet Banking System" workspace. Double-click the "Internet Banking System" and you'll be taken to its container diagram. Alternatively, you can change diagrams using the dropdown list at the top of the embed.

Documentation

Structurizr also provides support for attaching lightweight supplementary documentation to the software architecture model, using Markdown or AsciiDoc. Structurizr diagrams can be embedded, along with additional images (e.g. PNG, JPG and GIF format).


Documentation
Documentation

Navigation

Documentation can be navigated in a number of ways:

  • Select a documentation section from the dropdown list at the top of the page.
  • Press the Left/Right cursor keys to move to the previous/next section.
  • Press the Space key to open the quick navigation dialog; use the Up/Down cursor keys to select a section, or start typing to find a specific section. Press the Enter key to navigate to the selected section.

Quick navigation

The quick navigation dialog lets you easily navigate a large collection of documentation sections.

Architecture decision records

Because diagrams alone can't express the decisions that led to a solution, Structurizr allows you to supplement your software architecture model with a decision log, captured as a collection of lightweight Architecture Decision Records (ADRs) as described by Michael Nygard, and featured on the ThoughtWorks Technology Radar. Structurizr allows you to publish your ADRs to allow team members get an "at a glance" view of the current set of ADRs, along with facilities to make navigating them easier.

Structurizr architecture decision records screenshot

Get a quick "at a glance" view of the decisions.

Structurizr architecture decision records screenshot

And see the full detail of individual decisions.

Navigation works the same way as documentation; using the dropdown list at the top of the page, the Left/Right cursor keys or by opening the quick navigation dialog with the Space key.

Explorations

Structurizr provides some additional visualisations, created automatically, that you can use to explore the software architecture model from a number of different perspectives. If your software architecture diagrams start to become too cluttered, these visualisations are often a good alternative.

Explore
Explore

Other features

Some other important features include role-based access to workspaces, a workspace sharing link for access without being signed in, client-side encryption for increased security, full-text search across all of your workspaces, and the ability to embed your diagrams via an iframe.