5 Real Ways Teams Use PlantUML

A summary of five ways PlantUML gets used inside real engineering teams, plus the gotchas that bite along the way.

1. Use case diagrams for requirement reviews

Half an hour of whiteboarding in a meeting rarely beats 30 minutes of editing a PlantUML file that can be diffed, reviewed, and merged.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

@startuml
left to right direction
skinparam actorStyle awesome
actor "Guest" 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

Reviewers comment on the diff — should be extend, not include — instead of squinting at blurry whiteboard photos.

2. Component diagrams instead of Visio

Versioned C4-style component diagrams live in the repo and never go stale:

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

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml

Person(user, "User", "Web / Mobile")
Container(web, "Web App", "React/Vue", "UI")
Container(api, "API Service", "Go/Java", "REST")
ContainerDb(db, "Primary DB", "PostgreSQL", "OLTP")
Container(redis, "Cache", "Redis", "Hot keys")

Rel(user, web, "uses")
Rel(web, api, "HTTPS/JSON", "3k rps")
Rel(api, db, "read/write")
Rel(api, redis, "query")
@enduml

Commit the source under docs/architecture/. CI renders to PNG/SVG and attaches them to the README.

3. Sequence diagrams in PR descriptions

For non-trivial interface changes, a short PlantUML in the PR body makes the intent obvious:

1
2
3
4
5
6
7
8
9
10
11

@startuml
title Login flow (legacy)
participant FE
participant API
participant Auth
FE -> API: POST /login
API -> Auth: validate(jwt)
Auth --> API: ok
API -> API: mint new session
API --> FE: 200 + Set-Cookie
@enduml

Reviewers spot the race on step 4 without opening an IDE.

4. Onboarding docs

Day 1 for a new engineer: five PlantUML files > fifty pages of Confluence. One component diagram per module, a handful of sequence diagrams for the critical paths.

5. CI / pipeline diagrams

Render GitHub Actions / Argo / Airflow graphs from PlantUML so pipelines are diffable too:

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

@startuml
(*) --> "lint"
"lint" --> "test"
"test" --> "build"
"build" --> "deploy staging"
"deploy staging" --> "smoke test"
"smoke test" --> if "passed?" then
  -->[yes] "deploy prod"
  --> (*)
else
  -->[no] "alert oncall"
  --> "rollback"
  --> (*)
endif
@enduml

Gotchas

• Use case diagrams with rectangle wrapping usecase break in older PlantUML releases. Keep it flat.
• C4 with !include over the network: clone the stdlib into the repo or vendor it — corporate firewalls will block raw.githubusercontent.com.
• Theme conflicts with dark wikis: default theme is unreadable on dark backgrounds. Switch to !theme cyborg or !theme black-knight.