Uml Diagram

Vodou UML Diagram Generator

Overview

Transform your system design ideas into professional UML diagrams instantly. This skill leverages the uml-mcp server to generate class diagrams, sequence diagrams, activity diagrams, and more using PlantUML syntax with real-time rendering capabilities.

Prerequisites

• uml-mcp server must be connected and healthy
• Internet connection for PlantUML rendering (or local PlantUML server)
• Basic understanding of UML diagram concepts

Core Workflow

1. Diagram Planning and Analysis

⏸️ STOPPING POINT - Diagram Subject

First, what are we drawing?

"Describe the system or flow you want diagrammed — or paste PlantUML source directly."

Your answer is captured as {{SUBJECT}} and is what the diagram is generated FROM. Without it the generator receives no code and fails with Received undefined — this phase is not optional decoration.

⏸️ STOPPING POINT - Diagram Requirements

Then pick the notation:

1. Class Diagram - Show classes, attributes, methods, and relationships
2. Sequence Diagram - Display interactions between objects over time
3. Activity Diagram - Illustrate workflows and business processes
4. Component Diagram - Visualize system components and dependencies
5. State Diagram - Show state transitions and behavior
6. Use Case Diagram - Document actors and use cases

Which diagram type best fits your needs?

2. Content Analysis and Code Generation

Once you've selected a diagram type, I'll help generate the appropriate PlantUML code:

# Class structure: summarize entities/relationships from your repo (search/read in editor), then pass that text into generate_uml or describe it in {{TOPIC}}

⏸️ STOPPING POINT - PlantUML Code Review

Based on your requirements, I'll generate PlantUML syntax. Here are the options:

A) Use existing code analysis to auto-generate diagram structure B) Create diagram from scratch using your specifications C) Start with a template and customize it together D) Analyze existing UML files and improve them

Which approach works best for your project?

3. Diagram Generation and Rendering

Generate the UML diagram with real-time rendering:

# Generate class diagram
./vodou-core call uml-mcp generate_uml '{
  "diagram_type": "class",
  "code": "@startuml\nclass User {\n  -id: int\n  -name: string\n  +login(): boolean\n  +logout(): void\n}\n\nclass Order {\n  -id: int\n  -items: List<Item>\n  +addItem(item: Item): void\n  +calculateTotal(): double\n}\n\nUser \"1\" -- \"many\" Order: places\n@enduml"
}'

# Generate sequence diagram for user interactions
./vodou-core call uml-mcp generate_uml '{
  "diagram_type": "sequence",
  "code": "@startuml\nactor User\nparticipant \"Web App\" as WA\nparticipant \"API\" as API\nparticipant \"Database\" as DB\n\nUser -> WA: Login Request\nWA -> API: POST /auth/login\nAPI -> DB: Validate Credentials\nDB --> API: User Data\nAPI --> WA: JWT Token\nWA --> User: Login Success\n@enduml"
}'

# Generate activity diagram for workflows
./vodou-core call uml-mcp generate_uml '{
  "diagram_type": "activity",
  "code": "@startuml\nstart\n:User Login;\nif (Valid Credentials?) then (yes)\n  :Generate Token;\n  :Redirect to Dashboard;\n  stop\nelse (no)\n  :Show Error Message;\n  :Return to Login;\n  stop\nendif\n@enduml"
}'

4. Advanced Diagram Patterns

System Architecture Visualization

# Component diagram showing system architecture
./vodou-core call uml-mcp generate_uml '{
  "diagram_type": "component",
  "code": "@startuml\npackage \"Frontend\" {\n  [React App]\n  [Redux Store]\n}\n\npackage \"Backend\" {\n  [API Gateway]\n  [Auth Service]\n  [User Service]\n  [Payment Service]\n}\n\npackage \"Database\" {\n  [User DB]\n  [Order DB]\n  [Payment DB]\n}\n\n[React App] --> [API Gateway]\n[API Gateway] --> [Auth Service]\n[API Gateway] --> [User Service]\n[API Gateway] --> [Payment Service]\n[User Service] --> [User DB]\n[Payment Service] --> [Payment DB]\n@enduml"
}'

Database Entity Relationships

