Eraser Diagrams

Eraser Diagram Generator

Generates professional architecture diagrams directly from code, infrastructure files, or natural language descriptions using the Eraser API.

When to Use

Activate this skill when:

• User asks to create, generate, or visualize a diagram
• User wants to document architecture from code
• User has Terraform, AWS, Azure, or infrastructure files
• User describes a system and wants it visualized
• User mentions "diagram", "architecture", "visualize", or "draw"

How It Works

1. Analyze the source: Extract architecture information from code, files, or descriptions 2. Generate Eraser DSL: Create Eraser DSL code that describes the diagram 3. Call the Eraser API: Make an HTTP POST request to render the diagram 4. Return the result: Present the image URL and editor link to the user

Diagram Types and Syntax

Eraser supports five types of diagrams, each optimized for different use cases. For detailed DSL syntax and examples, refer to the appropriate reference file:

Flow Charts

Visualize process flows, user flows, and logic flows represented as nodes, groups, and relationships. Diagrams are created using simple syntax.

Use for: Process flows, user journeys, decision trees, business process documentation

diagramType: "flowchart-diagram"

Reference: Flowchart Syntax

Entity Relationship Diagrams (ERD)

Visualize data models represented as entities, attributes, and relationships. Diagrams are created using simple syntax.

Use for: Database schema design, data modeling, understanding entity relationships, documenting data structures

diagramType: "entity-relationship-diagram"

Reference: ERD Syntax

Cloud Architecture Diagrams

Visualize cloud infrastructure represented as nodes, groups, and connections. Diagrams are created using simple syntax.

Use for: Cloud infrastructure visualization, AWS/Azure/GCP architectures, system architecture documentation, data flow visualization

diagramType: "cloud-architecture-diagram"

Reference: Architecture Syntax

Sequence Diagrams

Visualize system flows using sequence diagrams. Each vertical column represents an entity (e.g. user, server, DB) and arrows between the columns represent the flow of information or requests. Diagrams are created using simple syntax.

Use for: API request/response flows, system interactions, user workflows, message passing between services, process flows over time

diagramType: "sequence-diagram"

Reference: Sequence Syntax

BPMN Diagrams (Swimlane Diagrams)

Visualize business processes represented as pools, lanes, and flow objects such as tasks, events, and gateways. Diagrams are created using simple syntax.

Use for: Business process documentation, workflow visualization, process improvement, cross-functional processes, swimlane diagrams showing roles/responsibilities

diagramType: "bpmn-diagram"

Reference: BPMN Syntax

Each reference file contains complete syntax documentation, property references, and practical examples.

API Integration

Endpoint

POST https://app.eraser.io/api/render/elements
Content-Type: application/json
Authorization: Bearer ${ERASER_API_KEY}
X-Skill-Source: eraser-skill

Note: The X-Skill-Source header identifies the AI agent. You MUST replace eraser-skill with your actual agent name:

• If you are Claude (Anthropic), use: claude
• If you are running in Cursor, use: cursor
• If you are ChatGPT (OpenAI), use: chatgpt
• If you are Gemini (Google), use: gemini
• Otherwise, use your model/agent name in lowercase

Response Format

{
  "imageUrl": "https://storage.googleapis.com/eraser-images/...",
  "createEraserFileUrl": "https://app.eraser.io/new?requestId=abc123&state=xyz789",
  "renderedElements": [...]
}

Error Responses

Error Response Format:

{
  "error": {
    "message": "Diagram element has no code",
    "status": 400
  }
}

Troubleshooting Tips:

• Verify DSL syntax is correct before making the API call
• Ensure diagramType matches the DSL content (e.g., sequence DSL with sequence-diagram)
• For auth errors, verify the API key is set correctly as an environment variable

Instructions

When the user requests a diagram:

1. Extract Information

• If code/files are provided, analyze the structure, resources, and relationships
• If description is provided, identify key components and connections
• Determine the appropriate diagram type

2. Generate Eraser DSL

• Create Eraser DSL code that represents the architecture
• CRITICAL: Label Formatting Rules
• Labels MUST be on a single line - NEVER use newlines inside label attributes
• Keep labels simple and readable - prefer separate labels over concatenating too much metadata
• Format DSL with proper line breaks (one node/group per line, but labels stay on single lines)
• For detailed DSL syntax and examples, see the Diagram Types and Syntax section above for links to reference files

