PlantUML Diagram Generation

One-Liner

java -jar ~/tools/plantuml.jar -tpng -charset UTF-8 file.puml

Prerequisites

• PlantUML jar: ~/tools/plantuml.jar
• Graphviz: Required for most diagram types. Verify with dot -V.
• Java: Required runtime. Verify with java -version.

If Graphviz is missing, sequence diagrams still render (they use the built-in lambda renderer), but other diagram types will fail.

Security & Trust Notes

This skill is a local diagram-generation helper. It does not require credentials, account access, production data access, or background automation. It only documents how to write PlantUML source and render it with local Java/Graphviz tooling.

Rendering PlantUML executes the local PlantUML Java jar and, for most non-sequence diagrams, local Graphviz. Treat .puml files as source code: review diagrams before rendering when they come from untrusted input, and render inside a controlled workspace.

Most examples use PlantUML's local stdlib. A few optional icon examples in references/stdlib-guide.md show external !include URLs for AWS/Azure/devicons; those may fetch resources from GitHub at render time. For sensitive/offline environments, mirror icon libraries locally or avoid URL-based includes.

Quick Start

1. Write .puml source file (kebab-case filename).
2. Generate image:
   bash java -jar ~/tools/plantuml.jar -tpng -charset UTF-8 <file>.puml
3. PlantUML uses the word after @startuml as the output filename (e.g., @startuml MyDiagram → MyDiagram.png).
4. Attach the resulting PNG/SVG in your reply with a MEDIA:<absolute-path> directive line — OpenClaw delivers it.

Diagram Types & Syntax

• Detailed per-type syntax: references/syntax-guide.md
• Architecture stdlib (C4, Archimate, AWS, Azure): references/stdlib-guide.md
• Shared style include: references/default-style.iuml
• Ready-to-render examples: examples/

Use Case Diagram

@startuml DiagramName
left to right direction
skinparam packageStyle rectangle
skinparam actorStyle awesome

actor User
actor Admin

rectangle "System Name" {
  usecase "Login" as UC1
  usecase "Do Something" as UC2
}

User --> UC1
User --> UC2
UC2 .> UC1 : <<include>>
@enduml

Class Diagram

@startuml DiagramName
skinparam classAttributeIconSize 0

abstract class Shape {
  + draw(): void
}
class Circle {
  - radius: double
}
Shape <|-- Circle

Circle "1" --> "0..*" Point : contains >
@enduml

Sequence Diagram

@startuml DiagramName
actor User
participant ":System" as SYS

User -> SYS : request()
activate SYS
SYS --> User : response()
deactivate SYS

alt success
  SYS --> User : ok
else failure
  SYS --> User : error
end
@enduml

Activity Diagram

@startuml DiagramName
start
:Step 1;
if (Condition?) then (yes)
  :Step 2a;
else (no)
  :Step 2b;
endif
stop
@enduml

State Diagram

@startuml DiagramName
[*] --> Idle
Idle --> Processing : start
Processing --> Done : complete
Processing --> Error : fail
Done --> [*]
Error --> [*]
@enduml

Component Diagram

@startuml DiagramName
component [Web App] as WA
component [API Server] as API
interface "REST API" as REST

WA -right- REST
REST -right- API
@enduml

Deployment Diagram

@startuml DiagramName
node "Web Server" as WS {
  component [Web App] as WA
}
node "DB Server" as DB {
  database [Database] as D
}
WA ..> D : JDBC
@enduml

C4 Architecture (System Context)

@startuml C4Context
!include <C4/C4_Context>

Person(user, "End User", "Uses the system through web/mobile.")
System(sys, "Order System", "Handles ordering, billing, and fulfilment.")
System_Ext(payment, "Payment Gateway", "Third-party PCI processor.")

Rel(user, sys, "Places orders")
Rel(sys, payment, "Processes payments", "HTTPS/JSON")
@enduml

For Container, Component, Dynamic, and Deployment views, see references/stdlib-guide.md.

Themes & Shared Style

PlantUML supports built-in themes (set near the top, after @startuml):

!theme cerulean-outline   ' clean blue/white
!theme materia            ' material design
!theme plain              ' minimal black/white
!theme spacelab           ' light, professional

For consistent styling across diagrams, prefer the shared include:

@startuml MyDiagram
!include /home/guoxh/.openclaw/skills/plantuml/references/default-style.iuml
...
@enduml

The include sets sensible defaults: dpi 150, no shadows, professional fonts, consistent colors. Override per-diagram as needed.

Key Conventions

• File naming: Use kebab-case for .puml filenames (e.g., order-system-class.puml).
• Diagram label: Always name @startuml <PascalCaseName> — this becomes the output filename.
• Charset: Always pass -charset UTF-8 for CJK content.
• Format: Default to -tpng. Use -tsvg for vector output (zoomable, smaller for line art).
• Batch: Pass multiple .puml files in one command for efficiency.
• Output directory: Default is same directory as source. Use -o <dir> to specify a different output directory.
• Style consistency: !include the shared default-style.iuml for professional output.

Rendering & Delivery Workflow

1. Write the .puml file to the workspace.
2. Render:
   bash java -jar ~/tools/plantuml.jar -tpng -charset UTF-8 <file>.puml
   Or use the wrapper:
   bash python3 ~/.openclaw/skills/plantuml/scripts/render.py <file>.puml
3. Verify the output file exists and is non-zero size:
   bash ls -la <DiagramName>.png
4. Attach in your reply by adding a line like:
   MEDIA:/absolute/path/to/DiagramName.png
   The directive must start the line as plain text (no markdown wrappers, not inside code fences). OpenClaw delivers the file via the active channel.

Smoke Test

Verify the toolchain end-to-end after install or update:

cd ~/.openclaw/skills/plantuml/examples
java -jar ~/tools/plantuml.jar -tpng -charset UTF-8 sequence-sample.puml
ls -la SequenceSample.png   # should exist, non-zero

Troubleshooting

Advanced: Output Size Control

# Increase max image size (default 4096)
java -DPLANTUML_LIMIT_SIZE=16384 -jar ~/tools/plantuml.jar -tpng -charset UTF-8 file.puml

Within the diagram:

skinparam dpi 150