Plantuml Sequence Diagram Code Examples for Microservices Architecture

When your team manages five, ten, or twenty microservices, understanding how they talk to each other becomes a real problem. A REST call here, a message queue there, an async event firing somewhere else it all piles up fast. PlantUML sequence diagram code examples for microservices architecture give you a text-based way to map these interactions clearly, share them in pull requests, and keep them version-controlled alongside your code. This article walks through real examples you can copy, adapt, and use today.

Why use sequence diagrams for microservices instead of just documentation?

Microservices communicate across network boundaries. When something breaks or behaves unexpectedly, you need to trace the exact path a request takes through multiple services. Plain text documentation gets outdated the moment someone changes an endpoint. PlantUML sequence diagrams live as .puml files in your repository, so they update with your code. They render into visual diagrams that anyone developer, QA, or product manager can read without parsing source files.

If you're also working on class-level documentation for individual services, our PlantUML class diagram syntax reference covers the notation you'll need for that layer of detail.

What does a basic microservices sequence diagram look like in PlantUML?

Here's a simple example showing a client calling an API gateway, which routes to an auth service and then an order service:

@startuml
actor Client
participant "API Gateway" as Gateway
participant "Auth Service" as Auth
participant "Order Service" as Orders
database "Order DB" as DB

Client -> Gateway: POST /api/orders
Gateway -> Auth: Validate JWT token
Auth --> Gateway: Token valid (user_id: 42)
Gateway -> Orders: CreateOrder(userId=42, items=[...])
Orders -> DB: INSERT order record
DB --> Orders: Order created (id: 1001)
Orders --> Gateway: 201 Created {orderId: 1001}
Gateway --> Client: 201 Created {orderId: 1001}
@enduml

This covers a synchronous request flow. Each arrow represents an HTTP call or database query. The actor keyword places the external client on the left, and participant labels each service with a readable name.

How do you diagram asynchronous messaging between services?

Most real microservices architectures use message brokers like RabbitMQ, Kafka, or AWS SQS for async communication. PlantUML handles this with dashed arrows and notes:

@startuml
participant "Order Service" as Orders
participant "Message Broker" as Broker
participant "Inventory Service" as Inventory
participant "Notification Service" as Notifications

Orders -> Broker: Publish OrderCreated event
activate Broker

Broker --> Inventory: Consume OrderCreated
activate Inventory
Inventory -> Inventory: Reserve stock
Inventory -> Broker: Publish StockReserved event
deactivate Inventory

Broker --> Notifications: Consume OrderCreated
activate Notifications
Notifications -> Notifications: Send confirmation email
deactivate Notifications

Broker --> Orders: Consume StockReserved
activate Orders
Orders -> Orders: Update order status
deactivate Orders
@enduml

Notice the dashed arrows (-->) indicate asynchronous delivery. This is a common pattern: one event triggers multiple consumers independently.

How do you show error handling and retries in sequence diagrams?

Microservices fail. Network timeouts, service crashes, and validation errors are normal. Your diagrams should reflect this reality. PlantUML supports alt/else blocks for conditional flows:

@startuml
participant "API Gateway" as Gateway
participant "Payment Service" as Payment
database "Payment DB" as DB

Gateway -> Payment: ProcessPayment(orderId=1001)
activate Payment

alt Payment succeeds
 Payment -> DB: Store transaction
 DB --> Payment: Transaction stored
 Payment --> Gateway: 200 OK {transactionId: "tx-55"}
else Payment fails
 Payment --> Gateway: 500 Internal Server Error
 Gateway -> Gateway: Retry (attempt 2 of 3)
 Gateway -> Payment: ProcessPayment(orderId=1001)
 Payment -> DB: Store transaction
 DB --> Payment: Transaction stored
 Payment --> Gateway: 200 OK {transactionId: "tx-56"}
end

deactivate Payment
@enduml

You can also use loop blocks to show retry patterns explicitly, and note elements to call out timeout values or circuit breaker behavior.

What about service-to-service authentication flows?

When services use OAuth2 or mutual TLS, the authentication step adds extra participants. Here's a pattern with a dedicated auth service issuing tokens between internal services:

@startuml
participant "Order Service" as Orders
participant "Service Registry" as Registry
participant "Auth Service" as Auth
participant "Inventory Service" as Inventory

Orders -> Registry: Discover Inventory Service URL
Registry --> Orders: https://inventory.internal:8080
Orders -> Auth: Request service-to-service token
Auth --> Orders: JWT (exp: 30s, scope: inventory:read)
Orders -> Inventory: GET /stock/1001 (Bearer JWT)
Inventory -> Auth: Validate token
Auth --> Inventory: Token valid
Inventory --> Orders: 200 OK {available: 24}
@enduml

