Plantuml

PlantUML

Overview

PlantUML is an open-source tool that renders UML diagrams from a plain text description language. Diagrams are defined between @startuml and @enduml tags. PlantUML supports all major UML diagram types plus additional diagrams like network diagrams, Gantt charts, and mind maps. It integrates with IDEs, CI pipelines, and documentation tools, and can generate PNG, SVG, EPS, and ASCII art output.

Sequence Diagram

The most commonly used PlantUML diagram type. Models the time-ordered exchange of messages between participants.

@startuml
title Order Processing Sequence

actor Customer
participant "Web App" as UI
participant "API Server" as API
database "PostgreSQL" as DB
queue "RabbitMQ" as Queue

Customer -> UI: Place Order
activate UI

UI -> API: POST /api/orders
activate API

API -> DB: BEGIN TRANSACTION
API -> DB: INSERT INTO orders
DB --> API: order_id = 42

API -> DB: UPDATE inventory
DB --> API: OK

API -> DB: COMMIT
DB --> API: OK

API -> Queue: Publish OrderCreated event
Queue --> API: ACK

API --> UI: 201 Created {order_id: 42}
deactivate API

UI --> Customer: Order Confirmation
deactivate UI

Queue -> API: Process OrderCreated
activate API
API -> API: Send confirmation email
deactivate API

@enduml

Participant Types

Arrow Types

Grouping and Fragments

@startuml

alt Successful
    A -> B: Request
    B --> A: Response
else Failure
    A -> B: Request
    B --> A: Error
end

loop Every 5 seconds
    A -> B: Heartbeat
    B --> A: ACK
end

par Parallel
    A -> B: Task 1
also
    A -> C: Task 2
end

opt Optional Step
    A -> B: Notify
end

critical Mutex Section
    A -> B: Lock
    B --> A: Acquired
end

@enduml

Class Diagram

@startuml
title Domain Model

abstract class Entity<T> {
    - id: T
    - createdAt: DateTime
    - updatedAt: DateTime
    + getId(): T
}

interface IRepository<T extends Entity> {
    + findById(id: ID): T
    + findAll(): List<T>
    + save(entity: T): T
    + delete(id: ID): void
}

class User extends Entity {
    - email: String
    - name: String
    - passwordHash: String
    + getEmail(): String
    + verifyPassword(raw: String): Boolean
}

class Order extends Entity {
    - status: OrderStatus
    - total: BigDecimal
    + getTotal(): BigDecimal
    + addItem(item: OrderItem): void
    + cancel(): void
}

class OrderItem {
    - quantity: int
    - unitPrice: BigDecimal
    + getSubtotal(): BigDecimal
}

enum OrderStatus {
    PENDING
    CONFIRMED
    SHIPPED
    DELIVERED
    CANCELLED
}

User "1" -- "0..*" Order : places >
Order "1" *-- "1..*" OrderItem : contains
Order --> OrderStatus

IRepository <|.. UserRepository
IRepository <|.. OrderRepository

@enduml

Relationship Syntax

Visibility Modifiers

Activity Diagram

PlantUML supports both legacy and modern (beta) activity diagram syntax. The modern syntax is recommended.

@startuml
title Order Fulfillment Process

start

:Receive Order;

if (Payment Valid?) then (yes)
    :Reserve Inventory;

    fork
        :Pack Items;
    fork again
        :Generate Invoice;
    fork again
        :Send Confirmation Email;
    end fork

    :Ship Order;

    if (Domestic?) then (yes)
        :Standard Shipping;
    else (no)
        :International Shipping;
        :Customs Declaration;
    endif

    :Update Tracking;
    :Mark as Shipped;
else (no)
    :Reject Order;
    :Notify Customer;
    :Refund if Charged;
endif

stop

@enduml

Activity Diagram Elements

Swimlanes

@startuml

|Customer|
start
:Place Order;

|System|
:Validate Order;
:Process Payment;

|Warehouse|
:Pick Items;
:Pack Shipment;

|Shipping|
:Ship Package;
:Update Tracking;

