Dev Studio Open tools

How to create a UML sequence diagram

By Nexo Design · Published 22 November 2026 · 4 min read

A sequence diagram shows how a group of people or systems talk to each other to get one job done. It answers questions like "who calls whom, in what order, and what comes back?" That makes it one of the most useful diagrams for explaining APIs, login flows and integrations between services.

This guide builds a sequence diagram step by step using PlantUML syntax, which you can paste straight into Dev Studio's Sequence Diagram tool.

How to read a sequence diagram

  • Participants sit along the top, from left to right. Each one is a person, service, database or queue.
  • Lifelines are the dashed vertical lines below each participant. Time flows downwards.
  • Messages are horizontal arrows between lifelines, drawn in the order they happen.
  • Activation bars are thin rectangles on a lifeline that show when a participant is busy handling a request.

Step 1: choose one scenario

A sequence diagram describes a single path through a system, such as "a user resets a forgotten password". Trying to show every possible path at once makes the diagram unreadable. Write the scenario as a sentence first, then list the participants it touches.

Step 2: declare the participants

Declare participants in the order you want them to appear. The keyword controls the shape:

PlantUML · sequenceOpen in Sequence Diagram
@startuml
actor User
participant "Web app" as Web
participant "Auth service" as Auth
database "Users DB" as DB
queue "Email queue" as Mail
@enduml

as creates a short alias, so you can write Web in messages instead of the full display name. Besides participant, actor, database and queue, PlantUML also offers boundary, control, entity and collections.

Step 3: add messages

The arrow style tells the reader what kind of message it is:

SyntaxMeaning
A -> B: textSynchronous call: A waits for B
B --> A: textReply or return value (dashed line)
A ->> B: textAsynchronous message: A doesn't wait (open arrowhead)
A -> A: textA message to itself, such as an internal step
A ->x B: textA message that is lost or fails

Label messages with what is being asked for, like POST /reset or find user by email, rather than vague words like "process".

Step 4: show who is busy

Adding ++ after a message starts an activation bar on the receiver, and -- ends one on the sender. The return keyword sends a dashed reply back to whoever made the last call and closes its activation, which keeps nested calls tidy:

PlantUML · sequenceOpen in Sequence Diagram
@startuml
participant Web
participant Auth
database DB

Web -> Auth ++: login(email, password)
Auth -> DB ++: SELECT user
return user row
Auth -> Auth: verify password hash
return session token
@enduml
Sequence diagram with activation bars: Web calls Auth, Auth queries the database, the database returns a row and Auth returns a token to Web
Activation bars appear while each participant handles a call

Step 5: handle choices and repetition

Real flows have branches. Group messages with these blocks, each closed by end:

  • alt … else … end for either/or paths, such as success and failure.
  • opt for a step that only happens sometimes.
  • loop for repetition, such as retries or polling.
  • par for messages that happen at the same time.

Step 6: add notes, dividers and numbers

  • note right of Auth: Token expires in 15 minutes attaches a note to a participant.
  • == Phase name == draws a divider across the diagram to separate stages.
  • autonumber numbers every message, which helps when you discuss the diagram in a meeting ("look at step 7").

A complete example: password reset

Here is everything together. Open it in the tool and try removing the alt block to see how much information it carries.

PlantUML · sequenceOpen in Sequence Diagram
@startuml
title Password reset
autonumber
actor User
participant "Web app" as Web
participant "Auth service" as Auth
database "Users DB" as DB
queue "Email queue" as Mail

User -> Web: Click "Forgot password"
Web -> Auth ++: POST /password/reset {email}
Auth -> DB ++: find user by email
return user or nothing
alt email is registered
  Auth -> Auth: create one-time token
  Auth ->> Mail: send reset link
  note right of Mail: Delivered by the\nemail worker
else unknown email
  Auth -> Auth: log attempt
end
Auth --> Web --: 202 Accepted
Web --> User: "Check your inbox"
== Later ==
User -> Web: Open reset link
Web -> Auth ++: POST /password {token, new password}
Auth -> DB: update password hash
Auth --> Web --: 204 No Content
@enduml
Password reset sequence diagram with numbered steps: request reset, look up the user, alt block for known and unknown email, email queue, then a second phase where the user opens the link and sets a new password
Password reset flow with numbering, an alt block, a note and a divider

Notice that the response to the user is the same whether or not the email exists. Showing that on the diagram makes a security decision (not revealing which emails are registered) visible to everyone who reads it.

Tips for clearer sequence diagrams

  • Keep it to roughly ten participants or fewer. If you need more, split the flow into two diagrams.
  • Put the initiator on the left. Readers expect the flow to start on the left and move right.
  • Show failures deliberately. An alt block for the important error case is often the most valuable part of the diagram.
  • Prefer real names. Use the actual endpoint, event or table name so the diagram doubles as documentation.
  • Leave out the obvious. Logging, metrics and retries inside a library rarely need arrows of their own.

Common mistakes

  • Forgetting end after an alt or loop. Dev Studio reports "group not closed with end" and points to the last line.
  • Using -- to deactivate a participant that was never activated. It does no harm, but the bar you expected won't appear.
  • Mixing up -> and -->. Readers assume dashed arrows are replies.