Plantuml Sequence Diagram Code Examples and Syntax Guide

Every software team eventually needs to document how systems talk to each other. A user clicks "Buy Now," and between that click and the confirmation email, a dozen services exchange messages. Trying to explain that flow in words alone gets messy fast. That's where PlantUML sequence diagrams come in and knowing the right code examples to copy, adapt, and build on saves hours of guesswork. This article covers real PlantUML sequence diagram code you can use immediately, from basic interactions to advanced patterns.

What Is a PlantUML Sequence Diagram?

A PlantUML sequence diagram is a text-based diagram that shows how objects or actors exchange messages over time. You write simple, plain-text code, and PlantUML renders it into a visual diagram. The "sequence" part means the diagram reads top to bottom, showing the order of interactions between participants.

Unlike drawing tools where you drag and drop boxes and arrows, PlantUML lets you define everything in code. This makes diagrams version-controllable, easy to update, and reproducible. If you've compared different diagramming approaches, you might find our diagram-as-code syntax comparison chart helpful for understanding how PlantUML stacks up against alternatives.

How Do You Write a Basic PlantUML Sequence Diagram?

Every PlantUML sequence diagram starts with @startuml and ends with @enduml. Inside those tags, you define participants and messages between them. Here's the simplest working example:

@startuml
Alice -> Bob: Hello, how are you?
Bob --> Alice: I'm good, thanks!
@enduml

In this code:

Alice and Bob are participants (created automatically on first mention).
The -> arrow means a synchronous (solid) message.
The --> arrow means a return (dashed) message.
Text after the colon is the message label.

That's it. PlantUML handles the layout, boxes, and lifelines on its own.

How Do You Define Participants and Change Their Appearance?

For more control, you can declare participants explicitly at the top. This also lets you set display names and use different shapes:

@startuml
actor "Customer" as C
participant "Web App" as W
participant "Payment Service" as P
database "Order DB" as DB

C -> W: Places order
W -> P: Process payment
P --> W: Payment confirmed
W -> DB: Save order
DB --> W: Order saved
W --> C: Order confirmation
@enduml

Notice the keywords used here:

actor draws a stick figure (for people or external users).
participant draws a standard rectangular box.
database draws a cylinder shape.

You can also use boundary, control, entity, and collections as participant types for UML-compliant styling.

How Do You Show Different Types of Arrows and Messages?

PlantUML supports several arrow styles, and each one carries a different meaning in sequence diagram notation:

@startuml
participant Client
participant Server

Client -> Server: Synchronous request
Client ->> Server: Asynchronous message
Client --> Server: Return/response
Client ->o Server: Lost message (open arrow)
Client o-> Server: Found message
Client <-> Server: Two-way communication
Client -->o Server: Return lost message
@enduml

Here's a quick breakdown:

-> solid line with closed arrow (sync call)
->> solid line with open arrow (async)
--> dashed line with closed arrow (return)
->o message that may be lost
<-> bidirectional

For a broader look at how these syntax patterns compare to other diagramming languages, our Mermaid diagram syntax reference guide covers similar sequence diagram features in Mermaid notation.

How Do You Add Notes, Groups, and Alt/Loop Blocks?

Real-world diagrams need more than just straight arrows. You'll often need to show conditional logic, loops, or add clarifying notes:

@startuml
actor User
participant "Auth Service" as Auth
participant "App Server" as App
database "User DB" as DB

User -> App: Login request
App -> Auth: Validate credentials

alt Credentials valid
 Auth -> DB: Fetch user profile
 DB --> Auth: User data
 Auth --> App: Auth token
 App --> User: Login success
else Credentials invalid
 Auth --> App: Auth failed
 App --> User: Error message
end

== Session Active ==

loop Every 5 minutes
 App -> Auth: Refresh token
 Auth --> App: New token
end

note right of Auth: Tokens expire after 30 min
@enduml

Key constructs to know:

alt/else/end conditional branches (like if/else)
loop/end repeated actions with a condition
opt optional block (runs only if condition is met)
break exits a loop early
== Text == divider with a label (separates phases)
note left of / note right of attached annotations

How Do You Show Activation Bars and Nested Calls?

Activation bars (thin rectangles on lifelines) show when a participant is actively processing. This matters in complex diagrams where you need to show call stacks:

@startuml
participant Controller
participant Service
participant Repository
database DB

Controller -> Service: processOrder()
activate Service

Service -> Repository: findById(123)
activate Repository
Repository -> DB: SELECT FROM orders WHERE id=123
DB --> Repository: Order row
Repository --> Service: Order object
deactivate Repository

Service -> Service: validate(order)

Service -> Repository: save(updatedOrder)
activate Repository
Repository -> DB: UPDATE orders SET status='processed'
DB --> Repository: OK
Repository --> Service: Saved
deactivate Repository

Service --> Controller: OrderResult
deactivate Service
@enduml