|Customer|
:Receive Package;
stop

@enduml

Component Diagram

@startuml
title System Components

package "Frontend" {
    [Web App] as webapp
    [Mobile App] as mobile
}

package "Backend" {
    [API Gateway] as gateway
    [Auth Service] as auth
    [Order Service] as orders
    [Catalog Service] as catalog
}

package "Data" {
    database "PostgreSQL" as db
    database "Redis" as cache
    queue "RabbitMQ" as queue
}

cloud "External" {
    [Stripe] as stripe
    [SendGrid] as email
}

webapp --> gateway : REST
mobile --> gateway : REST
gateway --> auth : gRPC
gateway --> orders : gRPC
gateway --> catalog : gRPC
catalog --> db
catalog --> cache
orders --> db
orders --> queue
orders --> stripe : HTTPS
queue --> email : AMQP

@enduml

State Diagram

@startuml
title Order State Machine

[*] --> Draft

Draft --> Submitted : submit()
Draft --> Cancelled : cancel()

Submitted --> InReview : [auto]

state InReview {
    [*] --> ValidatingPayment
    ValidatingPayment --> ValidatingInventory : [paymentOK]
    ValidatingPayment --> PaymentFailed : [paymentFailed]
    ValidatingInventory --> [*] : [inventoryOK]
    ValidatingInventory --> OutOfStock : [noStock]
}

InReview --> Approved : [allValid]
InReview --> Rejected : [validationFailed]

Approved --> Shipped : ship()
Shipped --> Delivered : confirmDelivery()
Rejected --> Draft : revise()

Delivered --> [*]
Cancelled --> [*]

note right of InReview
    Automatic validation
    runs within 30 seconds.
end note

@enduml

Use Case Diagram

@startuml
title E-Commerce Use Cases

left to right direction

actor Customer as C
actor Admin as A
actor "Payment System" as PS <<external>>

rectangle "E-Commerce Platform" {
    usecase "Browse Catalog" as UC1
    usecase "Search Products" as UC2
    usecase "Place Order" as UC3
    usecase "Process Payment" as UC4
    usecase "Track Order" as UC5
    usecase "Manage Inventory" as UC6
    usecase "Generate Reports" as UC7
    usecase "Authenticate" as UC8
}

C --> UC1
C --> UC2
C --> UC3
C --> UC5
C --> UC8

A --> UC6
A --> UC7
A --> UC8

UC3 ..> UC4 : <<include>>
UC3 ..> UC8 : <<include>>
UC4 --> PS

@enduml

Object Diagram

@startuml
title Order Instance Snapshot

object "order42 : Order" as o {
    id = 42
    status = CONFIRMED
    total = 149.97
    createdAt = "2025-03-15T10:30:00Z"
}

object "item1 : OrderItem" as i1 {
    productId = 101
    name = "Mechanical Keyboard"
    quantity = 1
    unitPrice = 99.99
}

object "item2 : OrderItem" as i2 {
    productId = 205
    name = "USB-C Cable"
    quantity = 2
    unitPrice = 24.99
}

object "customer7 : User" as u {
    id = 7
    name = "Alice Smith"
    email = "alice@example.com"
}

u --> o : places
o *-- i1 : contains
o *-- i2 : contains

@enduml

Deployment Diagram

@startuml
title Production Deployment

node "CDN (CloudFront)" as cdn {
    artifact "Static Assets" as static
}

node "Kubernetes Cluster" as k8s {
    node "API Pod (x3)" as api_pod {
        artifact "API Service" as api
    }
    node "Worker Pod (x2)" as worker_pod {
        artifact "Background Worker" as worker
    }
}

node "AWS RDS" as rds {
    database "PostgreSQL Primary" as db_primary
    database "PostgreSQL Replica" as db_replica
}

node "AWS ElastiCache" as ec {
    database "Redis Cluster" as redis
}

node "AWS SQS" as sqs {
    queue "Order Queue" as queue
}

