If you've ever needed to draw a sequence diagram, flowchart, or class diagram for a project, you know how tedious it can be to use drag-and-drop tools. PlantUML lets you write plain text code that renders into clean diagrams automatically. Having the right code snippets on hand saves you hours and keeps your documentation consistent across teams. This guide walks through real, copy-ready snippets for the diagrams people actually use day to day.

What is PlantUML and how does it work?

PlantUML is an open-source tool that turns plain text descriptions into UML and non-UML diagrams. You write short code snippets in a simple domain-specific language, and PlantUML renders them as images. It supports dozens of diagram types from sequence diagrams and class diagrams to mind maps and network topology charts.

You can run PlantUML locally with Java, through an IDE plugin (VS Code, IntelliJ, Eclipse), or via online editors like the official PlantUML server. The syntax is readable enough that even non-developers can follow along, which makes it practical for team collaboration.

Why do teams use PlantUML code snippets instead of drawing tools?

There are a few reasons PlantUML snippets have become standard in engineering and product teams:

  • Version control friendly. Text files diff cleanly in Git. You can track diagram changes alongside code changes without dealing with binary image files.
  • Speed. Writing a 10-line snippet is faster than dragging boxes and connecting arrows manually.
  • Consistency. The same snippet always produces the same output. No alignment drift, no font mismatches.
  • Living documentation. Snippets embedded in Markdown or AsciiDoc files update in CI pipelines, so your docs stay current.

What are the most common PlantUML diagram types?

Based on real-world usage across software teams, these are the diagrams people reach for most often. Each one below includes a working snippet you can copy and paste directly into any PlantUML renderer.

Sequence diagram

Sequence diagrams show how objects or actors exchange messages over time. They're the go-to for documenting API flows, authentication steps, or multi-service interactions.

When to use it: You need to show the order of requests between a client, server, and database during a login flow.

Snippet:

@startuml
actor User
participant "Frontend" as FE
participant "Auth Service" as Auth
database "User DB" as DB

User -> FE: Enter credentials
FE -> Auth: POST /login
Auth -> DB: Query user
DB --> Auth: User record
Auth --> FE: JWT token
FE --> User: Login success
@enduml

Class diagram

Class diagrams model the structure of a system classes, their attributes, methods, and relationships. They're essential in object-oriented design and onboarding new developers.

When to use it: You're designing a data model or explaining existing domain objects to your team.

Snippet:

@startuml
class User {
 -id: int
 -email: string
 -passwordHash: string
 +login(): bool
 +updateProfile(data): void
}

class Order {
 -id: int
 -total: decimal
 -status: string
 +place(): void
 +cancel(): void
}

User "1" -- "" Order : places
@enduml

For a deeper syntax reference on class diagram notation, check the UML diagram syntax reference guide.

Activity diagram

Activity diagrams model workflows and business processes. They're useful for mapping conditional logic, parallel tasks, and decision points.

When to use it: You want to document an approval workflow or a CI/CD pipeline with branching conditions.

Snippet:

@startuml
start
:Receive order request;
if (Items in stock?) then (yes)
 :Reserve items;
 :Process payment;
 if (Payment successful?) then (yes)
 :Ship order;
 else (no)
 :Notify payment failure;
 :Release reserved items;
 endif
else (no)
 :Notify out of stock;
endif
stop
@enduml

You can find more advanced control flow patterns, including fork/join and swim lanes, in this guide on UML activity diagram control flow examples.

Use case diagram

Use case diagrams capture what users (actors) can do with a system. They're common in early-stage requirements gathering.

When to use it: You're scoping features for a product or presenting system capabilities to non-technical stakeholders.

Snippet:

@startuml
left to right direction
actor Customer
actor Admin

rectangle "E-Commerce System" {
 usecase "Browse products" as UC1
 usecase "Add to cart" as UC2
 usecase "Checkout" as UC3
 usecase "Manage inventory" as UC4
 usecase "View reports" as UC5
}

Customer --> UC1
Customer --> UC2
Customer --> UC3
Admin --> UC4
Admin --> UC5
UC3 ..> UC2 : <>
@enduml

