Usage recommendations

Here are some of our recommendations for using Structurizr ... tl;dr:

  • A Structurizr workspace should contain the model, views and documentation for a single software system.
  • Use code or text to create your software architecture model.

Workspaces

In general, we recommend that a Structurizr workspace contains the model, views and documentation for a single software system. In many cases, a software system is "owned by" a single software development team. Here are a few example scenarios.

Example 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, our recommendation is to document this in a single workspace.

  • Number of workspaces: 1

Example 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, our recommendation is to document this in a single workspace.

  • Number of workspaces: 1

Example 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. Our recommendation is to document this in a single workspace, so that all of the documentation for the software system resides together.

  • Number of workspaces: 1

Example 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. Our recommendation is to document each software system in a separate workspace.

  • Number of workspaces: N

Example 5: microservices development, multiple teams

An organisation is building a software system comprised of N microservices (plus their corresponding data stores, if applicable). Each microservice is owned by a separate software development team. Due to the team boundaries, our recommendation is to treat each microservice as a separate software system, and to therefore document 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

Diagrams as code/text vs browser-based workspace editor UI

We recommend using the browser-based workspace editor UI in the following scenarios only:

  • For workspaces where you are only modelling people, software systems, and containers.
  • Non-programmers.

For all other usage, our recommendation is to use code or text. Please note that once you've decided to use the browser-based workspace editor, it's not possible to switch to a code/text approach - there is no tooling that will "decompile" a workspace JSON file back to Java code, C# code, the Structurizr DSL, etc.

Workflow

Here are some suggested steps for incorporating Structurizr into your workflow. Regardless of which authoring method you use, your workspace is stored on the cloud service/on-premises installation as a JSON file (OpenAPI schema). This JSON file can be exported in a number of ways - see Help - Workspace export and import for more details.

Browser-based editor

The browser-based workspace editor is essentially a UI for editing the JSON file, and no other tooling is required. You can export your workspace as a JSON file for addition to your version control system. We recommend regularly exporting your JSON file for backup purposes.

Code or text

The client libraries and Structurizr CLI take the input format used for authoring your workspace (e.g. Java code, C# code, DSL, etc) and convert that to a workspace JSON file. The client libraries and Structurizr CLI then push this JSON file to the cloud service/on-premises installation, where it is stored.

When using code or text, you should treat the uploaded workspace as immutable (with the exception of modifying diagram layout; see below). Any changes that you want to make to your workspace should be made by changing the workspace source (i.e. the code or text) - again, there is no tooling that will "decompile" a workspace JSON file back to Java code, C# code, the Structurizr DSL, etc.

The only exception to this immutability rule is diagram layout, assuming you're not using automatic layout. When you open the diagram editor, you'll be able to move elements around the diagram canvas. These layout changes are stored inside the workspace JSON file. Before you push a new version of your workspace, the client libraries and Structurizr CLI will pull a copy of your existing workspace JSON down to your computer, and attempt to extract the diagram layout information for inclusion in the new version of your workspace. The algorithm for doing this varies between client library implementations. For this reason, you may want to version control both your input code/text (this creates your workspace), and an export of the workspace JSON file (this contains your diagram layout information).