Structurizr Express

Structurizr provides an "Express" feature that allows you to create a single diagram as JSON or YAML. This is useful if you need to quickly create a simple software architecture diagram or two. To use this feature, head to Structurizr Express where you'll find a diagram editor along with some controls on the left to define the diagram.

See Diagramming vs modelling for a comparison of Structurizr Express vs Structurizr (the full version).

Structurizr Express


Converting an Express diagram into a full workspace

If you're signed in, and you have a workspace available, you can use the button to convert the Express definition to a full workspace. After conversion, the browser-based workspace editor will open so that you can continue to modify the new workspace.

type

The following diagram types are supported in Structurizr Express:

  • System Landscape
  • System Context
  • Container
  • Component
  • Dynamic

scope

The scope property defines the scope of the diagram, and varies depending on the diagram type.

  • System Landscape: The name of the enterprise being described.
  • System Context: The name of a software system defined in the elements array (see below).
  • Container: The name of a software system defined in the elements array (see below).
  • Component: The name of a container defined in the elements array (see below).
  • Dynamic: The name of a software system or container defined in the elements array (see below), or an empty string.

elements

This is an array of the top-level elements (people and software systems) defined in the diagram.

People

The following properties can be specified:

  • type: Must be Person.
  • name: The name of the person/actor/role/persona/etc.
  • description: A short description.
  • tags: A comma separated list of tags.
  • position: The x,y position in pixels of the element on the diagram canvas.

Software Systems

The following properties can be defined specified:

  • type: Must be Software System.
  • name: The name of the software system.
  • description: A short description.
  • tags: A comma separated list of tags.
  • position: The x,y position in pixels of the element on the diagram canvas.
  • containers: An array of containers (see below).

Containers

Containers are defined inside the containers property of the parent software system, and the following properties can be specified:

  • type: Must be Container.
  • name: The name of the container.
  • description: A short description.
  • technology: The technology of the container.
  • tags: A comma separated list of tags.
  • position: The x,y position in pixels of the element on the diagram canvas.
  • components: An array of components (see below).

Components

Components are defined inside the components property of the parent container, and the following properties can be specified:

  • type: Must be Component.
  • name: The name of the component.
  • description: A short description.
  • technology: The technology of the component.
  • tags: A comma separated list of tags.
  • position: The x,y position in pixels of the element on the diagram canvas.

relationships

This is an array of the relationships between elements. The following properties can be specified:

  • source: The name of the source element.
  • description: A short description.
  • technology: The technology used to implement the relationship.
  • destination: The name of the destination element.
  • tags: A comma separated list of tags.
  • vertices: An array of x,y coordinates used to bend the line. (optional)
  • order: The order of the interaction. (dynamic diagrams only)

styles

This is an array of the styles that are applied to elements and relationships, based upon the tags that they have.

Element styles

The following properties can be specified for element styles:

  • type: Must be element.
  • tag: The tag that this style applies to.
  • width: The width in pixels.
  • height: The height in pixels.
  • background: The background color as an RGB hex value (e.g. #ffffff).
  • color: The foreground color as an RGB hex value (e.g. #000000).
  • fontSize: The font size in pixels.
  • border: Solid or Dashed.
  • opacity: The opacity of the rendered element as a percentage (an integer between 0 and 100, inclusive).
  • shape: The shape to use (Box, RoundedBox, Circle, Ellipse, Hexagon, Person, Folder, Cylinder, Pipe).

Relationship styles

The following properties can be specified for relationship styles:

  • type: Must be relationship.
  • tag: The tag that this style applies to.
  • position: The position of the description along the line as a percentage from start to end (an integer between 0 and 100, inclusive).
  • thickness: The line thickness in pixels.
  • width: The width of the description in pixels.
  • color: The foreground color as an RGB hex value (e.g. #000000).
  • fontSize: The font size in pixels.
  • dashed: Whether the line is dashed or solid (true or false).
  • routing: The algorithm used to route lines between elements (Direct or Orthogonal).
  • opacity: The opacity of the rendered element (an integer between 0 and 100, inclusive).

Using external diagram definitions

To use an external diagram definition (e.g. a GitHub gist or a text file accessible from your web browser), simply add a src parameter to the query string. Here is an example using a diagram definition from a GitHub gist.

The content is loaded from your web browser, so you can use URLs that are only accessible inside your internal network as the source of diagram definitions.

You can also use an external diagram definition when embedding Express diagrams. Simply remove the inliine diagram definition from the embed code and replace it with a src parameter instead.

Saving a diagram definition to local storage

The current diagram definition can be saved to your web browser's local storage, which is useful if you need to close your browser and come back to the diagram definition later on. Once saved in local storage, you can access the diagram definition by clicking the name of your diagram in the "Express" menu.

Structurizr Express local storage

Additional notes

Please note that all elements on a diagram must be uniquely named.

Scripting

Structurizr Express can be scripted in conjunction with tools such as Puppeteer (headless Chrome/Chromium), to automate the generation and export of diagrams from the command line, perhaps as a part of a build process. The structurizr-puppeteer repo on GitHub has some code samples of how to do this.

Frequently asked questions

Why can't I generate multiple diagrams from a single Structurizr Express definition?

Structurizr Express is only designed to create a single diagram at a time, showing all elements and relationships included in the textual (JSON/YAML) definition. While it's certainly possible to generate multiple diagrams from a single definition (e.g. a Container diagram and the corresponding "zoomed-out" System Context diagram), Structurizr Express would need to make some assumptions as to what should be shown on both diagrams. While this is okay in trivial situations, it breaks down very quickly when you start needing to show different sets of elements or relationships on different diagrams.

The textual (JSON/YAML) definition mixes content (the model) and presentation (the view), which was a conscious decision to allow single diagrams to be created quickly. The full version of Structurizr does not have this limitation, allowing you to create a single model, and multiple views onto that model. In summary, Structurizr Express is a diagramming tool, whereas the full version of Structurizr is a modelling tool.

I have a complicated diagram that I'd like to convert to the full version of Structurizr. Is this possible?

If you're signed in, and you have a workspace available, you can use the button to convert the Express definition to a full workspace. After conversion, the browser-based workspace editor will open so that you can continue to modify the new workspace.