3. Create Element Definition

• Create an element object with:
• type: "diagram"
• id: "diagram-1" (or generate a unique ID)
• code: "<your generated DSL code>"
• diagramType: "<appropriate type>"

4. Make the HTTP Request

IMPORTANT: You MUST execute this curl command after generating the DSL. Never stop after generating DSL without making the API call.

CRITICAL: Replace eraser-skill in the X-Skill-Source header with your actual AI agent name (see API Integration section above for values).

   curl -X POST https://app.eraser.io/api/render/elements \
     -H "Content-Type: application/json" \
     -H "X-Skill-Source: eraser-skill" \
     -H "Authorization: Bearer ${ERASER_API_KEY}" \
     -d '{
       "elements": [{
         "type": "diagram",
         "id": "diagram-1",
         "code": "<your generated DSL>",
         "diagramType": "cloud-architecture-diagram"
       }],
       "scale": 2,
       "theme": "${ERASER_THEME:-dark}",
       "background": true
     }'

5. Track Sources During Analysis

As you analyze files and resources to generate the diagram, track:

• Internal files: Record each file path you read and what information was extracted (e.g., infra/main.tf - VPC and subnet definitions)
• External references: Note any documentation, examples, or URLs consulted (e.g., AWS VPC best practices documentation)
• Annotations: For each source, note what it contributed to the diagram

6. Handle the Response

CRITICAL: Minimal Output Format

Your response MUST always include these elements with clear headers:

1. Diagram Preview: Display with a header

      ## Diagram
      ![{Title}]({imageUrl})

Use the ACTUAL imageUrl from the API response.

2. Editor Link: Display with a header

      ## Open in Eraser
      [Edit this diagram in the Eraser editor]({createEraserFileUrl})

Use the ACTUAL URL from the API response.

3. Sources section: Brief list of files/resources analyzed (if applicable)

      ## Sources
      - `path/to/file` - What was extracted

4. Diagram Code section: The Eraser DSL in a code block with eraser language tag

      ## Diagram Code

{DSL code here}

5. Learn More link: You can learn more about Eraser at https://docs.eraser.io/docs/using-ai-agent-integrations

Additional content rules:

• If the user ONLY asked for a diagram, include NOTHING beyond the 5 elements above
• If the user explicitly asked for more (e.g., "explain the architecture", "suggest improvements"), you may include that additional content
• Never add unrequested sections like Overview, Security Considerations, Testing, etc.

The default output should be SHORT. The diagram image speaks for itself.

7. Error Handling

• If API call fails, explain the error
• Suggest checking API key if authentication fails
• Offer to regenerate DSL code as fallback

Best Practices

• Generate Valid DSL: Ensure the DSL syntax is correct before calling the API
• Quote Labels Properly: Always quote labels that contain spaces, special characters, or numbers
• Single-Line Labels: Labels MUST be on a single line - never use newlines inside label attributes
• Format for Readability: Put each node, group, and connection on its own line (but keep labels single-line)
• Include Metadata: If including CIDR blocks, instance types, etc., put them in the same quoted label string: [label: "VPC 10.0.0.0/16"]
• Use Appropriate Diagram Type: Choose the right diagramType for the content
• Group Related Items: Use containers (VPCs, modules) to group related components
• Specify Connections: Show data flows, dependencies, and relationships
• Handle Large Systems: Break down very large systems into focused diagrams
• Include Source Header: Always include X-Skill-Source header with your AI agent name (claude, cursor, chatgpt, etc.)

Notes

• Free tier diagrams include a watermark but are fully functional
• The createEraserFileUrl is always returned (works for both free and paid tiers) and allows users to edit diagrams in the Eraser web editor
• The DSL code can be used to regenerate or modify diagrams
• API responses are cached, so identical requests return quickly

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 icon and color properties.

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 Main Server group.

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

Groups support icon and color properties.

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:

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]

It is possible to set multiple properties by separating them using , like shown below:

Server [icon: server, typeface: mono]

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:

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.

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

Escape string

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

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

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.

Examples

Here are some examples of diagrams you can create.

AWS Diagram

