Structurizr Express

Structurizr provides an "Express" feature that allows you to create a single diagram without creating and uploading a workspace via the API. This is useful if you need to quickly sketch up a simple software architecture diagram. To use this feature, simply head to Structurizr Express where you'll find a regular diagram editing page along with a textarea at the top to define a diagram using a simple textual format.

Structurizr Express

Creating the diagram

To create a diagram, you need to use a simple text-based syntax, which is described below. Click the button to update the diagram from the textual definition, and the button to update the definition based upon the current diagram layout.

Hiding or showing the diagram definition

To hide the diagram definition, click the button. To show it again, click the button.

Viewing errors

Any errors with the definition can be seen by clicking the button.

People

Add people to the software architecture model that the diagram is based upon.

Person = Name | Description | Tags | x,y
  • Name: The name of the person/actor/role/persona/etc.
  • Description: A short description.
  • Tags: A comma separated list of tags.
  • x,y: The x,y position in pixels of the element on the diagram canvas.

Examples

A person with a name and description, no tags and no x,y position.

Person = Business User | A regular business user | | 

A person with a name, description and x,y position.

Person = Business User | A regular business user | | 82,164

Software systems

Add software systems to the software architecture model that the diagram is based upon.

SoftwareSystem = Name | Description | Tags | x,y
  • Name: The name of the software system.
  • Description: A short description.
  • Tags: A comma separated list of tags.
  • x,y: The x,y position in pixels of the element on the diagram canvas.

Examples

A software system with a name and description, no tags and no x,y position.

SoftwareSystem = Financial Risk System | Calculates the bank's exposure to risk for product X | | 

A software system with a name, description, tag and x,y position.

SoftwareSystem = Financial Risk System | Calculates the bank's exposure to risk for product X | Some Tag | 1747,1184

Containers

Add containers to the software architecture model that the diagram is based upon.

Container = Software System | Name | Description | Technology | Tags | x,y
  • Software System: The name of the software system that the container belongs to.
  • Name: The name of the container.
  • Description: A short description.
  • Technology: The implementation technology.
  • Tags: A comma separated list of tags.
  • x,y: The x,y position in pixels of the element on the diagram canvas.

Examples

A container within the "Financial Risk System" software system, with a name, description and technology, no tags and no x,y position.

Container = Financial Risk System | Calculation Engine | Calculates the bank's exposure to risk for product X | Java Application | | 

A container within the "Financial Risk System" software system, with a name, description, technology, tag and x,y position.

Container = Financial Risk System | Calculation Engine | Calculates the bank's exposure to risk for product X | Java Application | Some Tag | 1747,1184

Components

Add components to the software architecture model that the diagram is based upon.

Component = Container | Name | Description | Technology | Tags | x,y
  • Container: The name of the container that the component belongs to.
  • Name: The name of the component.
  • Description: A short description.
  • Technology: The implementation technology.
  • Tags: A comma separated list of tags.
  • x,y: The x,y position in pixels of the element on the diagram canvas.

Examples

A component within the "Web Application" container, with a name, description and technology, no tags and no x,y position.

Component = Web Application | Customer Repository | Stores customer data | Spring Data | | 

A component within the "Web Application" container, with a name, description, technology, tag and x,y position.

Component = Web Application | Customer Repository | Stores customer data | Spring Data | Some Tag | 1747,1184

Relationships

Add relationships (between elements) to the software architecture model the diagram is based upon.

Relationship = Source | Description | Technology | Destination | Tags | Vertices
  • 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: The set of x,y coordinates used to bend the line.

Examples

A relationship between the "Business User" and the "Financial Risk System", with a description but no technology, no tags and no vertices.

Relationship = Business User | Views reports via | | Financial Risk System | | 

A relationship between the "Business User" and the "Financial Risk System", with a description, technology, tag and vertices.

Relationship = Business User | Views reports via | HTTPS | Financial Risk System | Some Tag | 100,100 200,200 

Diagram

Specify the diagram type that you'd like to create. There can only be one of these defined. See Views for a description of which elements are permitted within each type of view.

Diagram = Type | Element or Enterprise Name | Description | Paper size
  • Type: The type of the diagram (Enterprise Context, System Context, Container or Component).
  • Element or Enterprise Name: The name of the element or enterprise that is the focus of this diagram.
  • Description: A short description of the diagram.
  • Paper size: The paper size (A5_Portrait, A5_Landscape, A4_Portrait, A4_Landscape, A3_Portrait, A3_Landscape, A2_Portrait, A2_Landscape, Letter_Portrait, Letter_Landscape, Slide_4_3, Slide_16_9).

Examples

A system context diagram for the "Financial Risk System", with a short description and a paper size of "A5_Landscape".

Diagram = System Context | Financial Risk System | A short description of this diagram. | A5_Landscape

Element styles

The styling applied to elements. See Notation for more details.

ElementStyle = Tag | Width | Height | Background | Color | Font size | Shape

Examples

An element style for elements tagged "Element" - a size of 650x400 pixels, a font size of 36 pixels and a Box shape.

ElementStyle = Element | 650 | 400 | | | 36 | Box

An element style for elements tagged "Person" - a background color of "#728da5", a foreground color of "#ffffff" and a "Person" shape.

ElementStyle = Person | | | #728da5 | #ffffff | | Person

Relationship styles

The styling applied to relationships. See Notation for more details.

