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.

When using code or text, you should treat the uploaded workspace as immutable (with the exception of modifying diagram layout). Any changes that you want to make to your workspace should be made by changing the workspace source code/text. Please also note that once you've decided to use the browser-based workspace editor, it's not possible to switch to a code/text approach.