// Define groups and nodes
API gateway [icon: aws-api-gateway]
Lambda [icon: aws-lambda]
S3 [icon: aws-simple-storage-service]
VPC Subnet {
  Main Server {
    Server [icon: aws-ec2]
    Data [icon: aws-rds]
  }
  Queue [icon: aws-auto-scaling]
  Compute Nodes {
    Worker1 [icon: aws-ec2]
    Worker2 [icon: aws-ec2]
    Worker3 [icon: aws-ec2]
  }
}
Analytics [icon: aws-redshift]

// Define connections
API gateway > Lambda > Server > Data
Server > Queue
Queue > Worker1, Worker2, Worker3
S3 < Data
Compute Nodes > Analytics

Google Cloud Diagram

// Define groups and nodes
Stream [icon: kafka, color: grey]
Ingest {
  Pub/Sub [icon: gcp-pubsub]
  Logging [icon: gcp-cloud-logging]
}
Pipelines {
  Dataflow [icon: gcp-dataflow]
}
Storage [icon: gcp-cloud-storage] {
  Datastore [icon: gcp-datastore]
  Bigtable [icon: gcp-bigtable]
}
Analytics {
  BigQuery [icon: gcp-bigquery]
}
Application [icon: gcp-app-engine] {
  App Engine [icon: gcp-app-engine]
  Container Engine [icon: gcp-container-registry]
  Compute Engine [icon: gcp-compute-engine]
}

// Define connections
Stream > Ingest
Logging > Analytics > Application
Pub/Sub > Pipelines > Storage > Application

Azure Diagram

// Define groups and nodes
AD tenant [icon: azure-active-directory]
Load Balancers [icon: azure-load-balancers]
Virtual Network [icon: azure-virtual-networks] {
  Web Tier [icon: azure-network-security-groups] {
    vm1 [icon: azure-virtual-machine]
    vm2 [icon: azure-virtual-machine]
    vm3 [icon: azure-virtual-machine]
  }
  Business Tier [icon: azure-network-security-groups] {
    lb2 [icon: azure-load-balancers]
    vm4 [icon: azure-virtual-machine]
    vm5 [icon: azure-virtual-machine]
    vm6 [icon: azure-virtual-machine]
  }
}

// Define connections
AD tenant > Load Balancers
Load Balancers > vm1, vm2, vm3
vm1, vm2, vm3 > lb2 > vm4, vm5, vm6

Kubernetes Diagram

// Define groups and nodes
Cloud Provider API [icon: settings]
AWS [icon: aws]
GCP [icon: google-cloud]
Azure [icon: azure]
Control Plane [icon: k8s-control-plane]{
  api [icon: k8s-api]
  sched [icon: k8s-sched]
  ccm [icon: k8s-c-c-m]
  cm [icon: k8s-c-m]
  etcd [icon: k8s-etcd]
}
Node1 [icon: k8s-node] {
  kubelet1 [icon: k8s-kubelet]
  kproxy1 [icon: k8s-k-proxy]
}
Node2 [icon: k8s-node] {
  kubelet2 [icon: k8s-kubelet]
  kproxy2 [icon: k8s-k-proxy]
}
Node3 [icon: k8s-node] {
  kubelet3 [icon: k8s-kubelet]
  kproxy3 [icon: k8s-k-proxy]
}

// Define connections
ccm > Cloud Provider API
Cloud Provider API > AWS, Azure, GCP
api > ccm, sched, etcd, cm
kubelet1, kproxy1, kubelet2, kproxy2, kubelet3, kproxy3 > api

Data ETL Pipeline

// Define groups and nodes
Input data sources {
  Oracle [icon: oracle]
  Twitter [icon: twitter]
  Facebook [icon: facebook]
}
ETL pipeline [color: silver]{
  User survey data [icon: kafka]
  Data load [icon: aws-s3]
  Data transformation [icon: databricks]
  Data store [icon: snowflake]
}
Data destinations {
  Notification [icon: slack]
  Experimentation [icon: tensorflow]
  BI dashboard [icon: tableau]
}

// Define connections
Oracle, Twitter, Facebook > User survey data
User survey data > Data load > Data transformation > Data store
Data store > Notification, Experimentation, BI dashboard

BPMN diagram syntax

Flow objects

Flow objects are the most basic building blocks in a BPMN diagram.

