plant uml cheat sheet.md

PlantUML Comprehensive LLM Cheat Sheet

Complete systematic analysis and reference guide for AI assistants working with PlantUML

Table of Contents

1. Universal Syntax Fundamentals
2. Diagram Types Reference
3. Advanced Features
4. LLM Best Practices
5. Common Patterns & Templates
6. Troubleshooting Guide

---

Universal Syntax Fundamentals

Basic Structure

@startuml [optional_diagram_name]
' Your diagram content here
@enduml

Core Conventions

• Comments: ' (single line) or /' ... '/ (multi-line block)
• String handling: Use "quotes" for names with spaces/special chars
• Aliases: as keyword creates short references
• Colors: #hexcode, colorname, or gradients #color1|color2
• Styling: Inline #color or global skinparam

Essential Patterns

' Variable naming (preprocessing)
!$variable = "value"

' Color application
element #color
element #back:color;line:color;text:color

' Multiline text
"First line\nSecond line"

' Aliases for complex names
component "Complex System Name" as CSN

---

Diagram Types Reference

1. Sequence Diagrams

Core Syntax:

@startuml
participant Alice
actor Bob
database "Database" as DB

Alice -> Bob: Request
Bob --> Alice: Response
Alice -> DB: Store data
note right of Alice: This is a note
@enduml

Key Features:

• Participants: participant, actor, boundary, control, entity, database, collections, queue
• Arrows: -> (solid), --> (dashed), <- (reverse)
• Arrow styles: ->x (lost), ->> (thin), ->o (circle), <-> (bidirectional)
• Activation: activate/deactivate or ++/--
• Grouping: alt/else/end, opt, loop, par, group, critical
• Auto-numbering: autonumber [start] [increment] ["format"]
• Notes: note left/right/over : text

Advanced Patterns:

' Message alignment
skinparam sequenceMessageAlign right

' Participant ordering
participant Last order 30
participant First order 10

' Multiline participants
participant Participant [
  =Title
  ----
  ""SubTitle""
]

