L05 Plantuml

title: "PlantUML — UML Diagrams as Code" weight: 5 description: "Learn PlantUML for UML diagrams as code: sequence diagrams, use case diagrams, activity diagrams, deployment diagrams, and integration with documentation pipelines for enterprise modeling." date: 2026-06-28 lastmod: 2026-06-28 tags: [technical-writing, diagram-as-code] }

PlantUML is a diagram-as-code tool specializing in UML diagrams including sequence, use case, activity, class, and deployment diagrams for comprehensive software modeling.

In this lesson, you will learn PlantUML basics, common UML diagram types, syntax patterns, rendering options, and how to integrate PlantUML into your documentation workflow.

What You'll Learn

You will learn PlantUML syntax for sequence, use case, activity, and deployment diagrams. You will understand when to use PlantUML over Mermaid and how to integrate it with documentation builds.

Why It Matters

PlantUML is the most comprehensive UML diagram-as-code tool. For teams that need formal UML modeling with strict notation, PlantUML is the industry standard choice.

Real-World Use

DodaTech uses PlantUML for deployment diagrams showing how Doda Browser components are distributed across servers. The strict UML notation ensures consistency with enterprise architecture standards.

@startuml
actor User
participant "Doda Browser" as Browser
participant "Auth Server" as Auth
User -> Browser: Open app
Browser -> Auth: Request token
Auth --> Browser: Return token
Browser -> User: Show dashboard
@enduml

def create_plantuml_sequence(participants, messages):
    """Generate PlantUML sequence diagram syntax."""
    lines = ["@startuml"]
    for p in participants:
        if p.get("actor"):
            lines.append(f'actor "{p["name"]}" as {p["id"]}')
        else:
            lines.append(f'participant "{p["name"]}" as {p["id"]}')
    for msg in messages:
        arrow = "->" if msg["sync"] else "-->"
        lines.append(f'{msg["from"]} {arrow} {msg["to"]}: {msg["label"]}')
    lines.append("@enduml")
    return "\n".join(lines)

diagram = create_plantuml_sequence(
    [{"id": "U", "name": "User", "actor": True},
     {"id": "S", "name": "Server"}],
    [{"from": "U", "to": "S", "label": "Login request", "sync": True},
     {"from": "S", "to": "U", "label": "Login response", "sync": False}]
)
print(diagram)

def create_plantuml_activity_diagram(start_node, activities, decisions):
    """Generate PlantUML activity diagram."""
    lines = ["@startuml", ":Start;"]
    for act in activities:
        lines.append(f":{act};")
    for dec, branches in decisions.items():
        lines.append(f"if ({dec}) then (yes)")
        for b in branches.get("yes", []):
            lines.append(f"  :{b};")
        lines.append("else (no)")
        for b in branches.get("no", []):
            lines.append(f"  :{b};")
        lines.append("endif")
    lines.append(":End;")
    lines.append("@enduml")
    return "\n".join(lines)

diagram = create_plantuml_activity_diagram("Start",
    ["Process input", "Validate data"],
    {"Valid?": {"yes": ["Save data"], "no": ["Show error"]}}
)
print(diagram)

def render_plantuml_in_docs(plantuml_text, output_format="svg"):
    """Configure PlantUML rendering for documentation."""
    config = {
        "render_command": f"plantuml -t{output_format}",
        "output_directory": "static/diagrams/",
        "file_extension": output_format,
    }
    return config

Teacher Mindset

Think of PlantUML as a specialized tool in your workshop. You would not use a sledgehammer to hang a picture frame. Similarly, you would not use PlantUML for a simple flowchart. But when you need proper UML notation with strict semantics, PlantUML is the right tool. Learn when to reach for it and when to use a simpler alternative.

Common Mistakes in PlantUML

1. Using PlantUML for Simple Flowcharts

PlantUML's activity diagrams work for flowcharts, but Mermaid is simpler and renders natively in Markdown. Use PlantUML only when you need formal UML.

2. Forgetting @startuml and @enduml

Every PlantUML diagram must start with @startuml and end with @enduml. Missing these causes rendering failures.

3. Overcomplicating Deployment Diagrams

Deployment diagrams with 20+ nodes become unreadable. Show only the deployment units relevant to the documentation.

4. Not Rendering During Build

PlantUML requires Java and Graphviz to render. Missing these dependencies in CI causes broken builds. Document rendering requirements clearly.

5. Inconsistent Use of PlantUML Features

Some team members use notes, others use comments, others use colors. Standardize on a subset of features for consistent output.

Practice Questions

1. What diagram types does PlantUML support? Sequence, use case, class, activity, component, deployment, state, object, and many more. PlantUML covers the full UML specification.

2. How is PlantUML different from Mermaid? PlantUML requires a Java renderer and does not render natively in Markdown. It offers more precise UML notation and a wider range of UML diagram types.

3. How do you integrate PlantUML into a static site build? Install PlantUML (Java) and Graphviz. Run a build script that processes all .puml files into images. Store the generated images in the static directory.

4. What are the rendering requirements for PlantUML? Java Runtime Environment (JRE) and Graphviz for diagram layout. Without these, PlantUML files cannot be rendered.

5. Challenge: Create a PlantUML deployment diagram showing a 3-tier web application architecture. Include presentation, application, and database tiers with at least 2 nodes each.

FAQ

Mini Project

Create a PlantUML sequence diagram for an API authentication flow. Include actor, system, and database participants. Add notes for each step. Render to SVG and embed in documentation alongside a Mermaid version for comparison.

What's Next

Structurizr in the next lesson.