RelationshipStyle = Tag | Line thickness | Color | Dashed | Routing | Font size | Width | Position
  • Tag: The tag that this style applies to.
  • Line thickness: The line thickness in pixels.
  • Color: The foreground color as an RGB hex value.
  • Dashed: Whether the line is dashed or solid (true or false).
  • Routing: The algorithm used to route lines between elements (Direct or Orthogonal).
  • Font size: The font size in pixels.
  • Width: The width of the description in pixels.
  • Position: The position of the description along the line, as a percentage from start to end (0-100).

Examples

A relationship style for relationships tagged "Relationship" - a line thickness of 5 pixels, a font size of 36 pixels and a description width of 400 pixels.

RelationshipStyle = Relationship | 5 | | | | 36 | 400 |

Example 1: Enterprise Context diagram

Here is a simple example Enterprise Context diagram. The location of the people and software systems (Internal or External) are specified as a tag.

Person = Customer | A customer of Widgets Limited. | External | 67,46
Person = Customer Service Agent | Deals with customer enquiries. | Internal | 1762,46
SoftwareSystem = E-commerce System | Allows customers to buy widgets online via the widgets.com website. | Internal | 914,683
SoftwareSystem = Payment Gateway | Processes credit card payments on behalf of Widgets Limited. | External | 914,1321

Relationship = Customer | Asks questions to | Telephone | Customer Service Agent | | 
Relationship = Customer | Places orders for widgets using | | E-commerce System | | 
Relationship = Customer Service Agent | Looks up order information using | | E-commerce System | | 
Relationship = E-commerce System | Delegates credit card processing to | | Payment Gateway | | 

Diagram = Enterprise Context | Widgets Limited | Sells widgets to customers online. | A5_Landscape

ElementStyle = Element         |  650 |  400 |         | #ffffff |  36 |            
ElementStyle = Software System |      |      | #1168bd |         |     |            
ElementStyle = Person          |      |      | #08427b |         |     |            

RelationshipStyle = Relationship |  5 |         |       | Direct     |  36 |  400 |     

See example in Structurizr Express

Example 2: System Context diagram

Here is a simple example System Context diagram.

Person = User | A user of my software system. | | 277,674
SoftwareSystem = Software System | My software system. | | 1552,674

Relationship = User | Uses | | Software System | |

Diagram = System Context | Software System | A description of this diagram. | A5_Landscape

ElementStyle = Element         |  650 |  400 |         | #ffffff |  36 |
ElementStyle = Software System |      |      | #1168bd |         |     |
ElementStyle = Person          |      |      | #08427b |         |     |

RelationshipStyle = Relationship |  5 |         |       | Direct     |  36 |  400 |

See example in Structurizr Express

Example 3: Container diagram

Here is a simple example Container diagram.

Person = User | A user of my software system. | | 142,64
SoftwareSystem = Software System | My software system. | |
Container = Software System | Single Page Application | Does interesting things. | Web Browser & JavaScript | | 1687,64
Container = Software System | Backend For Frontend | Does interesting things too. | Apache Tomcat & Java | | 1687,674
Container = Software System | Database | Stores interesting data. | MySQL | Database | 1687,1284

Relationship = User | Uses | | Single Page Application | |
Relationship = Single Page Application | Uses | HTTPS | Backend For Frontend | |
Relationship = Backend For Frontend | Reads from and writes to | JDBC | Database | |

Diagram = Container | Software System | A description of this diagram. | A5_Landscape

ElementStyle = Element         |  650 |  400 |         | #ffffff |  36 |
ElementStyle = Person          |      |      | #08427b |         |     |
ElementStyle = Container       |      |      | #438dd5 |         |     |
ElementStyle = Database        |      |      |         |         |     | Cylinder

RelationshipStyle = Relationship |  5 |         |       | Direct     |  32 |  400 |

See example in Structurizr Express

Example 4: Component diagram

Here is a simple example Component diagram.

SoftwareSystem = Software System | My software system. | |
Container = Software System | Single Page Application | Does interesting things. | Web Browser & JavaScript | | 97,64
Container = Software System | Backend For Frontend | Does interesting things too. | Apache Tomcat & Java | |
Container = Software System | Database | Stores interesting data. | MySQL | Database | 97,1184
Component = Backend For Frontend | Some Controller | A description of some controller. | Spring MVC RestController | | 1732,64
Component = Backend For Frontend | Some Service | A description of some service. | Spring Bean | | 1732,624
Component = Backend For Frontend | Some Repository | A description of some repository. | Spring Data | | 1732,1184

Relationship = Single Page Application | Uses | JSON/HTTPS | Some Controller | |
Relationship = Some Controller | Uses | | Some Service | |
Relationship = Some Service | Uses | | Some Repository | |
Relationship = Some Repository | Reads to and writes from | JDBC | Database | |

Diagram = Component | Backend For Frontend | A description of this diagram. | A5_Landscape

ElementStyle = Element         |  650 |  400 |         | #ffffff |  36 |
ElementStyle = Container       |      |      | #438dd5 |         |     |
ElementStyle = Component       |      |      | #85bbf0 | #000000 |     |
ElementStyle = Database        |      |      |         |         |     | Cylinder

RelationshipStyle = Relationship |  5 |         |       | Direct     |  32 |  400 |

See example in Structurizr Express

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.

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. To do this, simply click the button.

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.