# Object diagram showing database relationships
./vodou-core call uml-mcp generate_uml '{
  "diagram_type": "object",
  "code": "@startuml\nobject User {\n  id = 1\n  name = \"John Doe\"\n  email = \"john@example.com\"\n}\n\nobject Order {\n  id = 101\n  date = \"2024-01-05\"\n  status = \"completed\"\n}\n\nobject Product {\n  id = 501\n  name = \"Laptop\"\n  price = 999.99\n}\n\nUser ||--o{ Order\nOrder ||--o{ Product\n@enduml"
}'

State Machine Modeling

# State diagram for user session management
./vodou-core call uml-mcp generate_uml '{
  "diagram_type": "state",
  "code": "@startuml\n[*] --> Logged_Out\nLogged_Out --> Authenticating : login_attempt\nAuthenticating --> Logged_In : success\nAuthenticating --> Logged_Out : failure\nLogged_In --> Active : user_activity\nLogged_In --> Idle : timeout\nIdle --> Active : user_activity\nIdle --> Logged_Out : session_expire\nActive --> Logged_Out : logout\n@enduml"
}'

Advanced Usage

Multi-Diagram Documentation Workflow

⏸️ STOPPING POINT - Documentation Scope

For comprehensive system documentation, I can generate multiple related diagrams:

"I can create a complete diagram suite for your system. What's your documentation goal?"

1. System Overview - High-level architecture with component diagrams
2. User Interactions - Use case and sequence diagrams
3. Data Flow - Activity and state diagrams
4. Code Structure - Class and object diagrams
5. Custom Focus - Specific subsystem or feature area

Which documentation approach would be most valuable?

Complete System Documentation Example

# Generate comprehensive system documentation
./vodou-core call uml-mcp generate_uml '{
  "diagram_type": "usecase",
  "code": "@startuml\nactor User\nactor Admin\n\nrectangle \"E-commerce System\" {\n  User --> (Browse Products)\n  User --> (Add to Cart)\n  User --> (Checkout)\n  User --> (Track Order)\n  \n  Admin --> (Manage Products)\n  Admin --> (View Orders)\n  Admin --> (Generate Reports)\n}\n@enduml"
}'

Integration with Code Analysis

Combine UML generation with code analysis for living documentation:

# Infer structure from src/ (layout, rg) and any **Vodou memory** notes on architecture; feed uml-mcp generate_uml with PlantUML or a rich {{TOPIC}}

Collaborative Diagram Review

⏸️ STOPPING POINT - Review and Refinement

After generating initial diagrams:

"Your diagram has been generated! Here's what I can help you with next:"

1. Refine the diagram - Adjust layout, add details, or modify relationships
2. Generate additional views - Create related diagrams from different perspectives
3. Export variations - Create different formats or simplified versions
4. Integration planning - Show how this fits with existing documentation

What would be most helpful for your project?

Best Practices

1. Start Simple, Add Complexity

• Begin with core entities and relationships
• Add details incrementally
• Use PlantUML's grouping features for organization

2. Follow UML Conventions

• Use proper UML notation for relationships
• Include appropriate visibility modifiers (+, -, #, ~)
• Name classes and methods clearly

3. Optimize for Readability

• Group related elements logically
• Use consistent naming conventions
• Add notes and comments for clarity

4. Version Control Your Diagrams

• Save PlantUML code alongside your project
• Track changes to system design over time
• Use descriptive diagram titles and dates

Examples

Example 1: E-commerce Class Diagram

# Generate comprehensive e-commerce system class diagram
./vodou-core call uml-mcp generate_uml '{
  "diagram_type": "class",
  "code": "@startuml\ntitle E-commerce System - Core Classes\n\nclass User {\n  -id: Long\n  -username: String\n  -email: String\n  -password: String\n  +login(credentials): boolean\n  +logout(): void\n  +updateProfile(data): void\n}\n\nclass Product {\n  -id: Long\n  -name: String\n  -price: BigDecimal\n  -inventory: Integer\n  +updatePrice(price): void\n  +checkAvailability(): boolean\n}\n\nclass Order {\n  -id: Long\n  -date: LocalDateTime\n  -status: OrderStatus\n  -items: List<OrderItem>\n  +addItem(product, quantity): void\n  +calculateTotal(): BigDecimal\n  +process(): void\n}\n\nclass OrderItem {\n  -quantity: Integer\n  -unitPrice: BigDecimal\n  +getSubtotal(): BigDecimal\n}\n\nenum OrderStatus {\n  PENDING\n  PROCESSING\n  SHIPPED\n  DELIVERED\n  CANCELLED\n}\n\nUser \"1\" -- \"many\" Order : places\nOrder \"1\" -- \"many\" OrderItem : contains\nOrderItem \"many\" -- \"1\" Product : references\nOrder -- OrderStatus\n@enduml"
}'

