PlantUML Sequence Diagrams: A Practical Tutorial

A sequence diagram shows how parts of a system talk to each other over time: who sends which message to whom, in what order. It is the natural way to document an API exchange, an authentication handshake, or any interaction where the order of operations is the point. PlantUML is especially good at these because, unlike most of its diagram types, it lays out sequence diagrams with its own engine rather than delegating to Graphviz, which gives them a clean, predictable appearance.

This tutorial builds a PlantUML sequence diagram step by step, from the two-line minimum to the constructs you need for real interactions - activation bars, loops, alternatives, and notes. Because PlantUML is a text format, you can take any diagram here as a reference and rebuild it as an editable, styleable version in Atlas Diagram Studio at /diagrams, or start from the sequence diagram tool at /diagram-tools/sequence-diagram. The broader PlantUML overview at /guides/plantuml-complete-guide sets the wider context; this guide drills into one type.

Participants and your first messages

Every sequence diagram opens with @startuml and closes with @enduml. Between them, the simplest possible diagram is a single message: a line like Alice -> Bob: Authentication Request draws a solid arrow from Alice to Bob with that label. You do not have to declare Alice and Bob first - PlantUML creates a lifeline the moment it sees a name - but declaring them up front with participant Alice and participant Bob lets you control their left-to-right order and gives you a place to rename or colour them.

You can vary the lifeline's appearance with keywords in place of participant: use actor for a stick figure, database for a cylinder, boundary, control, and entity for the robustness-diagram shapes. Reply messages conventionally use a dashed arrow, so Bob --> Alice: Authentication Response signals a return. You can also alias a long name, writing participant "Payment Gateway" as PG so the rest of the diagram refers to the short PG while the box shows the full label.

Arrows, activation, and lifelines

The arrow syntax carries meaning. A solid line -> is a normal call, a dashed line --> is typically a return, and appending an x as in ->x marks a lost or failed message. You can make the arrowhead thinner with ->> or open, and colour a single arrow inline. Getting into the habit of using solid for calls and dashed for returns makes even a large diagram readable at a glance, because the eye learns the convention.

Activation bars show when a participant is actively processing. Write activate Bob after a message to draw the bar and deactivate Bob when the work finishes; a matched pair brackets the period Bob is busy. A convenient shortcut is to suffix the arrow: Alice -> Bob ++ activates Bob as the message arrives, and -- deactivates on a return. Activation makes nested calls legible - you can see at a glance that Bob is still working while he calls a third participant - which is exactly the clarity a sequence diagram exists to provide.

Loops, alternatives, and grouping

Real interactions have repetition and branching, and PlantUML has combined-fragment keywords for both. Each opens a labelled box and closes with end.

• loop: wrap repeated messages, as in loop for each item ... end, to show iteration.
• alt and else: mutually exclusive branches, like alt valid token ... else expired token ... end.
• opt: an optional block that may or may not run, for a step that only sometimes happens.
• par: parallel execution, showing messages that happen concurrently across participants.
• break: an out-of-the-ordinary exit from the current flow, such as an error abort.
• group: a generic labelled box for any grouping the standard fragments do not cover.
• Nest fragments freely - an alt inside a loop is common - and PlantUML indents the boxes for you.

Notes, dividers, and polishing

Annotations make a diagram self-explanatory. Add a note with note right of Bob: validates the token, or attach one across several lifelines with note over Alice, Bob: shared context. Use == Section Name == to draw a divider that splits the diagram into labelled phases, which is invaluable for a long handshake where readers benefit from seeing "request phase" and "response phase" marked out. A title line and the autonumber keyword - which numbers every message automatically - turn a rough sketch into something documentation-ready.

When a sequence diagram needs to live in a slide deck, a shared document, or a place where non-engineers will annotate it, the PlantUML text is your structural source, and Atlas Diagram Studio at /diagrams is where you rebuild it as an editable, collaborative diagram with clean export. You can also draft from the dedicated sequence diagram tool at /diagram-tools/sequence-diagram or generate a first pass from a description with the AI diagram generator at /diagram-tools/ai-diagram-generator. For the class-diagram counterpart, see /guides/plantuml-class-diagram-tutorial; for how PlantUML compares to Mermaid on sequences, see /guides/mermaid-vs-plantuml.