PlantUML Diagram Generation and Conversion

Table of Contents

• Purpose
• When to Use This Skill
• Prerequisites
• Creating Diagrams
  • Diagram Type Identification
  • Resilient Workflow
• Converting Source Code to Diagrams
• Converting Diagrams to Images
  • Standalone .puml Files
  • Markdown Processing
  • Direct Command-Line Usage
• Best Practices
• Troubleshooting
• References

Purpose

This skill enables comprehensive PlantUML diagram creation and conversion workflows. PlantUML is a text-based diagramming tool that generates professional diagrams from simple, intuitive syntax.

Core capabilities:

1. Create diagrams from natural language descriptions
2. Convert source code to architecture diagrams (Spring Boot, FastAPI, Python ETL, Node.js, React)
3. Convert standalone .puml files to PNG or SVG images
4. Extract puml code blocks from markdown and convert to images
5. Process linked .puml files in markdown (![diagram](path/to/diagram.puml))
6. Validate PlantUML syntax without conversion
7. Replace markdown diagrams with image links for publication (Confluence, Notion)

When to Use This Skill

Default for WikiTicket, GitHub wiki, architecture docs, walkthroughs, and requirements is design-doc-mermaid. GitHub renders fenced mermaid (flowchart, sequence, class, ER, state, C4). This skill is opt-in.

Activate for:

• Salt wireframes / UI mocks
• UML use case, timing, ArchiMate
• nwdiag networks, WBS, JSON/YAML trees
• .puml file to PNG or SVG conversion (always required; GitHub wiki does not render PlantUML source)
• Markdown files containing PlantUML fences or linked .puml files
• Confluence or Notion image export (render first, then upload)
• PlantUML syntax validation
• A user who already has .puml source and wants an image

Do not take class, ER, state, sequence, or C4 from WikiTicket design docs unless Mermaid cannot do the job or the user names PlantUML.

GitHub wiki: never leave a raw PlantUML fence as the only view. Render PNG or SVG, commit under docs/diagrams/, link the image, upload it with the wiki page.

Confluence/Notion: render PlantUML (and Mermaid, via design-doc-mermaid) to PNG or SVG and upload both. See references/wiki-ticket-integration.md.

Prerequisites

Before creating diagrams, verify the PlantUML setup:

python scripts/check_setup.py

Required components:

Component	Purpose	Installation
Java JRE/JDK 8+	Runtime	https://www.oracle.com/java/technologies/downloads/
plantuml.jar	Diagram generator	https://plantuml.com/download (place in ~/plantuml.jar or set PLANTUML_JAR)
Graphviz (optional)	Complex layouts	https://graphviz.org/download/

Creating Diagrams

Diagram Type Identification

Identify the appropriate diagram type based on user intent.

WikiTicket / GitHub wiki default is design-doc-mermaid. Use the sequence, class, activity, state, ER, and component rows below only when the user names PlantUML or you are converting existing .puml files. Always emit PNG or SVG. Never leave a raw PlantUML fence as the only view.

User Intent	Diagram Type	Reference
UI mock, screen sketch	Salt wireframe	references/wireframes_salt.md
Actors and goals	Use Case	references/use_case_diagrams.md
Clock, waveform	Timing	references/timing_diagrams.md
Enterprise layers	ArchiMate	references/archimate_diagrams.md
Network rack	nwdiag	references/network_diagrams.md
Work breakdown	WBS	references/wbs_diagrams.md
Interactions over time (only if user names PlantUML)	Sequence	references/sequence_diagrams.md
System structure with classes (only if user names PlantUML)	Class	references/class_diagrams.md
Workflows, decision flows (only if user names PlantUML)	Activity	references/activity_diagrams.md
Object states and transitions (only if user names PlantUML)	State	references/state_diagrams.md
Database schemas (only if user names PlantUML)	ER (Entity Relationship)	references/er_diagrams.md
Project timelines	Gantt	references/gantt_diagrams.md
Idea organization	MindMap	references/mindmap_diagrams.md
System architecture (only if user names PlantUML)	Component	references/component_diagrams.md
All 19 types	See navigation hub	references/toc.md
WikiTicket / GitHub wiki / Confluence	Image export rules	references/wiki-ticket-integration.md

Syntax resources:

• references/toc.md: Navigation hub linking to all diagram types
• references/common_format.md: Universal elements (delimiters, metadata, comments, notes)
• references/styling_guide.md: Modern <style> syntax for visual customization

Resilient Workflow (Primary - Recommended)

For reliable diagram generation with error recovery, follow the 4-step resilient workflow:

Step 1: Identify Diagram Type & Load Reference

• Identify diagram type from user intent
• Load references/[diagram_type]_diagrams.md for syntax guide
• Consult references/toc.md if ambiguous

Step 2: Create File with Structured Naming

./diagrams/<markdown_name>_<num>_<type>_<title>.puml

Example: ./diagrams/architecture_001_sequence_user_auth.puml

Step 3: Convert with Error Handling (max 3 retries)

If conversion fails:

1. Check references/troubleshooting/toc.md for error classification
2. Load specific guide from references/troubleshooting/[category]_guide.md
3. Check references/common_syntax_errors.md for diagram type

Step 4: Validate & Integrate

1. Verify image file exists
2. Add image link: ![title](diagrams/filename.png)
3. Keep .puml source file for future edits

Full documentation: references/workflows/resilient-execution-guide.md

Quick Syntax Reference

Common elements:

• Delimiters: @startuml / @enduml (required)
• Comments: ' Single line or /' Multi-line '/
• Relationships: -> (solid), --> (dashed), ..> (dotted)
• Labels: A -> B : Label text