State diagram

State diagrams show how an object transitions between states based on events. They're valuable for modeling order lifecycles, UI flows, or protocol behavior.

When to use it: You need to document all possible states and transitions for an order, ticket, or connection object.

Snippet:

@startuml
[] --> Draft
Draft --> InReview : submit
InReview --> Approved : approve
InReview --> Rejected : reject
Rejected --> Draft : revise
Approved --> Published : publish
Published --> Archived : archive
Archived --> []
@enduml

Component diagram

Component diagrams show how a system is divided into components and how those components depend on each other. They're useful for architecture discussions.

When to use it: You're explaining a microservices layout or onboarding someone into a large codebase.

Snippet:

@startuml
package "Frontend" {
 [Web App]
 [Mobile App]
}

package "Backend" {
 [API Gateway]
 [User Service]
 [Order Service]
 [Payment Service]
}

database "PostgreSQL" as DB
database "Redis" as Cache

[Web App] --> [API Gateway]
[Mobile App] --> [API Gateway]
[API Gateway] --> [User Service]
[API Gateway] --> [Order Service]
[API Gateway] --> [Payment Service]
[User Service] --> DB
[Order Service] --> DB
[Payment Service] --> DB
[User Service] --> Cache
@enduml

Deployment diagram

Deployment diagrams map software artifacts to physical or cloud infrastructure. They help ops and dev teams communicate about where things actually run.

When to use it: You're planning infrastructure or documenting how containers and services are distributed across nodes.

Snippet:

@startuml
node "Load Balancer" as LB
node "Web Server 1" as WS1
node "Web Server 2" as WS2
node "Database Server" as DBS

LB --> WS1
LB --> WS2
WS1 --> DBS
WS2 --> DBS

artifact "Web App" as WA1 on WS1
artifact "Web App" as WA2 on WS2
artifact "PostgreSQL" as PG on DBS
@enduml

What are common mistakes when writing PlantUML snippets?

Even though PlantUML syntax is straightforward, people run into the same issues repeatedly:

  1. Forgetting @startuml and @enduml. Every snippet needs these bookend tags. Without them, nothing renders.
  2. Mismatched arrow syntax. Using --> when you mean ->, or mixing up dotted and solid lines, changes the diagram meaning. Solid lines are synchronous; dashed lines are return or asynchronous.
  3. Not quoting special characters. Class names or labels with spaces, colons, or brackets need to be wrapped in quotes. Otherwise the parser throws errors.
  4. Overcomplicating one diagram. A sequence diagram with 15 participants is unreadable. Split complex flows across multiple diagrams linked by context notes.
  5. Ignoring themes. PlantUML defaults work fine, but for documentation sites, applying a consistent !theme directive keeps diagrams visually aligned with your brand.

How can you integrate PlantUML into your workflow?

There are several practical ways to make these snippets part of your daily process:

  • IDE plugins. Install the PlantUML extension in VS Code or IntelliJ. You get live previews as you type, so you see the rendered diagram without leaving your editor.
  • CI/CD pipelines. Use the PlantUML CLI in your build pipeline to generate diagram images from .puml files on every commit. This keeps docs in sync with code.
  • Markdown embedding. If you use MkDocs, Docusaurus, or similar tools, you can embed PlantUML source directly and have it rendered at build time.
  • Collaborative editors. Some Confluence and Notion integrations support PlantUML blocks, letting non-technical team members view and edit diagrams.

Quick-start checklist for your first PlantUML diagram

  1. Choose your diagram type based on what you need to communicate (structure, behavior, interaction, or deployment).
  2. Copy the matching snippet from above into the PlantUML online editor and confirm it renders.
  3. Replace the example names, methods, and relationships with your actual system details.
  4. Export the diagram as SVG for documentation or PNG for slides.
  5. Commit the .puml source file to version control alongside the generated image.
  6. Set up an IDE plugin or CI step so diagrams regenerate automatically when the source changes.

Start with a single diagram a sequence diagram for your most important user flow is usually the highest-value starting point. Once the first one is in place and your team sees the output, adding more becomes a natural habit.