Flow object definitions consist of a name followed by a set of properties including the type property which determines whether it is an activity, event, or gateway. If omitted, it defaults to activity.

Place order[type: activity]
Shipped[type: event]
Approved?[type: gateway]

Flow object names are required to be unique.

Flow objects support type, icon, color, and label properties. More on properties below.

Pools and Lanes

A pool is the top-level container which usually maps to organizations or departments. A pool can contain flow objects as well as lanes.

A lane is a sub container inside a pool which usually maps to roles or sub-organizations.

Pool and lane definitions consist of a name followed by { }. The outermost brackets are assumed to be pools and any inner nested brackets are assumed to be lanes. For example, Online store is the name of the pool, which contains a Warehouse lane, which in turn contains the Place order, Shipped, and Approved? flow objects.

Online store {
  Warehouse {
		Place order[type: activity]
		Shipped[type: event]
		Approved?[type: gateway]
	}
}

Pools and lanes support icon, color, and label properties.

Properties

Properties are key-value pairs enclosed in [ ] brackets that can be appended to definitions of flow objects, pools, and lanes. Properties are optional.

Here are the properties that are allowed:

The label property is useful if you want multiple flow objects, pools, or lanes, to have the same label since names are required to be unique. By default, the label is set as the name.

// Names need to be distinct, but labels can overlap
Employee_A [label: employee]
Employee_B [label: employee]

It is possible to set multiple properties by separating them using , like shown below:

Place order [type: activity, icon: flag]

Connections

Connections represent show how work progresses, messages travel, or data links between elements in the process.

Here is an example of a connection between two activities:

Open website > Place order

Here are the types of connectors:

Connection label

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

Open website > Place order: Browse

Connection properties

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

Escape string

Certain characters are not allowed in names because they are reserved. To use these characters, you can wrap the entire flow object, pool, or lane name in quotes " ".

Customer {
	Open website [type: activity]
  "Place / cancel order" [type: activity]
}

Styling

Styles can be applied at the diagram level. Below is an overview of the options and syntax.

Examples

Here are some examples of BPMN diagrams you can create.

Expense Submission and Approval Flow

title Expense Submission and Approval Flow

User [color: lightblue] {
  Login [icon: log-in]
  Access confirmed [type: event, icon: check-circle]
  Start new expense report [icon: file-plus]
  Upload receipts [icon: upload]
  Reimbursed [type: event, icon: dollar-sign]
  User rejected [type: event, label: "Rejected", icon: x-circle]
}

System [color: orange] {
  OCR extract date & amount [icon: calendar]
  Check amount [type: gateway, icon: filter]
  "Auto-approve?" [type: gateway, icon: check]
  "Auto-approved" [type: event, icon: thumbs-up]
  Send to manager [icon: send]
  Process reimbursement [icon: credit-card]
}

Manager [color: green] {
  Review expense [icon: eye]
  Approve? [type: gateway, icon: check]
  Approved [type: event, icon: thumbs-up]
  Rejected [type: event, icon: x-circle]
}

// Connections within User pool
Login > Access confirmed
Access confirmed > Start new expense report
Start new expense report > Upload receipts

// User to System (dashed message flow)
Upload receipts -- OCR extract date & amount : Receipts

// System pool
OCR extract date & amount > Check amount
Check amount > "Auto-approve?" : Amount < $500
Check amount --> Rejected : Amount > $500

// Auto-approve gateway
"Auto-approve?" > "Auto-approved" : Amount < $50
"Auto-approve?" > Send to manager : $51–$500

// Auto-approved to reimbursement
"Auto-approved" > Process reimbursement

// Send to manager to Manager pool (dashed message flow)
Send to manager -- Review expense : Expense for approval

// Manager pool
Review expense > Approve?
Approve? > Approved : Yes
Approve? > Rejected : No

// Approved to System (dashed message flow)
Approved --> Process reimbursement : Approval

// Process reimbursement to User pool (dashed message flow)
Process reimbursement --> Reimbursed : Reimbursement
Upload receipts > Reimbursed

// Rejected to User pool (dashed message flow)
Rejected --> Reimbursed : Notify user
Upload receipts > User rejected

Product Returns Process

title Product Returns Process

