Architecture diagram syntax

Nodes

A node is the most basic building block in a cloud architecture diagram.

Node definitions consist of a name followed by an optional set of properties. For example, compute is the name of below node and it has an icon property which is set to aws-ec2.

compute [icon: aws-ec2]

Node names are required to be unique.

Nodes support the properties below, such as icon and color.

Groups

A group is a container that can encapsulate nodes and groups.

Group definitions consist of a name followed by { }. For example, Main Server is the name of the below group and it contains Server and Data nodes.

  Main Server {
    Server [icon: aws-ec2]
    Data [icon: aws-rds]
  }

Group names are required to be unique.

Groups can be nested. In the below example, VPC Subnet group contains the Main Server group.

VPC Subnet {
  Main Server {
    Server [icon: aws-ec2]
    Data [icon: aws-rds]
  }
}

Groups support the same properties as nodes.

Properties

Properties are key-value pairs enclosed in [ ] brackets that can be appended to definitions of nodes and groups. Properties are optional.

It is possible to set multiple properties like shown below:

  Main Server [icon: aws-ec2, color: blue] {
    Server [icon: aws-ec2]
    Data [icon: aws-rds]
  }

Here are the properties that are allowed:

Here are the lists of icon names:

• AWS Icons
• Google Cloud Icons
• Azure Icons
• Tech Logos
• General Icons

The label property is useful if you want the node’s (or group’s) label and name to be distinct. By default, the label is set as the node name. But because node names are required to be distinct, you will need to use the label property if you have two nodes with the exact same label.

// Names need to be distinct, but labels can overlap
Server_A [label: server]
Server_B [label: server]

Refer to Styling for more details and examples on the colorMode, styleMode, typeface, and textSize properties.

Connections

Connections represent relationships between nodes and groups. They can be created between nodes, between groups, and between nodes and groups.

Here is an example of a connection between two nodes:

Compute > Storage

Here are the types of connectors:

Connector	Syntax	Description
	>	Left-to-right arrow
	<	Right-to-left arrow
	<>	Bi-directional arrow
	-	Line
	--	Dashed line
	-->	Dashed arrow

<-- and <--> are the dashed versions of < and <>.

The connector type sets the arrowheads and dashes, while the connectorStyle property sets the line’s path: elbow (default), straight or arc.

It is possible to add a label to a connection. Here is an example:

Storage > Server: Cache Hit

It is possible to create one-to-many connections in a single statement. This is instead of creating separate one-to-one connections. Here is an example:

Server > Worker1, Worker2, Worker3

If a connection statement contains a name that has not been previously defined as a node or a group, a blank node with that name will be created.

Define a node, with its properties and inside its group, before the first connection that uses it. Defining it after that shows a duplicate-name error, and the node stays outside its group.

Here are the properties that are allowed on connections (lines):

Connection properties go after the :. Without it, Storage > Server [color: green] colors the Server node instead of the line.

Icons

Here’s a list of all the icons you can use with diagram-as-code.

Escape string

Certain characters are not allowed in node and group names because they are reserved. However, you can still use these characters by wrapping the entire node or group name in quotes " ".

User > "https://localhost:8080": GET

A name whose first word is a diagram keyword is read as that keyword instead: title, direction, legend, colorMode, styleMode, typeface, textSize, layout, wrap and connectorStyle, in any case. Wrap such names in quotes too:

"Layout Service" > Database

Comments

Text after // is a comment and is ignored.

// This line is a comment

Title

A title line sets the diagram’s title, the same one you can edit from the property bar.

title Checkout service

Direction

The direction of the cloud architecture diagram can be changed using the direction statement. Allowed directions are:

• direction down
• direction up
• direction right (default)
• direction left

The direction statement can be placed anywhere in the code like this:

direction down

Styling

Styles can be applied at the diagram level. Below is an overview of the options and syntax. Refer to Styling for more details and examples.

With wrap off, labels break only at \n instead of wrapping. It applies to everything defined after it; for a single node, group or connection, use the wrap property.

wrap off
web-01 [icon: aws-ec2, label: "web-01\n10.0.12.34"]

With connectorStyle straight or connectorStyle arc, connections defined after it are drawn as straight or curved lines instead of elbows; for a single connection, use the connectorStyle property. A node connected to itself, a node connected to a group it sits in, and several connections between the same two nodes are always drawn as elbows.

Legends

Legends map a swatch (connection, icon, shape, or color) to a label. Swatches are not tied to actual elements in the diagram.

 legend {                                        
    [connection: -->, label: Async]            
    [color: red, label: Error]
    [icon: aws-lambda, label: Lambda]
    [shape: diamond, label: Decision]
  }

Legend properties

  legend [position: bottom-left] {  
    [color: red, label: Error]  
  }

Here is the list of positions:

top-left, top-right (default), bottom-left, bottom-right, top, bottom, left, right

Legend item properties

Each legend item is enclosed in [ ] and must include a label and at least one swatch property.

color can be combined with connection or shape. Other swatch types are mutually exclusive.

legend {  
    [connection: -->, color: orange, label: Async backup]  
    [shape: rectangle, color: blue, label: Active]  
}