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

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