Structurizr

Sign up Cloud service On-premises installation

The quickest way to create software architecture diagrams

Have you ever spent hours trying to make a software architecture diagram look pretty? It's 2018 and, as software engineers, we shouldn't be using general purpose diagramming tools to create software architecture diagrams! Structurizr is a lightweight, web-based modelling tool that lets you quickly create diagrams based upon the C4 model for software architecture.

System Landscape diagrams

System Context diagrams

Container diagrams

Component diagrams

Dynamic diagrams

Deployment diagrams

Your team's software architecture documentation hub

Visualise

Create software architecture diagrams based upon the C4 model with code via the web API, or by using the browser-based workspace editor.

Document

Create supplementary documentation using Markdown or AsciiDoc, along with architecture decision records (ADRs) to capture your significant design decisions.

Explore

Explore your software architecture model from a number of perspectives, to get insight into the structure of your software.

Share

Share your software architecture diagrams and documentation with your team, using role-based access or a unique sharing link.

Export

Export your software architecture diagrams to PNG or SVG, via the UI or the scripting API. The complete set of diagrams and documentation can also be exported to a static HTML page for offline use.

Integrate

Integrate your software architecture diagrams into websites and wikis, using the iframe embed or the macros built specifically for Atlassian Confluence. Search for content directly from Slack.

Option 1: Use code and the web API

The first option for creating software architecture models is to use the web API in conjunction with the Structurizr for Java and Structurizr for .NET client libraries, both of which are open source. For example, with Java:

public static void main(String[] args) throws Exception {
    Workspace workspace = new Workspace("Getting Started", "This is a model of my software system.");
    Model model = workspace.getModel();

    Person user = model.addPerson("User", "A user of my software system.");
    SoftwareSystem softwareSystem = model.addSoftwareSystem("Software System", "My software system.");
    user.uses(softwareSystem, "Uses");

    ViewSet viewSet = workspace.getViews();
    SystemContextView contextView = viewSet.createSystemContextView(softwareSystem, "SystemContext", "An example of a System Context diagram.");
    contextView.addAllSoftwareSystems();
    contextView.addAllPeople();

    Styles styles = viewSet.getConfiguration().getStyles();
    styles.addElementStyle(Tags.SOFTWARE_SYSTEM).background("#1168bd").color("#ffffff");
    styles.addElementStyle(Tags.PERSON).background("#08427b").color("#ffffff").shape(Shape.Person);

    StructurizrClient structurizrClient = new StructurizrClient("key", "secret");
    structurizrClient.putWorkspace(25441, workspace);
}

Here's the resulting diagram when you open it in Structurizr, where the layout of the diagrams can be modified.

A diagram key is automatically generated for you, based upon the styles and shapes defined in the model.

The code used to create the software architecture model can be thought of as an executable domain specific language, or an executable architecture description language. This offers a number of opportunities over using a static textual description, such as the ability to use the programming language's reflection and static analysis capabilities to find and extract components from the codebase being documented. The web API is open and documented too, providing you the ability to create your own tooling if desired.

Option 2: Use the browser-based workspace editor beta

The second option is to the browser-based workspace editor where you can create diagrams, along with supplementary documentation and decision records.

View and manage the hierarchy of elements that make up the static structure.

View and manage the relationships between elements in the model.

Modify the set of diagrams and their content.

Modify the styles used on your diagrams.

View and manage the set of decision records contained in the workspace.

Edit individual decision records.

Documentation as Markdown or AsciiDoc

Because the code doesn't tell the whole story, Structurizr also provides support for lightweight supplementary technical documentation, based upon a number of popular templates such as arc42.

The documentation is a collection of Markdown or AsciiDoc documents, one per section, which are rendered in the web browser. You can either upload existing Markdown/AsciiDoc files using the client libraries, or edit documentation via the browser-based workspace-editor.

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.

As with the documentation support, you can either upload existing decision records (e.g. those created using adr-tools) via the client libraries, or manage them via the browser-based workspace editor.

Explore your software architecture model

Once you have a model of your software system, extracted from your code using reflection and static analysis techniques, you can additionally visualise the model in a number of different ways. Structurizr provides some explorations to help you explore the elements and their relationships in the model.

Explore the software systems, containers and components defined in the model.

View model elements ranked by size.

Explore the afferent, efferent and cyclic dependencies between components.

Explore the dependencies between components and code.

Far too many teams allow their codebases to grow without having an insight into the structure of the code. The result is often the proverbial "big ball of mud"; a codebase that is tangled, hard to understand, hard to work with and hard to change. Visualising the structure of your code is the first step towards improving it.