Use activate to start a bar and deactivate to end it. You can nest activations to show one method calling another before returning. PlantUML also supports the shorthand ++ and -- syntax:

@startuml
A -> B++ : start
B -> C++ : call
C --> B-- : return
B --> A-- : done
@enduml

How Do You Handle Multiple Scenarios with Ref and Frames?

When a diagram gets long, you can break it into logical frames or reference other diagrams:

@startuml
actor User
participant "Frontend" as FE
participant "Backend" as BE

User -> FE: Submit form
FE -> BE: POST /api/submit

ref over FE, BE: Validation flow (see diagram #2)

BE --> FE: 201 Created
FE --> User: Success message

box "External Services" #LightBlue
 participant "Email Service" as Email
 participant "Analytics" as Analytics
end

BE -> Email: Send confirmation email
BE -> Analytics: Track event
@enduml

The ref over keyword creates a reference frame pointing to another diagram or section. The box keyword groups participants visually, which helps when your diagram involves multiple services or systems.

How Do You Show Timelines, Delays, and Destruction?

Sometimes you need to show that something takes time, or that an object gets destroyed:

@startuml
participant Client
participant Server
participant Cache

Client -> Server: GET /data
Server -> Cache: Check cache

...50ms...

Cache --> Server: Cache miss
Server -> Server: Query database

...200ms...

Server --> Client: Response with data

x Server: Connection pool closed
@enduml

...Text... adds a time gap with an optional label
x Participant shows destruction (end of lifeline)
Blank ... adds an empty delay

How Do You Style PlantUML Sequence Diagrams?

PlantUML supports skin parameters and themes to change the look of your diagrams without altering the logic:

@startuml
skinparam backgroundColor #FEFEFE
skinparam sequenceArrowThickness 2
skinparam sequenceParticipantBorderColor #2C3E50
skinparam sequenceLifeLineBorderColor #7F8C8D
skinparam noteBackgroundColor #FFFDE7
skinparam noteBorderColor #FBC02D

autonumber

User -> API: Request
API -> DB: Query
DB --> API: Result
API --> User: Response
@enduml

The autonumber command adds numbered labels to each message useful for referencing specific steps in documentation or code reviews. You can also use built-in themes:

@startuml
!theme cerulean
actor User
participant App

User -> App: Do something
App --> User: Done
@enduml

Available themes include cerulean, amiga, black-knight, carbon-gray, and more. Check the official PlantUML themes page for a full list.

What Are the Most Common Mistakes in PlantUML Sequence Diagrams?

After working with PlantUML sequence diagrams across many projects, here are the errors that come up most often:

Forgetting @enduml. Without it, PlantUML won't render anything and may throw a cryptic error.
Mismatched alt/end or loop/end blocks. Every alt, loop, opt, and break needs a matching end.
Using the wrong arrow type. -> and --> look similar but mean different things. Solid for calls, dashed for returns.
Not escaping special characters. Colons in message text can confuse the parser. Use \: if your label contains a colon.
Participant name conflicts. If you declare participant "App" as A and later reference App directly, PlantUML creates a second box. Always use the alias.
Overcrowded diagrams. Trying to show 15 services in one sequence diagram makes it unreadable. Split into multiple diagrams or use ref over to reference sub-flows.

Where Can You Render PlantUML Sequence Diagrams?

You have several options for turning your PlantUML code into rendered images:

PlantUML Online Server paste code and get an instant image. Good for quick testing.
VS Code extensions the PlantUML extension gives you live previews as you type.
IntelliJ IDEA / JetBrains IDEs built-in PlantUML plugin with preview support.
Command-line tool requires Java; integrates into build pipelines and CI/CD.
GitHub/GitLab rendering both platforms can render PlantUML blocks in Markdown files with the right plugin or integration.

Quick-Start PlantUML Sequence Diagram Template

Copy this template to get started fast. Replace the placeholder names and messages with your own:

@startuml
!theme plain
autonumber

title Your Diagram Title Here

actor "User" as User
participant "Service A" as A
participant "Service B" as B
database "Database" as DB

User -> A: Action request
activate A

A -> B: Sub-request
activate B
B -> DB: Query
DB --> B: Data
B --> A: Response
deactivate B

A --> User: Final result
deactivate A

note over A, B: Add context about this flow here
@enduml

This covers participants, activation bars, auto-numbering, notes, and a title the skeleton you'll build on for most real diagrams.

Practice Checklist: Your Next Steps with PlantUML Sequence Diagrams

Pick one real flow from your current project a login, API call, or checkout process and write it as a PlantUML sequence diagram using the basic syntax above.
Render it using the PlantUML online server to verify it works before adding it to documentation.
Add conditional logic (alt/else) and loops where your system has branching behavior.
Split large diagrams into multiple linked diagrams using ref frames if you have more than 8–10 participants.
Store your .puml files in version control alongside your code so diagrams stay updated when the system changes.
Compare PlantUML with other diagram-as-code tools using our syntax comparison chart if you want to evaluate options for your team.