PlantUML Sequence Diagram Syntax and Examples

What Is a PlantUML Sequence Diagram?

A PlantUML sequence diagram is a UML behavioral diagram that shows messages exchanged between users, objects, services, and other participants in time order. It makes the order of an interaction visible, from the first request through each response or side effect.

Common Use Cases for Sequence Diagrams

Use sequence diagrams to document REST API requests and responses, login and payment flows, microservice calls, and asynchronous messages. They also help with production troubleshooting, user-story discussions, and architecture reviews because everyone can inspect the same interaction timeline.

Participants and Lifelines

Declare each lifeline with the keyword that best describes its role: actor for a person or external system, participant for a general component, boundary for an interface, control for orchestration, entity for domain data, and database for stored records. Add an alias such as participant "Payment API" as PaymentApi to keep messages short while preserving clear labels.

Messages and Return Values

Use -> for a synchronous request and --> for a return value. Use ->> and -->> when the message or response is asynchronous. Label every arrow with an action or meaningful result, such as "POST /orders" or "201 Created", so readers can understand the intent and outcome without guessing.

Conditions with alt and else

Use alt and else to show mutually exclusive outcomes in one readable interaction, such as a login, authorization check, or payment decision. Put the business condition in the alt label and make each response explicit.

alt Payment approved
  Client -> Payment API: Capture payment
  Payment API --> Client: Payment confirmed
else Payment declined
  Payment API --> Client: Decline reason
end

Loops, Notes, and Grouped Interactions

Use loop for repeated work such as polling, retries, or processing batches. Add a note over one or more participants when an assumption needs context, and use group or box to visually organize related interactions, services, or bounded responsibilities.

loop Retry up to 3 times
  Worker -> Queue: Poll message
  Queue --> Worker: Return job or empty result
end

Asynchronous Messages and Parallel Work

Use ->> to distinguish an asynchronous event or queued command from a synchronous call that waits for a reply. Use par, and, and end to show independent work that can happen in parallel, such as notifying a customer while a worker updates analytics.

Sequence Diagram Best Practices

Give participants stable, descriptive names and keep message granularity consistent across the diagram. Limit crossing lines by ordering lifelines thoughtfully, split very long flows into focused diagrams, and keep the PlantUML source with the code or documentation so the diagram can be reviewed and updated.