Customer [color: teal] {
  Return requested [type: event, icon: mail]
  Ship or drop off item [icon: truck]
  Return complete [type: event, icon: check-circle]
  "Notified: Return not accepted" [type: event, icon: alert-triangle]
}

Company [color: blue] {
  Customer Service {
    Check return eligibility [icon: check-square]
    Eligible? [type: gateway, icon: x]
    Send return instructions [icon: send]
    "Notify: Return not accepted" [icon: x-circle]
  }
  Warehouse {
    Receive & inspect item [icon: package]
    Item OK? [type: gateway, icon: x]
    Offer partial refund or return item [icon: slash]
    Approve return & update stock [icon: database]
  }
  Finance {
    "Issue refund/store credit/replacement" [icon: credit-card]
    "Notify customer: Return complete" [icon: mail]
  }
}

// Connections

Return requested > Check return eligibility
Check return eligibility > Eligible?
Eligible? > Send return instructions : Yes
Eligible? > "Notify: Return not accepted" : No
"Notify: Return not accepted" --> "Notified: Return not accepted"
Return requested > Ship or drop off item
Send return instructions > Ship or drop off item
Ship or drop off item --> Receive & inspect item
Receive & inspect item > Item OK?
Item OK? > Approve return & update stock : Yes
Item OK? > Offer partial refund or return item : No
Offer partial refund or return item --> "Issue refund/store credit/replacement"
Approve return & update stock --> "Issue refund/store credit/replacement"
"Issue refund/store credit/replacement" > "Notify customer: Return complete"
"Notify customer: Return complete" --> Return complete
Ship or drop off item > Return complete
Ship or drop off item > "Notified: Return not accepted"

ERD syntax

Entities

Entities correspond to database tables or similar. Entities contain attributes.

Entity definitions consist of a name followed by { }. For example, users is the name of the below entity and it contains attributes id and displayName.

users {
id string
displayName string
}

It is possible for entities to contain nothing like the below.

users { }

Entity names are required to be unique.

Attributes

Attributes correspond to database table columns or similar.

Attribute definitions occur within an entity definition. They consist of a name, type (optional), and metadata (optional) delimited by the space character. Here is an example:

users {
id string pk
}

Outside of a definition (e.g. in a relationship statement), attributes are referred to following the entity that they belong to, separated by a .. Here is an example:

users.teamId > teams.id

Properties

Properties are key-value pairs enclosed in [ ] brackets that can be appended to entity definitions. Properties are optional.

It is possible to set multiple properties like shown below:

users [icon: user, color: blue] {
 // ...rows
}

Here are the properties that are allowed:

Relationships

Relationships show the attribute-level relations between entities.

Here is an example:

users.teamId > teams.id

It is possible to show omit the attribute-level and simply show entity-level relations like this:

users > teams

The type of connecting line represents the cardinality between the two entities. Here are the types:

If a relationship statement contains a name that has not been previously defined as an entity or attribute, an entity or attribute with that name will be created.

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

Escape string

Certain reserved characters are not allowed in entity or attribute names. However, you can still use these characters by wrapping the entire entity or attribute name in quotes " ".

"CI/CD" [icon: gear] {
    id string pk
}

Styling

Styles can be applied at the diagram level. Below is an overview of the options and syntax.

Examples

Here are some examples of entity relationship diagrams (ERDs) you can create in Eraser:

Chat App

users [icon: user, color: blue] {
    id string pk
    displayName string
    team_role string
    teams string
}

teams [icon: users, color: blue] {
    id string pk
    name string
}

workspaces [icon: home] {
    id string
    createdAt timestamp
    folderId string
    teamId string
}

folders [icon: folder] {
    id string
    name string
}

chat [icon: message-circle, color: green] {
    duration number
    startedAt timestamp
    endedAt timestamp
    workspaceId string
}

invite [icon: mail, color: green] {
    inviteId string
    type string
    workspaceId string
    inviterId string
}

users.teams <> teams.id
workspaces.folderId > folders.id
workspaces.teamId > teams.id
chat.workspaceId > workspaces.id
invite.workspaceId > workspaces.id
invite.inviterId > users.id

Calendar Booking App

User [icon: user] {
  id Int pk
  username String
  email String
  avatar String
  createdDate DateTime
}