Minimal examples (see references/[type]_diagrams.md for comprehensive syntax):

' Sequence: references/sequence_diagrams.md
@startuml
Alice -> Bob: Request
Bob --> Alice: Response
@enduml

' Class: references/class_diagrams.md
@startuml
class Animal { +move() }
class Dog extends Animal { +bark() }
@enduml

' ER: references/er_diagrams.md
@startuml
entity User { *id: int }
entity Post { *id: int }
User ||--o{ Post
@enduml

Converting Source Code to Diagrams

The examples/ directory contains language-specific templates for converting common application architectures:

Application Type	Directory	Key Diagrams
Spring Boot	examples/spring-boot/	Deployment, Component, Sequence
FastAPI	examples/fastapi/	Deployment, Component (async routers)
Python ETL	examples/python-etl/	Architecture with Airflow
Node.js	examples/nodejs-web/	Express/Nest.js components
React	examples/react-frontend/	SPA deployment, component architecture

Workflow:

1. Identify application type
2. Review example in examples/[app-type]/
3. Map code structure to diagram patterns
4. Copy and adapt the example .puml file
5. Use Unicode symbols from references/unicode_symbols.md for semantic clarity

Converting Diagrams to Images

Convert Standalone .puml Files

# Convert to PNG (default)
python scripts/convert_puml.py diagram.puml

# Convert to SVG
python scripts/convert_puml.py diagram.puml --format svg

# Specify output directory
python scripts/convert_puml.py diagram.puml --format svg --output-dir images/

Extract and Convert from Markdown

CRITICAL for Confluence/Notion: Run this FIRST before upload if markdown contains PlantUML diagrams.

# Process embedded ```puml blocks AND linked ![](diagram.puml) files
python scripts/process_markdown_puml.py article.md

# Convert to SVG format
python scripts/process_markdown_puml.py article.md --format svg

# Validate syntax only (for CI/CD)
python scripts/process_markdown_puml.py article.md --validate

Outputs:

• article_with_images.md: Markdown with image links
• images/: Directory with generated images

IDE-Friendly Workflow: Keep diagrams as .puml files during development for IDE preview, then convert for publication.

Direct Command-Line Usage

# Basic conversion
java -jar ~/plantuml.jar diagram.puml

# SVG with custom output
java -jar ~/plantuml.jar --svg --output-dir out/ diagram.puml

# Batch conversion
java -jar ~/plantuml.jar "**/*.puml" --svg

See references/plantuml_reference.md for comprehensive command-line options.

Best Practices

Diagram Quality:

• Use descriptive filenames from diagram content
• Add comments with ' for clarity
• Follow standard UML notation
• Test incrementally before adding complexity

Format Selection:

• PNG: Web publishing, smaller files, fixed resolution
• SVG: Documentation, scalable, supports hyperlinks

Styling: Apply modern <style> syntax from references/styling_guide.md:

@startuml
<style>
classDiagram {
  class { BackgroundColor LightBlue }
}
</style>
' diagram content
@enduml

Themes: !theme cerulean (also: bluegray, plain, sketchy, amiga)

Unicode symbols: Add semantic meaning with symbols from references/unicode_symbols.md:

node "☁️ AWS Cloud" as aws
database "💾 PostgreSQL" as db

Troubleshooting

Quick diagnosis:

1. Check syntax: java -jar plantuml.jar --check-syntax file.puml
2. Identify error type
3. Load troubleshooting guide: references/troubleshooting/toc.md

Common issues:

Issue	Solution
"plantuml.jar not found"	Download from https://plantuml.com/download, set PLANTUML_JAR
"Graphviz not found"	Install from https://graphviz.org/download/
"Syntax Error"	Check delimiters match, consult references/common_format.md
"Java not found"	Install Java JRE/JDK 8+, verify with java -version

Comprehensive guides (215+ errors documented):

• references/troubleshooting/toc.md - Navigation hub with error decision tree
• references/troubleshooting/[category]_guide.md - 12 focused guides by error type

References

Core Syntax References

Resource	Purpose
references/wiki-ticket-integration.md	WikiTicket leftover types, always PNG/SVG, Confluence upload
references/toc.md	Navigation hub for all 19 diagram types
references/common_format.md	Universal elements (delimiters, metadata, comments)
references/styling_guide.md	Modern <style> syntax with CSS-like rules
references/plantuml_reference.md	Installation, CLI, and troubleshooting

Troubleshooting Guides

Resource	Coverage
references/troubleshooting/toc.md	Navigation hub with error decision tree
references/troubleshooting/installation_setup_guide.md	Setup problems
references/troubleshooting/general_syntax_guide.md	Syntax errors
references/troubleshooting/[diagram_type]_guide.md	Diagram-specific errors

Enrichment Resources

Resource	Purpose
references/unicode_symbols.md	Unicode symbols for semantic enrichment
examples/[framework]/	Code-to-diagram patterns

Summary

1. Verify setup: python scripts/check_setup.py
2. Navigate types: Start with references/toc.md
3. Learn syntax: Open references/[diagram_type]_diagrams.md
4. Apply styling: Use references/styling_guide.md
5. Add symbols: Use references/unicode_symbols.md
6. Convert files: scripts/convert_puml.py
7. Process markdown: scripts/process_markdown_puml.py
8. Troubleshoot: references/troubleshooting/toc.md

Supported diagrams:

• UML: sequence, class, activity, state, component, deployment, use case, object, timing
• Non-UML: ER, Gantt, mindmap, WBS, JSON/YAML, network, Archimate, wireframes