This kind of diagram helps security reviewers and new developers understand the trust boundaries between services without reading multiple README files.

What common mistakes show up in PlantUML microservices diagrams?

After working with teams that use these diagrams regularly, a few patterns repeat:

Too many participants. If your diagram has 15 services on screen, nobody reads it. Focus on the flow you're documenting. Break large flows into multiple diagrams with cross-references.
Mixing abstraction levels. Showing both HTTP calls and internal method calls in the same diagram creates confusion. Pick one level and stick with it.
Missing lifelines for databases and queues. Leaving out the data layer hides important details about where data gets stored and which service owns which table.
No activation boxes. Without activate/deactivate, it's hard to see when a service is actively processing vs. waiting.
Forgetting async indicators. Using solid arrows for message queue communication misleads readers into thinking the call is synchronous and blocking.

How do you organize PlantUML files for a microservices project?

A structure that works well across teams:

One .puml file per significant flow (e.g., order-creation-flow.puml, payment-processing-flow.puml).
A shared common.puml file with !include directives defining service aliases, skin params, and theme settings.
Folders grouped by domain: diagrams/orders/, diagrams/payments/, diagrams/notifications/.
A diagram index or README linking to each file with a one-line description.

Using !include keeps your diagrams consistent. You define colors, fonts, and participant aliases once:

@startuml
!include ./common.puml

actor Customer
participant API_Gateway
participant Order_Service
database Order_DB

Customer -> API_Gateway: POST /orders
API_Gateway -> Order_Service: CreateOrder(...)
Order_Service -> Order_DB: INSERT
Order_DB --> Order_Service: OK
Order_Service --> API_Gateway: 201
API_Gateway --> Customer: 201
@enduml

If you also need to document how these services deploy to cloud infrastructure, check out our PlantUML component diagram examples for cloud deployment, which pairs well with sequence diagrams at the architecture review level.

Can you show a saga pattern example with compensating transactions?

Distributed transactions across microservices often use choreography or orchestration sagas. Here's an orchestrated saga with rollback logic:

@startuml
participant "Order Orchestrator" as Orch
participant "Order Service" as Orders
participant "Payment Service" as Payment
participant "Inventory Service" as Inventory
participant "Shipping Service" as Shipping

Orch -> Orders: CreateOrder (PENDING)
Orders --> Orch: orderId: 1001

Orch -> Payment: Charge(cardToken, amount)
Payment --> Orch: Success (chargeId: ch-77)

Orch -> Inventory: ReserveStock(orderId=1001)
Inventory --> Orch: Success (reservationId: res-33)

Orch -> Shipping: ScheduleDelivery(orderId=1001)
activate Shipping
Shipping --> Orch: FAILURE (no carriers available)
deactivate Shipping

note over Orch: Saga compensation begins

Orch -> Inventory: CancelReservation(res-33)
Inventory --> Orch: Cancelled

Orch -> Payment: Refund(ch-77)
Payment --> Orch: Refunded

Orch -> Orders: UpdateStatus(CANCELLED)
Orders --> Orch: Done
@enduml

This makes the happy path and the rollback path visible in one diagram. Teams use this during design reviews to verify that every compensating action is accounted for.

What tips help keep these diagrams useful over time?

Version them with your code. Place .puml files in the same repository as the service they describe. A diagram that drifts from reality is worse than no diagram.
Generate images in CI. Use the PlantUML CLI or a GitHub Action to render SVG files on every commit. Link them from your documentation site.
Use meaningful participant names. "Order Service" is better than "os" or "Service A." Readability matters more than typing speed.
Add timestamps or version notes. A comment like ' Last updated: 2024-03-15, matches v2.1 of Order API saves future confusion.
Review diagrams in pull requests. Treat them like code. If someone changes a service contract, the diagram update should be in the same PR.

Quick checklist before sharing your microservices sequence diagram

Run through these before pushing a diagram to your repo:

Each participant maps to a real service, database, or external system
Sync calls use solid arrows, async calls use dashed arrows
Error paths and retries are shown with alt/else blocks
Activation boxes show when each service is processing
The diagram focuses on one flow not the entire system
File is included in the correct domain folder with a shared !include
A teammate can understand the flow without additional context

Start with one critical flow in your system the one that breaks most often or confuses new team members the most. Diagram that first. Once your team sees the value, the rest will follow naturally. For a broader view of diagram types and syntax, the official PlantUML sequence diagram documentation is a solid reference to keep bookmarked.