Structurizr

It's been said that "software is eating the world", yet software development teams waste time and money because they struggle to communicate software architecture. Existing CASE/modelling tools are complex and have become unfashionable after the "agile" movement started in 2001. Teams now tend to favour whiteboards and general purpose tooling instead. The resulting diagrams, however, are typically ad hoc, confusing and disconnected from the code.

Structurizr is a collection of tooling to visualise, document and explore your software architecture.

Visualise your software architecture

Create a software architecture model and diagrams using code, in a way that is connected to the code being described.

Document your software architecture

Embed supplementary documentation into the software architecture model, using developer-friendly Markdown and AsciiDoc.

Explore your software architecture

Better understand and improve the software architecture by exploring the code structures. Keep the model up to date with build tool integration.

Structurizr for Java Structurizr for .NET

Software architecture diagrams as code

Structurizr is an implementation of the System Context, Container and Component diagrams from Simon Brown's C4 model, supplemented with a dynamic diagram that takes its influence from UML. Structurizr does not provide a "drag and drop" editor to create diagrams. Instead, you create a software architecture model using code and upload it via the web API. Here's a simple example using Java:

Workspace workspace = new Workspace("My model", "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, "context", "A simple 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);

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

A simple diagram

In essence, Structurizr is an implementation of an executable architecture description language, a simple domain-specific language to describe static structure, using code. There are open source client libraries on GitHub for Java and the .NET platform, which include static analysis features to help you extract components from your codebase. If you integrate this with your continuous integration/build process, your diagrams stay up to date.

Software documentation as Markdown or AsciiDoc

The code doesn't tell the whole story, so in addition to static and dynamic diagrams, Structurizr also provides support for lightweight supplementary technical documentation based upon the "software guidebook" from Simon Brown's Software Architecture for Developers: Volume 2 book or other templates such as arc42.

Structurizr documentation screenshot

The documentation is a collection of Markdown or AsciiDoc documents, one per section, which are rendered in the web browser. This content is uploaded in a workspace along with the software architecture model, which makes it easy to embed diagrams from that workspace.

Explore your software architecture model

Once you have a model of your software system, extracted from your code using 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.

Tree

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

Blocks

View how responsibilities are partitioned across your software systems, containers and components.

Component size

View components ranked by size.

Component dependencies

Explore the afferent, efferent and cyclic dependencies between components.

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.

Structurizr vs other tools

Structurizr combines the power and richness of a model, with the ease of use we get from text-based tools such as PlantUML and WebSequenceDiagrams.

Structurizr vs other tools

More information

Simon Brown's "Visualise, document and explore your software architecture" talk from the NDC London 2017 conference provides a great introduction to software architecture diagramming and the tooling provided by Structurizr.