Sequence Diagram Template

Use this template as a starting point for documenting runtime behavior.

When to Use Sequence Diagrams

Rule of thumb: Create a sequence diagram when a flow involves 3+ actors or has non-trivial error handling.

Good candidates:

• Multi-step handshakes across components/services
• Flows with retries, fallbacks, or timeouts
• Async operations with callbacks
• Workflows with significant side effects

Mermaid Example

sequenceDiagram
  autonumber
  actor U as 👤 User
  participant W as 🌐 Website
  participant H as ☁️ CDN

  U->>W: Request page
  activate W
  W->>H: Fetch static assets
  activate H
  H-->>W: Assets (HTML, CSS, JS)
  deactivate H
  W-->>U: Rendered page
  deactivate W

With Error Handling

sequenceDiagram
  autonumber
  actor U as 👤 User
  participant W as 🌐 Website
  participant H as ☁️ CDN

  U->>W: Request page
  activate W
  W->>H: Fetch static assets
  activate H
  
  alt Success
    H-->>W: Assets
    W-->>U: Rendered page
  else CDN Timeout
    H--xW: Timeout (5s)
    W->>W: Serve cached fallback
    W-->>U: Cached page + warning
  else CDN Error
    H-->>W: 500 Error
    W-->>U: Error page
  end
  
  deactivate H
  deactivate W

PlantUML Example

@startuml
skinparam style strictuml

actor User
participant Website
participant CDN

autonumber

User -> Website : Request page
activate Website

Website -> CDN : Fetch assets
activate CDN

alt Success
  CDN --> Website : Assets
  Website --> User : Rendered page
else Timeout
  CDN --> Website : Timeout
  Website --> User : Cached page
end

deactivate CDN
deactivate Website

@enduml

Syntax Quick Reference

Arrow Types (Mermaid)

Blocks

Checklist

Before finalizing your diagram:

• Participants named consistently — Use the same names as in code/architecture docs
• All paths shown — Happy path, error paths, edge cases
• Error handling explicit — Timeouts, retries, fallbacks
• Async behavior clear — Distinguish sync vs async calls
• Side effects noted — Database writes, external calls, events
• Numbered steps — Use autonumber for easier reference
• Activation bars — Show when participants are “working”

Best Practices

1. Start simple — Add complexity only as needed
2. One diagram per flow — Don’t cram multiple scenarios together
3. Link to code — Reference the implementing function/handler
4. Keep it current — Update when behavior changes
5. Add notes — Explain non-obvious decisions inline