PlantUML

Generate UML diagrams (use case, class, sequence, activity, state, component, deployment, object, timing, and more) using PlantUML. Use when the user asks to draw, create, or generate any UML diagram, or mentions PlantUML, UML, use case diagram, class diagram, sequence diagram, activity diagram, state diagram, or any structural/behavioral diagram.

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.

Quick Start

1. Write .puml source file
2. Generate image: 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. Copy to outbound media dir and send via message tool — OpenClaw will handle path resolution automatically

Diagram Types & Syntax

See references/syntax-guide.md for detailed syntax per diagram type.

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

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 when needed.
• 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.

Rendering & Delivery Workflow

1. Write .puml to workspace
2. Run: java -jar ~/tools/plantuml.jar -tpng -charset UTF-8 <file>.puml
3. Verify output exists and has nonzero size
4. Copy PNG to ~/.openclaw/media/outbound/ (create if needed)
5. Send via message tool with media parameter — OpenClaw handles path resolution automatically

Troubleshooting

Problem	Solution
Cannot run program "dot"	Graphviz not installed. Sequence diagrams still work; others need apt install graphviz.
Empty output file (0 bytes)	Likely a syntax error. Run with -v flag to see detailed error output.
Smetana UnsupportedOperationException	Avoid -Playout=smetana; use Graphviz instead.
CJK garbled text	Ensure -charset UTF-8 flag is set and source file is UTF-8.
Image too large/small	Add -DPLANTUML_LIMIT_SIZE=16384 before the jar, or resize in the puml with skinparam dpi.

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