cdn --> api : HTTPS
api --> db_primary : SQL (write)
api --> db_replica : SQL (read)
api --> redis : Cache
api --> queue : Enqueue
worker --> queue : Dequeue
worker --> db_primary : SQL

db_primary --> db_replica : Replication

@enduml

Skinparam and Theming

Skinparam

skinparam controls the visual appearance of all diagram elements.

@startuml

skinparam backgroundColor #2E3440
skinparam defaultFontColor #ECEFF4
skinparam defaultFontName "Segoe UI"
skinparam defaultFontSize 12

skinparam class {
    BackgroundColor #4C566A
    BorderColor #D8DEE9
    FontColor #ECEFF4
    ArrowColor #88C0D0
    StereotypeFontColor #81A1C1
}

skinparam note {
    BackgroundColor #3B4252
    BorderColor #4C566A
    FontColor #ECEFF4
}

skinparam package {
    BackgroundColor #3B4252
    BorderColor #4C566A
    FontColor #D8DEE9
}

class User {
    + name: String
    + email: String
}

class Order {
    + total: Decimal
    + status: Status
}

User --> Order

@enduml

Common Skinparam Properties

Built-in Themes

PlantUML includes built-in themes that can be applied with a single directive.

@startuml
!theme cerulean
' Other themes: amiga, blueprint, cerulean, crt-amber, crt-green,
' cyborg, hacker, lightgray, mars, materia, metal, minty, plain,
' reddress, sandstone, silver, sketchy-outline, spacelab, superhero,
' toy, united, vibrant

class Example {
    + field: Type
}

@enduml

Includes and File Organization

!include Directive

@startuml
' Include from a local file
!include common-styles.puml
!include domain/user.puml
!include domain/order.puml

' Include from a URL
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml

User --> Order

@enduml

Defining Reusable Fragments

common-styles.puml:

skinparam class {
    BackgroundColor #4C566A
    BorderColor #D8DEE9
    FontColor #ECEFF4
}

skinparam defaultFontName "Segoe UI"

domain/user.puml:

class User {
    - id: Long
    - email: String
    - name: String
    + getEmail(): String
}

Preprocessing Directives

PlantUML includes a preprocessor with variables, conditionals, loops, and functions.

Variables

@startuml
!$primary_color = "#5E81AC"
!$font_color = "#ECEFF4"
!$bg_color = "#2E3440"

skinparam backgroundColor $bg_color
skinparam class {
    BackgroundColor $primary_color
    FontColor $font_color
}

class Example {
    + field: Type
}

@enduml

Conditionals

@startuml
!$env = "production"

!if ($env == "production")
    skinparam backgroundColor #2E3440
    skinparam defaultFontColor #ECEFF4
!else
    skinparam backgroundColor White
    skinparam defaultFontColor Black
!endif

class Config {
    + env: String
}

@enduml

Procedures (Macros)

@startuml
!procedure $service($name, $tech)
    rectangle "$name\n<size:10>[$tech]</size>" as $name
!endprocedure

!procedure $database($name, $tech)
    database "$name\n<size:10>[$tech]</size>" as $name
!endprocedure

$service(API, "Node.js")
$service(Auth, "Go")
$database(DB, "PostgreSQL")
$database(Cache, "Redis")

API --> Auth
API --> DB
API --> Cache

@enduml

Loops

@startuml
!$i = 0
!while $i < 3
    class "Service_$i" {
        + process(): void
    }
    !$i = $i + 1
!endwhile

Service_0 --> Service_1
Service_1 --> Service_2

@enduml

C4-PlantUML Library

The C4-PlantUML library provides macros for creating C4 model diagrams using PlantUML.

Installation

Include the library from GitHub or a local copy:

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml
' or for container diagrams:
' !include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
' or for component diagrams:
' !include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Component.puml
@enduml

C4 Context Diagram

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

LAYOUT_WITH_LEGEND()

title System Context Diagram

Person(customer, "Customer", "A user who shops online.")
System(ecommerce, "E-Commerce Platform", "Handles catalog, orders, and payments.")
System_Ext(payment, "Payment Provider", "Processes credit card transactions.")
System_Ext(email, "Email Service", "Sends transactional emails.")