Booking [icon: clock] {
  id Int pk
  userId Int
  title String
  startTime DateTime
  endTime DateTime
  location String
  eventTypeId Int
  destinationCalendarId Int
}

EventType [icon: list] {
  id Int pk
  userId Int
  teamId Int
  hidden Boolean
  length Int
}

ApiKey [icon: key]{
  id String pk
  userId Int
  appId String
  hashedKey String
}

App [icon: grid] {
  slug String
  dirName String
  keys Json
  createdAt DateTime
}

Webhook [icon: link] {
  id String pk
  userId Int
  appId String
  active Boolean
}

DestinationCalender [icon: calendar] {
  id Int pk
  userId Int
  integration String
  eventTypeId Int
}

// Booking.eventtType < EventType.id
Webhook.appId > App.slug
Webhook.userId > User.id
// Webhook.eventTypeId > EventType.id
App.slug > ApiKey.appId
User.id < Booking.userId
EventType.userId <> User.id
User.id > ApiKey.userId
DestinationCalender.id > Booking.destinationCalendarId
DestinationCalender.userId < User.id
DestinationCalender.eventTypeId < EventType.id

Form Builder App

User [icon: user] {
  id Int
  firstname String
  lastname String
  email String
  emailVerified DateTime
}

Form [icon: check-square] {
  id String
  ownerId Int
  name String
  formType FormType
  createdAt DateTime
}

Pipeline [icon: filter] {
  id String
  name String
  formId String
  events PipelineEvent
  createdAt DateTime
}

SessionEvent [icon: zap]{
  id String
  submissionSessionId String
  type String
  createdAt DateTime
}

SubmissionSession [icon: clock]{
  id String
  formId String
  createdAt DateTime
}

NoCodeForm [icon: check-square] {
  id String
  published Boolean
  closed Boolean
  formId String
}

User.id < Form.ownerId
Form.id < Pipeline.formId
Form.id < SubmissionSession.formId
Form.id < NoCodeForm.formId
SubmissionSession.id < SessionEvent.submissionSessionId

Flow chart syntax

Nodes

A node is the most basic building block in a flow chart.

Node definitions consist of a name followed by an optional set of properties. For example, Start is the name of below node and it has an shape property which is set to oval.

Start [shape: oval]

Node names are required to be unique.

Nodes support shape, icon, color, and label properties. More on properties below.

Groups

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

Group definitions consist of a name followed by { }. For example, Loop is the name of the below group and it contains Issue1, Issue2, and Issue3 nodes.

Loop {
  Issue1, Issue2, Issue3
}

Nodes (or groups) inside a group can be enumerated either with , or new lines as separators. Below results in the same but uses new lines to separate each node.

Loop {
  Issue1
  Issue2
  Issue3
}

Group names are required to be unique.

Groups can be nested. In the below example, the Outer Loop group contains the Inner Loop group.

Outer Loop {
	Inner Loop {
		Issue1
		Issue2    
	}
	Issue3
}

Groups support icon, color, and label properties.

Properties

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

Here are the properties that are allowed:

Here is the list of shapes:

• rectangle (default), cylinder, diamond, document, ellipse, hexagon, oval, parallelogram, star, trapezoid, triangle

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
Start_A [label: start]
Start_B [label: start]

It is possible to set multiple properties by separating them using , like shown below:

Start [shape: oval, icon: flag]

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:

Issue > Bug

Here are the types of connectors:

Connection label

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

Issue > Bug: Triage

Branching connections

It is possible to create one-to-many connections in a single statement. Here is an example:

Issue > Bug, Feature

Chained connections

It is also possible to "chain" a sequence of connection statements in a single statement

Issue > Bug > Duplicate?

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.

Connection properties

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

Escape string

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

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

Direction

The direction of the flow chart can be changed using the direction statement. Allowed directions are:

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

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

direction right

Styling

Styles can be applied at the diagram level. Below is an overview of the options and syntax.

Examples

Here are some examples of diagrams you can create.

Issue Triage Flow

// Nodes and groups
Issue type? [shape: oval, icon: file-text]

BugPath [color: red] {
  Bug [icon: bug, color: red]
  Duplicate? [shape: diamond, icon: copy]
  Mark duplicate [shape: oval, icon: copy]
  Has repro? [shape: diamond, icon: repeat]
  Ask for repro [shape: oval, icon: repeat]
}

