PlantUML use case diagrams: from requirement to review

Use case diagrams are the most underused UML type. They don’t draw code; they precisely describe what value a system provides and who uses it.

One-line definition

A use case diagram = a set of actors + a set of use cases + their relationships + a system boundary that wraps the cases.

@startuml
left to right direction
skinparam actorStyle awesome

actor "Visitor" as Guest
actor "Member" as Member
Member <<Human>>

rectangle "E-commerce" {
  usecase "Browse items" as UC1
  usecase "Place order" as UC2
  usecase "Pay" as UC3
  usecase "View orders" as UC4
  usecase "Request refund" as UC5
}

Guest --> UC1
Member --> UC1
Member --> UC2
Member --> UC4

UC2 ..> UC3 : <<include>>
UC3 ..> UC5 : <<extend>>
@enduml

Element cheat sheet

Element	Keyword	Render
Actor	`actor`	Stick figure
Use case	`usecase "name"`	Ellipse
System boundary	`rectangle "system" { ... }`	Big rectangle
Actor-to-case link	`-->`	Solid
Case-to-case dependency	`..> : <<include>>` / `<<extend>>`	Dashed

include vs extend — and how to tell them apart

These two relationships are most often mixed up in reviews.

@startuml
actor User
rectangle "Bank system" {
  usecase "Check balance" as Bal
  usecase "Login" as Login
  usecase "Transfer" as Trans
}

User --> Bal
User --> Trans
User --> Login

Trans ..> Bal : <<include>>
Bal ..> Login : <<include>>
@enduml

<<include>>: executing case A must execute case B.

Example: Transfer must check balance — skipping balance is risky.

@startuml
actor User
rectangle "E-commerce" {
  usecase "Place order" as Place
  usecase "Apply coupon" as Coupon
  usecase "Use points" as Points
}

User --> Place
Coupon ..> Place : <<extend>>
Points ..> Place : <<extend>>
@enduml

<<extend>>: executing A may optionally execute B.

Example: placing an order may use a coupon — optional behavior.

Relation	Meaning	Example
`<<include>>`	mandatory	transfer / balance
`<<extend>>`	optional	order / coupon
`-->`	actor-uses-case	user / order

Real example: e-commerce

@startuml
left to right direction
skinparam actorStyle awesome
skinparam rectangle {
  BorderColor #2F4858
  BackgroundColor #FAFAFA
}

actor "Visitor" as Guest
actor "Member" as Member
actor "Admin" as Admin
Member <<Human>>
Admin <<Human>>

rectangle "E-commerce" {
  usecase "Register" as Reg
  usecase "Login" as Login
  usecase "Browse" as Browse
  usecase "Search" as Search
  usecase "Add to cart" as Cart
  usecase "Place order" as Place
  usecase "Pay" as Pay
  usecase "View orders" as Orders
  usecase "Refund" as Refund
  usecase "Manage products" as MgmtProd
  usecase "Reports" as Reports
}

Guest --> Browse
Guest --> Search
Guest --> Reg
Guest --> Login

Member --> Browse
Member --> Cart
Member --> Place
Member --> Pay
Member --> Orders
Member --> Refund
Member --> Login

Admin --> MgmtProd
Admin --> Reports
Admin --> Login

Reg ..> Login : <<include>>
Pay ..> Login : <<include>>
Refund ..> Orders : <<extend>>
Place ..> Cart : <<include>>
@enduml

Multiple system boundaries

When an organization has multiple systems:

@startuml
left to right direction

actor "Customer" as C

rectangle "Front" {
  usecase "Browse" as Front
  usecase "Submit order" as Submit
}

rectangle "Payment" {
  usecase "Charge" as Charge
  usecase "Refund" as RF
}

rectangle "Logistics" {
  usecase "Picking" as StockOut
  usecase "Delivery" as Deliver
}

C --> Front
C --> Submit

Submit ..> Charge : <<include>>
Charge ..> Front : <<include>>
RF ..> Deliver : <<include>>
@enduml

Each rectangle is one system; cross-boundary dependencies use ..>.

Avoiding diagram bloat

5-15 cases per diagram; group the rest:

@startuml
left to right direction

actor User

package "Account" {
  usecase "Register" as Reg
  usecase "Login" as Login
  usecase "Logout" as Logout
}

package "Content" {
  usecase "Read" as View
  usecase "Write" as Write
  usecase "Comment" as Comment
}

package "Settings" {
  usecase "Change password" as Pwd
  usecase "Change email" as Email
  usecase "KYC" as KYC
}

User --> Reg
User --> Login
User --> View
User --> Write
User --> Comment
User --> Pwd
User --> Email
User --> KYC

Logout ..> Login : <<extend>>
@enduml

package groups cases by theme; renders as big rounded rectangles.

Review checklist

All actors named?
Cases use verb phrases (Place order, Pay, Register) not nouns?
System boundary is clear — drawing only one system’s cases?
<<include>> and <<extend>> not misused?
Not too many — 5-15 cases per diagram?

Practical tips

Detail cases with scenarios

Use case diagrams say “what”; pair with activity for “how”:

@startuml
left to right direction
usecase "Place order" as Place

note right of Place
  Scenario:
  1. User adds item to cart
  2. User fills shipping address
  3. User picks payment method
  4. System confirms order
end note

@enduml

note right of is the description slot. One note per complex case.

Staged reviews

Use case diagrams also come in versions:

v1: 3-5 cases, walk through with PM in 5 min
v2: 8-12 cases, dev review
v3: complete, into the doc library

TL;DR

Use case diagrams use verb-phrase ellipses to express what a system does. <<include>> / <<extend>> capture mandatory / optional relationships between cases. Faster than prose specs, sharper than activity diagrams.