' Colored arrows
Alice -[#red]> Bob: colored message

2. Class Diagrams

Core Syntax:

@startuml
class User {
  +name: string
  -password: string
  #email: string
  ~id: int
  --
  +login()
  +logout()
  -validatePassword()
}

class Admin extends User
User ||--o{ Order : places
@enduml

Key Relationships:

Symbol	Meaning	Usage
<|--	Inheritance	Child <|-- Parent
<|..	Implementation	Class <|.. Interface
*--	Composition	Whole *-- Part
o--	Aggregation	Container o-- Item
-->	Dependency	Client --> Service
..>	Weak dependency	A ..> B

Visibility Modifiers:

• + Public
• - Private
• # Protected
• ~ Package

Advanced Features:

' Association classes
class Student
class Course
(Student, Course) .. Enrollment

' Package organization
package "com.example" {
  class MyClass
}

' Stereotypes and spots
class System << (S,#FF7700) Singleton >>

3. Activity Diagrams (New Syntax)

Core Syntax:

@startuml
start
:Initialize system;
if (System ready?) then (yes)
  :Process request;
  if (Valid input?) then (yes)
    :Execute action;
  else (no)
    :Show error;
    stop
  endif
else (no)
  :Wait for system;
endif
:Send response;
end
@enduml

Control Structures:

• Conditionals: if/then/else/endif
• Switches: switch/case/endswitch
• Loops: repeat/repeatwhile, while/endwhile
• Parallel: fork/fork again/end fork
• Partitions: partition "Name" { ... }
• Swimlanes: |Actor| :action;

Advanced Patterns:

' Colored activities
#HotPink:Critical process;

' SDL shapes (Specification Description Language)
:Input< 
:Output>
:Procedure|
:Save/
:Load\

' Kill/Detach
:Process data;
kill

' Connectors
start
:Activity;
(A)
detach
(A)
:Other activity;

4. Use Case Diagrams

@startuml
left to right direction

:User: --> (Login)
:Admin: --> (Manage Users)

package System {
  (Login) .> (Validate Credentials) : include
  (Manage Users) .> (Login) : include
}

:User: --> (Browse Products)
@enduml

Key Elements:

• Actors: :Actor Name:
• Use Cases: (Use Case)
• Relationships: --> (association), .> (include/extend)
• Packages: package Name { ... }

5. Component Diagrams

@startuml
package "Web Layer" {
  component [Web Controller] as WC
  component [Web Service] as WS
}

package "Business Layer" {
  component [Business Logic] as BL
  component [Data Access] as DA
}

database "Database" as DB

WC --> WS
WS --> BL
BL --> DA
DA --> DB
@enduml

6. State Diagrams

@startuml
[*] --> Idle
Idle --> Processing : start
Processing --> Idle : complete
Processing --> Error : failure
Error --> Idle : reset
Idle --> [*] : shutdown

state Processing {
  [*] --> Loading
  Loading --> Executing
  Executing --> Validating
  Validating --> [*]
}
@enduml

7. Specialized Diagrams

Gantt Charts

@startgantt
Project starts 2024-01-01

[Design Phase] requires 2 weeks
[Implementation] requires 3 weeks
[Testing] requires 1 week

[Implementation] starts at [Design Phase]'s end
[Testing] starts at [Implementation]'s end

[Design Phase] is colored in lightblue
[Implementation] is colored in lightgreen
[Testing] is colored in orange
@endgantt

Mind Maps

@startmindmap
* Central Topic
** Right Branch 1
*** Sub-item 1
*** Sub-item 2
** Right Branch 2
left side
** Left Branch 1
*** Left Sub-item
** Left Branch 2
@endmindmap

Network Diagrams (nwdiag)

@startuml
nwdiag {
  network internet {
    web01 [shape = cloud];
  }
  network internal {
    web01;
    db01 [shape = database];
    app01;
  }
}
@enduml

---

Advanced Features

Preprocessing System

PlantUML includes a powerful preprocessing system for dynamic content generation:

Variables and Functions

@startuml
!$company = "Acme Corp"
!$version = 1.2

!function $header($title)
!return $title + " v" + $version + " - " + $company
!endfunction

title $header("System Architecture")

' Rest of diagram...
@enduml

Conditional Logic

@startuml
!$environment = "production"

!if $environment == "production"
  skinparam backgroundColor lightgreen
!else
  skinparam backgroundColor lightcoral
!endif

' Conditional elements
!if $environment == "production"
  database "Production DB" as ProdDB
!else
  database "Test DB" as TestDB
!endif
@enduml

Loops and Iteration

@startuml
!procedure $createServers($count)
  !$i = 1
  !while $i <= $count
    component "Server $i" as S$i
    !$i = $i + 1
  !endwhile
!endprocedure

$createServers(3)
S1 --> S2
S2 --> S3
@enduml

Styling and Themes

Skinparam (Global Styling)

@startuml
skinparam {
  backgroundColor #E8F4FD
  defaultFontSize 12
  defaultFontName Arial
  
  class {
    BackgroundColor lightblue
    BorderColor darkblue
    ArrowColor black
  }
  
  sequence {
    ParticipantBorderColor black
    ParticipantBackgroundColor #EEEEEE
    MessageAlign center
  }
}

' Your diagram content...
@enduml

Inline Styling

@startuml
' Color syntax: #[background];line:color;line.style;text:color
class Important #red;line:black;line.bold;text:white
component Service #lightblue;line:blue;line.dashed
@enduml

Style Sheets

@startuml
<style>
classDiagram {
  class {
    BackgroundColor #E1F5FE
    BorderColor #0277BD
    FontSize 14
    FontStyle bold
  }
  
  .important {
    BackgroundColor #FFCDD2
    BorderColor #D32F2F
  }
}
</style>

class NormalClass
class ImportantClass <<important>>
@enduml

Data Visualization

JSON Display

@startjson
{
  "name": "John Doe",
  "age": 30,
  "skills": ["Java", "Python", "PlantUML"],
  "address": {
    "city": "New York",
    "country": "USA"
  }
}
@endjson

YAML Display

@startyaml
name: John Doe
age: 30
skills:
  - Java
  - Python  
  - PlantUML
address:
  city: New York
  country: USA
@endyaml

Standard Library Integration

@startuml
!include <aws/AWSCommon>
!include <aws/Compute/AmazonEC2/AmazonEC2>
!include <aws/Database/AmazonRDS/AmazonRDS>
!include <aws/Storage/AmazonS3/AmazonS3>

AmazonEC2(ec2, "Web Server", "")
AmazonRDS(rds, "Database", "")
AmazonS3(s3, "File Storage", "")

ec2 --> rds
ec2 --> s3
@enduml

---

LLM Best Practices

1. Approach Strategy

Start Simple, Add Complexity:

' Phase 1: Basic structure
@startuml
A -> B
@enduml

' Phase 2: Add details
@startuml
participant "System A" as A
participant "System B" as B
A -> B: Request
B --> A: Response
@enduml

' Phase 3: Add styling and notes
@startuml
participant "System A" as A #lightblue
participant "System B" as B #lightgreen
A -> B: Request
note right: Important interaction
B --> A: Response
@enduml

2. Error Prevention Patterns

Safe Naming:

' Good: Use aliases for complex names
component "Complex-System_Name (v2.1)" as CSN
database "User Database Server" as UDB

' Avoid: Special characters in direct references
' component Complex-System_Name (v2.1)  // This could cause issues

Quote Management:

' Safe approach for special characters
participant "User with spaces" as User
actor "Admin (Super)" as Admin
note over User, Admin: "Quoted text with ""nested"" quotes"

3. Layout Control Techniques

@startuml
' Control diagram direction
left to right direction

' Group related elements
together {
  class A
  class B
}

' Force layout with hidden connections
A -[hidden]-> C
B -[hidden]-> D

' Use packages for organization
package "Layer 1" {
  class Service1
}
package "Layer 2" {
  class Service2
}
@enduml

4. Responsive Design Considerations

@startuml
' Set appropriate scaling
scale 1.2

' Control text wrapping
skinparam maxMessageSize 100
skinparam wrapWidth 200

' Use meaningful short names
participant "Long Service Name" as LSN
@enduml

---

Common Patterns & Templates

System Architecture Template

@startuml
!define SYSTEM(name, desc) rectangle name as "==name\n\n desc"
!define EXTERNAL(name, desc) rectangle name as "==name\n\n desc" #lightgray

title System Architecture Overview

SYSTEM(WebApp, "Main Web Application")
SYSTEM(API, "REST API Gateway") 
SYSTEM(Auth, "Authentication Service")
EXTERNAL(Database, "PostgreSQL Database")
EXTERNAL(Cache, "Redis Cache")

WebApp --> API: HTTP Requests
API --> Auth: Validate Token
API --> Database: Query Data
API --> Cache: Cache Results
@enduml

Process Flow Template

@startuml
!procedure $decision($condition, $yes, $no)
if ($condition) then (yes)
  :$yes;
else (no)
  :$no;
endif
!endprocedure

start
:Receive Request;
$decision("Valid Input?", "Process Request", "Return Error")
:Send Response;
stop
@enduml

Class Hierarchy Template

@startuml
abstract class Animal {
  #name: String
  #age: int
  --
  +getName(): String
  {abstract} +makeSound(): String
}

class Dog extends Animal {
  -breed: String
  --
  +makeSound(): String
}

class Cat extends Animal {
  -indoor: boolean  
  --
  +makeSound(): String
}

interface Pet {
  +play(): void
  +feed(): void
}

Dog ..|> Pet
Cat ..|> Pet
@enduml

Integration Pattern Template

@startuml
!include <aws/AWSCommon>
!include <kubernetes/k8s-sprites-unlabeled-25pct>

package "Kubernetes Cluster" {
  rectangle "<$k8s-pod>\nWeb Pods" as WebPods
  rectangle "<$k8s-svc>\nLoad Balancer" as LB
}

package "AWS Services" {
  rectangle "<$aws-rds>\nDatabase" as DB
  rectangle "<$aws-s3>\nFile Storage" as Storage
}

LB --> WebPods
WebPods --> DB
WebPods --> Storage
@enduml

---

Troubleshooting Guide

Common Syntax Issues

Issue: Parsing Errors

' Problem: Unclosed quotes or brackets
participant "User Name  // Missing closing quote

' Solution: Properly close all quotes
participant "User Name" as User

Issue: Invalid Characters

' Problem: Special characters in names
class User-Profile  // Hyphen can cause issues

' Solution: Use quotes or aliases
class "User-Profile" as UP

Layout Problems

Issue: Poor Automatic Layout

' Solution: Use layout hints
@startuml
left to right direction
skinparam nodesep 50
skinparam ranksep 50
@enduml

Issue: Text Overflow

' Solution: Control text wrapping
@startuml
skinparam maxMessageSize 50
skinparam wrapWidth 150
@enduml

Debugging Techniques

Use Logging:

@startuml
!log "Starting diagram generation"
!$counter = 0

!while $counter < 3
  !log "Creating component " + $counter
  component "Service $counter" as S$counter
  !$counter = $counter + 1
!endwhile

!log "Completed diagram with " + $counter + " components"
@enduml

Memory Debugging:

@startuml
!$debug = true

!if $debug
  !dump_memory Debug checkpoint
!endif

' Your diagram content
@enduml

Performance Optimization

For Large Diagrams:

@startuml
' Split large diagrams
page 2x2

' Use appropriate scale
scale 0.8

' Minimize complex styling
skinparam shadowing false
skinparam linetype ortho
@enduml

---

Quick Reference Tables

Arrow Types Summary

Diagram Type	Solid	Dashed	Notes
Sequence	->	-->	Use <- for reverse
Class	--	..	Add heads: `<
Activity	->	N/A	Use within flow
Use Case	-->	..>	For associations

Color Notation

Method	Example	Usage
Hex	#FF0000	Precise colors
Named	red, lightblue	Common colors
Gradient	#red|blue	Background gradients
Inline	#back:color;line:color	Complex styling

Diagram Type Keywords

Type	Start	End	Purpose
UML	@startuml	@enduml	General UML diagrams
Gantt	@startgantt	@endgantt	Project schedules
MindMap	@startmindmap	@endmindmap	Mind mapping
JSON	@startjson	@endjson	Data display
YAML	@startyaml	@endyaml	Data display

---

This comprehensive cheat sheet covers the essential patterns and advanced features needed for effective PlantUML usage by LLM systems. Always start with simple structures and progressively add complexity as needed.