How to Create Sequence Diagrams from Text

Sequence diagrams are one of the most useful diagram types for developers. They show how components interact over time — API calls, authentication flows, microservice communication, or any request-response pattern.

This tutorial shows you how to create sequence diagrams from plain text using DGMO.

Your First Sequence Diagram

A sequence diagram starts with participants and messages between them. In DGMO, you just write who talks to whom:

Alice -Hello-> Bob
Bob -Hi there!-> Alice

That’s two lines of text, and you get a complete diagram with participant boxes, arrows, and labels.

A Real-World Example: API Login Flow

Here’s a more practical example — a login flow with JWT authentication:

Browser -POST /login-> API
API -SELECT user-> DB
DB -user record-> API
API -200 + JWT-> Browser

Browser -GET /profile-> API
note: Bearer token in header
API -200 user data-> Browser

A few things to notice:

• Labeled arrows — write A -POST /login-> B to label the arrow “POST /login”. The message sits inside the arrow.
• Notes — add note: text between messages to annotate the flow.
• No declarations — participants are created automatically when first referenced.

Adding Notes for Context

Notes are useful for explaining business logic or preconditions that aren’t obvious from the message names:

Client -POST /checkout-> Server
note: Validate cart items
Server -charge card-> PaymentGateway
PaymentGateway -success-> Server
note: Send confirmation email
Server -200 Order confirmed-> Client

Place note: text on its own line between messages. The note appears between the two surrounding messages.

Multi-Service Flows

For complex flows involving multiple services, just keep writing messages. The diagram tracks participants and draws arrows in order:

chart: sequence
title: Microservice Auth

User -request-> Gateway
Gateway -validate token-> Auth
Auth -check session-> Redis
Redis -session data-> Auth
Auth -valid-> Gateway
Gateway -forward request-> Service
Service -query-> DB
DB -result-> Service
Gateway -response-> User

The title: directive adds a heading to the diagram.

Self-Calls

Sometimes a service calls itself — for validation, transformation, or internal processing:

Server -validate input-> Server
Server -query-> DB
DB -result-> Server
Server -transform response-> Server

Write Server -validate input-> Server and the arrow loops back to the same participant.

Tips for Better Sequence Diagrams

1. Name participants by role, not technology — “Gateway” rather than “Express.js Server”
2. Add notes sparingly — only where the flow isn’t self-explanatory
3. Keep diagrams focused — one flow per diagram is easier to read than a mega-diagram

Where to Use Them

Sequence diagrams work great for:

• API documentation — show the request/response flow between client and server
• Architecture Decision Records — illustrate the proposed interaction pattern
• Code reviews — explain complex multi-service flows
• Onboarding docs — help new team members understand system interactions

Try It Yourself

The fastest way to start:

1. Playground — write DGMO and see it render live, right in your browser
2. CLI — render from the terminal with dgmo diagram.dgmo -o output.png
3. Desktop app — full editor with live preview and click-to-source navigation

Sequence diagrams are text. They live in your repo, go through code review, and stay current. That’s the whole point.