Example 2: Microservices Sequence Diagram

# Generate microservices interaction sequence diagram
./vodou-core call uml-mcp generate_uml '{
  "diagram_type": "sequence",
  "code": "@startuml\ntitle Order Processing - Microservices Flow\n\nactor Customer\nparticipant \"Web UI\" as UI\nparticipant \"API Gateway\" as Gateway\nparticipant \"Order Service\" as Order\nparticipant \"Payment Service\" as Payment\nparticipant \"Inventory Service\" as Inventory\nparticipant \"Notification Service\" as Notification\n\nCustomer -> UI: Place Order\nUI -> Gateway: POST /orders\nGateway -> Order: Create Order\n\nOrder -> Inventory: Check Stock\nInventory --> Order: Stock Available\n\nOrder -> Payment: Process Payment\nPayment --> Order: Payment Successful\n\nOrder -> Inventory: Reserve Items\nInventory --> Order: Items Reserved\n\nOrder -> Notification: Send Confirmation\nNotification --> Customer: Order Confirmation Email\n\nOrder --> Gateway: Order Created\nGateway --> UI: Success Response\nUI --> Customer: Order Confirmation\n@enduml"
}'

Example 3: User Journey Activity Diagram

# Generate user registration and onboarding activity diagram
./vodou-core call uml-mcp generate_uml '{
  "diagram_type": "activity",
  "code": "@startuml\ntitle User Onboarding Process\n\nstart\n:User visits registration page;\n:Fill registration form;\n\nif (Valid data?) then (yes)\n  :Create account;\n  :Send verification email;\n  :Wait for email verification;\n  \n  if (Email verified?) then (yes)\n    :Activate account;\n    :Show welcome tutorial;\n    \n    if (Complete tutorial?) then (yes)\n      :Redirect to dashboard;\n      :Log onboarding complete;\n      stop\n    else (skip)\n      :Redirect to dashboard;\n      :Mark tutorial as skipped;\n      stop\n    endif\n  else (timeout)\n    :Send reminder email;\n    :Account remains inactive;\n    stop\n  endif\nelse (no)\n  :Show validation errors;\n  :Return to form;\n  stop\nendif\n@enduml"
}'

Troubleshooting

Common Issues

Problem: PlantUML syntax errors in generated diagrams Solution: Validate PlantUML code at http://www.plantuml.com/plantuml before generating

Problem: Complex diagrams are hard to read Solution: Break large diagrams into smaller, focused views using PlantUML packages

Problem: Diagram doesn't render or shows error Solution:

# Check uml-mcp server health
./vodou-core call uml-mcp generate_uml '{"diagram_type": "class", "code": "@startuml\nclass Test\n@enduml"}'

# Verify PlantUML server connectivity
# Default server: http://www.plantuml.com/plantuml

Problem: Need offline diagram generation Solution: Set up local PlantUML server:

# Run local PlantUML server with Docker
docker run -d -p 8080:8080 plantuml/plantuml-server

# Configure uml-mcp to use local server
export PLANTUML_SERVER="http://localhost:8080"

🔗 URL Display Best Practices

CRITICAL: When presenting UML diagram results, always format URLs properly to prevent truncation!

✅ CORRECT URL Presentation:

🔗 **View Your Diagram:** [Click here to view your UML Class Diagram](full-plantuml-url)

🎨 **Your UML Diagram is Ready!**
[**→ View Class Diagram**](url-here)

❌ INCORRECT - Causes Truncation:

Your diagram URL: http://www.plantuml.com/plantuml/svg/very-long-encoded-string-that-gets-cut-off-in-display...

📋 AI Agent URL Handling Instructions:

When presenting diagram results to users:

1. Use Markdown Links: Always format as [descriptive text](URL) - NEVER show raw URLs
2. Descriptive Text: Use clear action words like "View your Class Diagram"
3. Visual Emphasis: Add emojis (🔗, 🎨, 📊) and bold formatting
4. Accessibility: Ensure links work in all environments
5. Context: Include diagram type in link text
6. ⚠️ CRITICAL: Keep link text SHORT to prevent line wrapping that breaks clickability
7. ⚠️ CRITICAL: Never show raw URLs as they get truncated and become unclickable

📝 Example Proper Response Format:

## 🎨 **UML Diagram Generated Successfully!**

🔗 **View Your Diagram:** [**→ View Class Diagram**](plantuml-url)

**Diagram Type**: Class Diagram  
**Format**: SVG (scalable vector graphics)  
**Status**: ✅ Ready for viewing and sharing

⚠️ CRITICAL LINK FORMAT RULES:

✅ GOOD - Short Link Text (Prevents Line Wrapping):

• [**→ View Diagram**](url)
• [**Class Diagram**](url)
• [**→ Open**](url)
• [**View UML**](url)

❌ BAD - Long Link Text (Causes Line Wrapping):

• [Click here to view your comprehensive UML Class Diagram with all relationships](url) ❌ TOO LONG
• [View your detailed system architecture component diagram](url) ❌ TOO LONG

🎯 OPTIMAL FORMAT:

🔗 [**→ View Diagram**](url)

🚨 TERMINAL DISPLAY ISSUE - PlantUML URLs Are Inherently Long

PROBLEM: PlantUML URLs are 80-200+ characters and WILL wrap in most terminal windows, causing the markdown link to break and only the first line to be clickable.

SOLUTIONS:

Option 1: Block Format (Recommended)

🔗 **UML Diagram Ready!**

[**→ CLICK HERE TO VIEW DIAGRAM**](url)

**Type**: Class Diagram

Option 2: Separated Display

## 🎨 **Your UML Diagram is Ready!**

**Diagram Type:** Class Diagram  
**Status:** ✅ Generated successfully

**🔗 View Link:**  
[**OPEN DIAGRAM**](url)

Option 3: Copy-Paste Instructions (RECOMMENDED)

🔗 **Diagram Generated!**

**To view your diagram, copy this URL to your browser:**

http://www.plantuml.com/plantuml/svg/encoded-string-here

**Type:** Class Diagram | **Format:** SVG

Option 4: Code Block Format (Alternative)

## 🎨 **UML Diagram Ready!**

Copy and paste this URL into your browser to view:

http://www.plantuml.com/plantuml/svg/encoded-string-here

**Diagram Details:** Class diagram with User/Order relationship

⚠️ IMPORTANT: PlantUML URLs are 80-200+ characters and will wrap in terminals. Copy-paste approach (Option 3 & 4) eliminates clickability issues entirely.

✅ RECOMMENDED: Use copy-paste format to avoid all terminal line-wrapping and clickability problems!

Integration with Other Skills

With Code Analysis

# Summarize structure from the repo, then generate class diagram from that summary
./do "generate uml class diagram for [subsystem]"

With Documentation

# Create diagrams as part of documentation workflow
./do "generate system documentation with uml diagrams"

With Architecture Planning

# Use for system design and architecture discussions
./do "design microservices architecture with component diagrams"

Quick Reference

# Generate class diagram
./vodou-core call uml-mcp generate_uml '{"diagram_type": "class", "code": "@startuml\nclass Example\n@enduml"}'

# Generate sequence diagram  
./vodou-core call uml-mcp generate_uml '{"diagram_type": "sequence", "code": "@startuml\nA -> B: message\n@enduml"}'

# Generate activity diagram
./vodou-core call uml-mcp generate_uml '{"diagram_type": "activity", "code": "@startuml\nstart\n:action;\nstop\n@enduml"}'

# Check server health
./vodou-core call uml-mcp generate_uml '{"diagram_type": "class", "code": "@startuml\nclass Health\n@enduml"}'

Performance Tips

1. Keep diagrams focused - One diagram per concept or system area
2. Use packages - Organize related elements with PlantUML packages
3. Leverage templates - Create reusable PlantUML code patterns
4. Validate syntax - Check PlantUML syntax before generation to avoid errors

Transform your system designs into clear, professional diagrams that communicate effectively with stakeholders and team members!