FeaturePath [color: green] {
  Feature [icon: zap, color: green]
  Well specced? [shape: diamond, icon: check-square]
  Can be package? [shape: diamond, icon: package]
  Define as package [shape: oval, icon: package]
}

Issue ready to claim [shape: oval, icon: send]

// Relationships
Issue type? > Bug
Bug > Duplicate?
Duplicate? > Mark duplicate: Yes
Duplicate? > Has repro?: No
Has repro? > Issue ready to claim: Yes
Has repro? > Ask for repro: No
Issue type? > Feature
Feature > Can be package?
Can be package? > Well specced?: No
Can be package? > Define as package: Yes
Well specced? > Issue ready to claim: Yes

Price Lookup Flow

// Define nodes and relationships "A > B"
Start [shape: oval, icon: flag] > Read keywords from Excel [icon: excel]
Read keywords from Excel > Establish Amazon API connection [icon: amazon]
Establish Amazon API connection > Wait for user input [shape: diamond, icon: user]
Wait for user input > Search for keyword on Amazon[icon: search]: User selects keyword
Search for keyword on Amazon > Retrieve item price [icon: dollar-sign] 
Retrieve item price > Output result to Excel [icon: excel] 
Output result to Excel > End
Wait for user input > Close modal [icon: x]: User clicks cancel
Close modal > End [shape: oval, icon: check]

// Define Groups
For each keyword in the list [icon: repeat] {
  Search for keyword on Amazon
  Retrieve item price 
  Output result to Excel
}

Sequence diagram syntax

Each line in a sequence diagram consists of two columns (i.e. entities), an arrow (i.e. direction of flow), and a message. The two columns are separated by the > arrow and the message is prepended with the :.

Here is an example:

Web App > DB: Start transaction

Here are the types of arrows:

Each line is parsed in sequential order from top to bottom and rendered in the diagram the same way.

Column names are required to be unique. If a line refers to a column name that hasn't been used in prior lines, a new column will be created.

Properties

Properties are key-value pairs enclosed in [ ] brackets that can be appended to column names. Properties are optional.

It is possible to set multiple properties like shown below:

Web App [icon: monitor, color: blue] > DB [icon: database, color: green]: Start transaction 

Here are the properties that are allowed on columns:

The label property is useful if you want the column label and name to be distinct. By default, the label is set as the column name. But because column names are required to be distinct, you will need to use the label property if you have two column with the exact same label.

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

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

Blocks

Blocks are groupings of messages that represent control flow. They can be used to express loops, if-else logic, parallel processing, and break execution.

Block definitions consist of a block type followed by { }. It can have an optional label property. For example, the below opt (optional) block has a label if complete. The block contains a single message from Server to Client.

opt [label: if complete] {
 Server > Client: Success
}

There are 5 block types, each representing a type of control flow.

It is possible to create connected blocks in the case of the alt (paired with else) and par (paired with and) blocks.

alt [label: if complete] {
 Server > Client: Success
}
else [label: if failed] {
 Server > Client: Failure
}

Here are all the block properties that are allowed:

Activations

Activations represent the time during which a column (an actor or resource) is actively performing an action.

A pair of activate and deactivate statements define a single activation. The activate and deactivate keyword is followed by the column name.

Client > Server: Data request
activate Server
Server > Client: Return data
deactivate Server

Escape string

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

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

Styling

Styles can be applied at the diagram level. Below is an overview of the options and syntax.

Examples

Here are some examples of sequence diagrams you can create in Eraser:

Web App Transaction Flow

Web App [icon: layout] > DB [icon: database]: Start transaction
Web App > Cloud Fx [icon: function]: Call function
Cloud Fx > API [icon: cloud-cog]: Create session
API > Cloud Fx: Session info
Cloud Fx > DB: Create tx record
Cloud Fx > API: Request access token
API > Cloud Fx: Access token
Cloud Fx > Web App: Token and transaction info
Web App > API: Complete transaction
alt [label: If successful]{
  API > Web App: Transaction confirmation
}
else [label: If failed]{
  API > Web App: Transaction cancellation
}
Web App > DB: Create tx record
Web App > API: Subscribe to transaction changes
activate API 
API > API: Ongoing events
API > Web App: Push events
deactivate API