PlantUML sequence diagram advanced: fragment, step, ref

puml.online
  2026-07-29 15:50 2026-07-29 15:50 Created   2026-08-14 21:34:29 2026-08-14 21:34:29 Updated    

Sequence-diagram grammar is interview-popular but underused in real codebases — most teams have no idea how to make these diagrams genuinely readable to reviewers. Here’s the full set.

Fragment cheat sheet (repeated for emphasis)

1
2
3
4
5
6
7
alt / else / end     — branch
opt / end            — optional block
loop / end           — loop
par / else / end     — parallel
critical / option / end — critical + failure path
break / end          — early exit
note / end note      — annotation

Two or three of these for “order payment flow”:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
@startuml
title Payment flow

User -> Gateway: initiate pay
Gateway -> Risk: evaluate
alt risk OK
  Gateway -> Bank: charge
  critical failure rollback
    Gateway -> Bank: refund
    option refund failed
      Gateway -> Support: human in
    end option
  end critical
  Gateway --> User: 200
else risk rejected
  Gateway --> User: 403
end

@enduml

Real-world: combining class + state + sequence

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
@startuml
actor User
participant "Order Service" as Os
participant "Payment Service" as Ps
participant "Inventory Service" as Is
database  "Order DB" as Odb

== Submit order ==
User -> Os: POST /orders
Os -> Is: lock stock
Is --> Os: ok
Os -> Odb: insert
Odb --> Os: order_id

== Pay ==
Os -> Ps: pay(order_id)
group payment logic
  alt success
    Ps -> Odb: update status=paid
  else fail
    Ps -> Odb: update status=failed
    Os -> Is: unlock
  end
end

== Notify ==
Os --> User: 200 + order_id
@enduml

group / end folds a span in the rendered output — handy for hiding detail.

ref and step

ref — point to another diagram

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
@startuml
title Main login flow
participant FE
participant API
participant Auth

== Signup ==
User -> FE: open signup
FE -> API: POST /signup
API -> Auth: create user
Auth --> API: ok
API --> FE: 200

note right of User: already documented
@enduml

ref over A, B : label references an existing description:

1
2
3
4
5
6
7
8
9
10
11
@startuml

participant FE
participant API

FE -> API: POST /login
note right of FE: ref'd over
ref over FE : login page loaded
FE -> API: submit form

@enduml

step (visible delay)

step 500ms tells PlantUML to render the next arrow after a delay:

1
2
3
4
5
6
7
8
9
@startuml

Client -> Server: request
step 500ms
Server --> Client: 200
step 1000ms
Client -> Server: next request

@enduml

Useful for animated sequence screenshots, but for static blog exports the delay doesn’t show.

skinparam on sequence

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
@startuml

skinparam sequence {
  ArrowColor #2F4858
  ArrowFontColor #1F2328
  LifeLineBorderColor #A31F34
  LifeLineBackgroundColor #FAFAFA
  ParticipantBorderColor #2F4858
  ParticipantBackgroundColor #FAFAFA
  ActorBorderColor #A31F34
  ActorBackgroundColor #FAFAFA
  BoxBorderColor #2F4858
  BoxBackgroundColor #FAFAFA
  FontColor #1F2328
}

actor User
participant Gateway
participant Backend
database DB

User -> Gateway: signup
Gateway -> Backend: create_user
Backend -> DB: INSERT
DB --> Backend: ok
Backend --> Gateway: 200
Gateway --> User: 200

@enduml

Tune to your brand palette.

group / box / partition

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
@startuml
box "Client"
  participant FE
end box
box "Server"
  participant API
end box
box "Data"
  database DB
end box

FE -> API: HTTP
API -> DB: SQL

@enduml

box ... end box groups objects for clarity.

Partitions inside a box

1
2
3
4
5
6
7
8
9
10
11
12
13
@startuml

box over Server #FAFAFA
  partition API layer {
    participant Auth
    participant Domain
  }
  partition Data layer {
    database DB
  }
end box

@enduml

Arrow flavors

Self message (solid + filled arrow)