Rel(customer, ecommerce, "Browses and purchases", "HTTPS")
Rel(ecommerce, payment, "Processes payments", "HTTPS")
Rel(ecommerce, email, "Sends notifications", "SMTP")

@enduml

C4 Container Diagram

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

LAYOUT_WITH_LEGEND()

title Container Diagram - E-Commerce Platform

Person(customer, "Customer")

System_Boundary(ecommerce, "E-Commerce Platform") {
    Container(webapp, "Web Application", "Next.js", "Serves the storefront UI.")
    Container(api, "API Service", "Node.js / Express", "Handles business logic and API endpoints.")
    Container(worker, "Background Worker", "Node.js", "Processes async tasks.")
    ContainerDb(db, "Database", "PostgreSQL", "Stores users, orders, products.")
    ContainerQueue(queue, "Message Queue", "RabbitMQ", "Async event processing.")
    Container(cache, "Cache", "Redis", "Session and data caching.")
}

System_Ext(payment, "Stripe", "Payment processing.")

Rel(customer, webapp, "Browses", "HTTPS")
Rel(webapp, api, "API calls", "HTTPS/JSON")
Rel(api, db, "Reads/Writes", "SQL")
Rel(api, cache, "Reads/Writes", "Redis Protocol")
Rel(api, queue, "Publishes events", "AMQP")
Rel(worker, queue, "Consumes events", "AMQP")
Rel(worker, db, "Reads/Writes", "SQL")
Rel(api, payment, "Charges", "HTTPS")

@enduml

C4-PlantUML Macros

Running PlantUML

Command Line

# Generate PNG from a .puml file
java -jar plantuml.jar diagram.puml

# Generate SVG
java -jar plantuml.jar -tsvg diagram.puml

# Generate all diagrams in a directory
java -jar plantuml.jar -tsvg -o output/ src/diagrams/

# Generate from stdin
echo "@startuml\nA -> B\n@enduml" | java -jar plantuml.jar -pipe > diagram.png

# Use a config file for shared skinparam settings
java -jar plantuml.jar -config style.puml diagram.puml

Docker

# Run PlantUML server
docker run -d -p 8080:8080 plantuml/plantuml-server:tomcat

# Generate via Docker (no local Java needed)
docker run --rm -v $(pwd):/data plantuml/plantuml -tsvg /data/diagram.puml

IDE Integration

• VS Code: "PlantUML" extension by jebbs — provides syntax highlighting, live preview, and export.
• IntelliJ IDEA: Built-in PlantUML support via the PlantUML Integration plugin.
• Confluence: PlantUML plugin renders diagrams inline.

Best Practices

• Use @startuml / @enduml blocks. Every PlantUML diagram must be wrapped in these tags. The optional name after @startuml becomes the output filename.
• Organize with !include. Split large models into separate .puml files per domain concept and compose them with includes.
• Use skinparam for consistent styling. Define a shared style file and !include it in every diagram for visual consistency.
• Use built-in themes for quick, professional styling. !theme cerulean or !theme blueprint are good defaults.
• Leverage the preprocessor. Use variables for colors, procedures for reusable shapes, and conditionals for environment-specific rendering.
• Use C4-PlantUML for architecture diagrams. The C4-PlantUML library provides well-designed macros that produce clean, standardized C4 diagrams.
• Use aliases for readability. participant "API Server" as API makes source readable while producing clean output.
• Keep sequence diagrams focused. If a sequence diagram has more than 7-8 participants or 20+ messages, split it into multiple diagrams with ref fragments.
• Use left to right direction in use case and component diagrams to improve readability for systems with many elements.
• Generate SVG for documentation. SVG scales better than PNG and is searchable. Use -tsvg in CI pipelines.
• Integrate with CI. Add PlantUML rendering to your CI pipeline so diagrams are always up-to-date. Docker-based rendering avoids Java dependency issues.
• Use the PlantUML server for team environments. A shared server provides consistent rendering and can be used as a rendering service for documentation platforms.