For a complete breakdown of message types and when to use each one, check our guide on UML sequence diagram message types and notation.

What does a real-world architecture scenario look like?

Let's model something more involved an e-commerce checkout that calls a payment gateway, sends a confirmation email, and updates inventory:

sequenceDiagram
 actor Customer
 participant WebApp
 participant OrderService
 participant PaymentGateway
 participant InventoryService
 participant EmailService
 participant Database

 Customer->>WebApp: Click "Place Order"
 WebApp->>OrderService: POST /orders

 OrderService->>PaymentGateway: Charge card
 PaymentGateway-->>OrderService: Payment confirmed

 OrderService->>InventoryService: Reserve items
 InventoryService->>Database: Decrement stock
 Database-->>InventoryService: Stock updated
 InventoryService-->>OrderService: Items reserved

 par Send email and update order
 OrderService->>EmailService: Send confirmation
 OrderService->>Database: Update order status
 end

 OrderService-->>WebApp: Order complete
 WebApp-->>Customer: Confirmation page

Notice the par fragment it shows two operations happening in parallel. This kind of detail matters in architecture discussions because it surfaces concurrency assumptions your team might disagree on.

How do you show conditional logic and loops in sequence diagrams?

Most real flows aren't linear. You'll need fragments to represent branching and repetition.

Conditional flows with alt

sequenceDiagram
 participant Client
 participant API
 participant Cache
 participant Database

 Client->>API: GET /products/42
 API->>Cache: Check cache

 alt Cache hit
 Cache-->>API: Cached data
 API-->>Client: 200 OK (from cache)
 else Cache miss
 Cache-->>API: Not found
 API->>Database: Query product
 Database-->>API: Product data
 API->>Cache: Store in cache
 API-->>Client: 200 OK (from DB)
 end

Loops with loop

sequenceDiagram
 participant Scheduler
 participant Worker
 participant Queue

 Scheduler->>Queue: Fetch next batch
 Queue-->>Scheduler: 10 tasks

 loop For each task
 Scheduler->>Worker: Process task
 Worker-->>Scheduler: Task complete
 end

 Scheduler->>Scheduler: Wait for next interval

There are additional fragment types like opt (optional), break (interrupt), and critical (atomic sections). Our Mermaid sequence diagram cheatsheet has quick-reference examples for all of them.

When should you create a sequence diagram in your workflow?

You don't need sequence diagrams for every feature. Use them when:

• Designing cross-service interactions. Before building a new microservice flow, diagram the message exchange to catch misunderstandings between teams.
• Documenting existing systems. If you're onboarding someone to a legacy system, a sequence diagram explains the call chain faster than reading through controllers and services.
• Reviewing architecture decisions. Use diagrams in design reviews. They force you to be specific about who calls what and in what order.
• Debugging complex flows. When a bug spans multiple services, drawing the expected sequence helps you find where reality diverges.
• Writing technical documentation. API docs with sequence diagrams reduce support questions because developers can see the full request lifecycle.

What mistakes do people make with sequence diagrams?

Here are common pitfalls that make diagrams less useful:

1. Too many participants. If your diagram has 12 lifelines, nobody will read it. Split it into focused sub-flows. One diagram per scenario.
2. Mixing abstraction levels. Don't show high-level service calls on one line and internal method calls on the next. Pick a level and stay consistent.
3. Leaving out error paths. Happy-path-only diagrams give a false sense of simplicity. Show at least the most common failure scenario.
4. No return messages. Arrows that go one way without responses leave readers guessing about what comes back. Show the return unless it's truly fire-and-forget.
5. Overusing notes as a crutch. If a note is required to explain a message, the message label itself might be unclear. Rewrite it.
6. Forgetting the time axis. Sequence diagrams read top to bottom in time order. Don't arrange lifelines to make the layout pretty at the cost of confusing the temporal flow.

How do you keep sequence diagrams maintainable as your system grows?

A few practices help diagrams stay useful over months and years:

• Store diagram source files next to the code they describe. When the code changes, the diagram is right there to update.
• Name files by feature or flow, not by date or ticket number. checkout-flow.md beats diagram-v3-final.md.
• Use consistent participant aliases. If your API gateway is "APIGateway" in one diagram, don't call it "Gateway" or "api-gw" in another.
• Link diagrams from your README or architecture docs. Diagrams nobody finds are diagrams nobody uses.
• Review diagrams during code reviews when the interaction pattern changes. Treat them as living documentation.

Quick-reference checklist for writing sequence diagram code

• Identify the specific scenario or use case you're modeling
• List only the participants involved in that scenario
• Define your participant aliases consistently
• Map messages in chronological order from top to bottom
• Use correct arrow types: ->> for synchronous, -->> for asynchronous, dashed for returns
• Add fragments (alt, loop, opt, par) only when they add clarity
• Include at least one error or alternative path
• Show return messages for every request that expects a response
• Keep it under 10-12 participants per diagram
• Save the source file in version control alongside related code
• Preview the rendered output before committing
• Add a one-line description above the diagram explaining what scenario it covers