1
2
3
4
5
6
7
8
9
10
11
@startuml

actor User
participant Browser
participant Backend

User -> Browser: click
Browser -> Browser: validate locally
Browser -> Backend: POST /submit

@enduml

Self-invocation

1
2
3
4
5
6
@startuml

class OrderService

OrderService -> OrderService: handle
@enduml

Async message

1
2
3
4
5
6
7
@startuml

API ->> Queue: publish event
Queue ->> Worker: async consume
Worker -->> API: ACK

@enduml

->> solid arrow = async send.
-->> dashed return.

Discarded message

1
2
3
4
@startuml

API ->x Cache: discard
@enduml

->x means “message dropped.”

Multiplicity

1
2
3
4
5
6
7
8
9
10
11
12
@startuml

"user 1" --> "req 1" : msg
"user 2" --> "req 2" : msg
"user 3" --> "req 3" : msg

note right of "req 1"
  In production thousands per minute
  multi-user concurrent
end note

@enduml

Sequence diagrams have no built-in multiplicity; use naming convention.

Nested alt / par

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
@startuml

FE -> API: submit
alt first submission
  par
    API -> DB: insert
  else
    API -> Cache: clear
  end
else retry
  loop 3 retries
    API -> DB: update
  end
end
@enduml

Alt / par / loop can nest arbitrarily.

Embedding sequence diagrams in docs

1
2
3
4
5
6
7
8
## Login flow

![login](login.puml)

Source (login.puml):
@startuml
...
@enduml

Reviewer sees the rendered SVG; debugger can copy the source and tweak.

Anti-patterns

1. Sequence without messages

1
2
3
4
5
6
User -> Browser
Browser -> Backend
Backend -> Auth
Auth -> DB
DB -> Auth
@enduml

Missing messages and responses makes it look like a flowchart, not a sequence.

2. Sequence with activity-graph behavior

1
2
3
4
if (...) then ...
-> ...
-> ...
@enduml

Loops and branches aren’t sequence territory. Use activity.

3. Sequence too long

5-15 steps and 3-5 lifelines per diagram. Beyond that, split.

4. Sequence without roles

1
2
3
A -> B
B --> C
@enduml

No actor / participant / database / queue loses business context.

Review checklist

  • All lifelines named?
  • Every call has a return?
  • Correct fragment used (alt / par / loop)?
  • No fragment misuse (no activity-graph content in sequence)?
  • ≤ 15 steps total?
  • Colors match theme (avoid black-on-white when blog is dark-mode)?

Sequence best practices

  1. One question per diagram: login, payment, and order each get their own.
  2. Lifelines ≤ 5.
  3. Each message has a clear verb: POST /login beats login.
  4. Critical path with normal arrow; async with ->>.
  5. Color-code failure paths or annotate; reviewers spot error flow first.
  6. Export SVG for PR; SVG beats PNG on clarity.
  • Title: PlantUML sequence diagram advanced: fragment, step, ref
  • Author: puml.online
  • Created at : 2026-07-29 15:50:00
  • Updated at : 2026-08-14 21:34:29
  • Link: https://puml.online/blog/plantuml-ie-macro-en/
  • License: This work is licensed under CC BY-NC-SA 4.0.
On this page
PlantUML sequence diagram advanced: fragment, step, ref
  1. Fragment cheat sheet (repeated for emphasis)
  2. Real-world: combining class + state + sequence
  3. ref and step
    1. ref — point to another diagram
    2. step (visible delay)
    3. skinparam on sequence
  4. group / box / partition
    1. Partitions inside a box
  5. Arrow flavors
    1. Self message (solid + filled arrow)
    2. Self-invocation
    3. Async message
    4. Discarded message
  6. Multiplicity
  7. Nested alt / par
  8. Embedding sequence diagrams in docs
  9. Anti-patterns
    1. 1. Sequence without messages
    2. 2. Sequence with activity-graph behavior
    3. 3. Sequence too long
    4. 4. Sequence without roles
  10. Review checklist
  11. Sequence best practices