PlantUML Sequence Diagram: Syntax and Real-World Examples

A PlantUML sequence diagram turns a time-ordered interaction into reviewable text. Declare the people and systems involved, connect them with messages, and use grouping keywords such as alt, loop, and par to show decisions or repetition. The result is especially useful for documenting authentication, API calls, background jobs, and service-to-service communication.

This tutorial builds two complete diagrams: a login flow and a REST API request. If you are still deciding which diagram fits your problem, start with the broader PlantUML examples guide.

Key Takeaways

A sequence diagram describes behavior over time; participants run left to right and messages run top to bottom.

Explicit participant declarations make names, types, and ordering predictable.

alt, opt, loop, par, and critical express control flow without drawing separate diagrams.

Activation bars show when a participant is performing work, but they do not measure elapsed time.

PlantUML renders the interaction you describe; it does not validate API or security correctness.

Prerequisites

Open the OnUML editor, choose PlantUML mode, and paste each example into the source editor. OnUML renders the preview for you, so no local PlantUML installation is required. Sign in and save the OnUML project when you want to continue editing it later.

The standard source boundary is:

@startuml
' 这里放置图表定义
Alice -> Bob: Hello
@enduml

PlantUML also recognizes participants when they first appear in a message, but explicit declarations are better for maintained documentation because they control labels and display order. The syntax in this guide follows the official sequence diagram documentation, retrieved July 24, 2026.

How Is a PlantUML Sequence Diagram Read?

Read the diagram from top to bottom. Each vertical lifeline represents a participant, and each horizontal arrow represents a message sent later than the messages above it. Horizontal placement is primarily about participants, not time duration: a long arrow does not mean a slow request.

PlantUML supports specialized participant shapes:

@startuml
actor User
boundary WebApp
control AuthService
entity Account
database UserDatabase
queue AuditQueue

User -> WebApp: Submit credentials
WebApp -> AuthService: Authenticate
AuthService -> UserDatabase: Find account
AuthService -> AuditQueue: Record attempt
@enduml

The types communicate roles to readers, but they do not change the underlying system. Use them consistently rather than trying to assign a unique shape to every implementation detail.

Step 1: Declare Participants and Messages

Start with the successful path. A solid arrow such as -> commonly represents a request, while a dashed arrow such as --> is useful for a response. This is a visual convention, not a protocol rule imposed by PlantUML.

@startuml
title Successful login

actor User
participant "Web App" as Web
participant "Auth Service" as Auth
database "User Database" as DB

User -> Web: Enter email and password
Web -> Auth: POST /sessions
Auth -> DB: Find user by email
DB --> Auth: User record
Auth --> Web: Session token
Web --> User: Show dashboard
@enduml

Aliases such as Web keep later messages short while preserving readable labels. Put declarations in the order you want participants displayed. PlantUML can still adjust spacing, but declaration order provides a stable starting point.

Step 2: Show Processing with Activation Bars

Activation bars indicate that a participant is actively handling part of the interaction. Use activate and deactivate when the working interval matters to the explanation.

@startuml
title Login with activation

actor User
participant "Web App" as Web
participant "Auth Service" as Auth
database "User Database" as DB

User -> Web: Submit login form
activate Web
Web -> Auth: Authenticate(credentials)
activate Auth
Auth -> DB: Load account
activate DB
DB --> Auth: Account
deactivate DB
Auth --> Web: Access token
deactivate Auth
Web --> User: Redirect to dashboard
deactivate Web
@enduml

Balance each activation with a deactivation. An unbalanced bar can make the output misleading even when the source renders. The destroy keyword is available when a participant's lifeline actually ends, while return label provides a compact way to draw and label a return message. See the official documentation before mixing shorthand and explicit activation in a large diagram.

Step 3: Add Success and Failure Branches

An authentication flow is incomplete if it only shows success. Use an alt group for mutually exclusive outcomes and else for the alternative branch.

@startuml
title Login success and failure
autonumber

actor User
participant "Web App" as Web
participant "Auth Service" as Auth
database "User Database" as DB

User -> Web: Submit credentials
Web -> Auth: Authenticate(credentials)
Auth -> DB: Find user and password hash
DB --> Auth: Account data

alt Credentials are valid
  Auth -> Auth: Create session token
  Auth --> Web: 201 Created + token
  Web --> User: Show dashboard
else Credentials are invalid
  Auth --> Web: 401 Unauthorized
  Web --> User: Show generic error
end
@enduml

autonumber makes discussions easier because reviewers can refer to message numbers. PlantUML also supports a custom start value, increment, pause, and resume. Avoid encoding sensitive implementation details in a public diagram: the flow should explain responsibilities without exposing secrets or defensive thresholds.

Step 4: Model Optional, Repeated, and Parallel Work

PlantUML provides several grouping constructs for common control-flow needs:

opt shows an optional interaction.
loop shows repetition.
par shows work that may proceed in parallel.
break shows an early exit.
critical marks an interaction that must be treated as a critical region.
group creates a named custom section.

Here is a complete REST API example that combines optional caching with parallel follow-up work:

@startuml
title Product API request
autonumber

actor Client
participant "API Gateway" as Gateway
participant "Product Service" as Product
database Cache
database "Product DB" as DB
queue "Analytics Queue" as Events

Client -> Gateway: GET /products/42
Gateway -> Product: getProduct(42)
activate Product
Product -> Cache: read("product:42")

alt Cache hit
  Cache --> Product: Cached product
else Cache miss
  Cache --> Product: Not found
  Product -> DB: SELECT product 42
  DB --> Product: Product row
  Product -> Cache: write("product:42", product)
end

par Return response
  Product --> Gateway: Product DTO
  Gateway --> Client: 200 OK
else Publish analytics
  Product -> Events: ProductViewed(42)
end
deactivate Product
@enduml

The par block communicates that two paths are independent enough to discuss as parallel behavior. It does not prove that the implementation uses separate threads or that the response can never wait for analytics. Define that meaning in surrounding documentation.

Step 5: Keep Large Diagrams Reviewable

A useful sequence diagram has one clear question. If the title requires “and” several times, split the source into smaller views. Keep participant aliases stable, label messages with business meaning, and use notes only for information that cannot be expressed by the interaction itself.

@startuml
title Resilient inventory reservation

actor Customer
participant Checkout
participant Inventory

Customer -> Checkout: Confirm order
Checkout -> Inventory: Reserve items

loop Up to 3 attempts
  alt Inventory service responds
    Inventory --> Checkout: Reservation result
    break Reservation completed
      Checkout --> Customer: Continue checkout
    end
  else Temporary timeout
    Checkout -> Checkout: Apply retry policy
  end
end

note right of Checkout
  Retry limits belong to the
  application policy, not PlantUML.
end note
@enduml

For a static view of types and relationships, continue with PlantUML class diagram relationships. To connect API behavior to stored entities, use a PlantUML ER diagram.

Common Sequence Diagram Mistakes

Problem	Why it happens	Better approach
Diagram reads like source code	Every function call is included	Show interactions across meaningful boundaries
Dashed and solid arrows are inconsistent	No legend or convention exists	Define request and response styles once
Failure paths are absent	The author starts from a happy-path demo	Add `alt` branches for material outcomes
Activation bars never end	`deactivate` was omitted	Balance activation explicitly
One diagram is extremely tall	Several scenarios were combined	Split scenarios into separate OnUML diagram tabs or summarize secondary work with `ref`
Diagram implies protocol correctness	Rendered output looks authoritative	Review the model separately with domain experts

Complete Authentication Example

The following source is ready to copy. It includes a token refresh path, an authentication failure, and an audit event.

@startuml
title Web authentication flow
autonumber

actor User
boundary Browser
control "Auth API" as Auth
entity "Session Store" as Sessions
database "User DB" as Users
queue "Audit Events" as Audit

User -> Browser: Submit login form
Browser -> Auth: POST /sessions
activate Auth
Auth -> Users: Find account
Users --> Auth: Account and password hash

alt Valid credentials
  Auth -> Sessions: Create session
  Sessions --> Auth: Session ID
  Auth -> Audit: LoginSucceeded
  Auth --> Browser: 201 Created + secure cookie
  Browser --> User: Show account
else Invalid credentials
  Auth -> Audit: LoginFailed
  Auth --> Browser: 401 Unauthorized
  Browser --> User: Show generic error
end
deactivate Auth
@enduml

Frequently Asked Questions

Does PlantUML require participants to be declared first?

No. Participants can be discovered from messages automatically. Explicit declarations are preferable when you need aliases, specialized participant shapes, or controlled ordering.

What is the difference between `alt` and `opt`?

Use alt for two or more mutually exclusive paths and opt for a single conditional interaction that may not occur. Both groups end with end.

Can a sequence diagram prove an API is correct?

No. PlantUML renders the messages and groups in the source; it does not validate authentication security, HTTP semantics, race conditions, or failure handling.

Where can I compare PlantUML with Mermaid for sequence diagrams?

Use the existing Mermaid vs PlantUML sequence diagram comparison when tool choice—not PlantUML syntax—is the main question.

Next Steps

Start with one interaction that your team currently explains in prose. Declare the external actor, the system boundaries, and the successful messages; then add only the failure and concurrency paths that affect the decision under review.

From there, explore the PlantUML examples hub, model persistent structures with PlantUML ERD syntax, or use the official sequence diagram reference for less common syntax such as message delays, dividers, and participant creation. The official Creole formatting reference explains how to format longer participant labels, notes, and message text without changing interaction semantics.

When several diagrams need the same visual conventions, use the official PlantUML theme reference instead of copying unrelated styling directives into every sequence.