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

Write .puml source file (kebab-case filename).

Generate image:

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

PlantUML uses the word after @startuml as the output filename (e.g., @startuml MyDiagram → MyDiagram.png).
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

Write the .puml file to the workspace.

Render:

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

Or use the wrapper:

python3 ~/.openclaw/skills/plantuml/scripts/render.py <file>.puml

Verify the output file exists and is non-zero size:
```
ls -la <DiagramName>.png
```
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

| 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 set skinparam dpi in source. | | C4 stdlib not found | Requires PlantUML ≥ 1.2020.x. Verify with java -jar ~/tools/plantuml.jar -version. | | !include file not found | Use absolute path or path relative to the .puml file. |

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