Sequence Diagram

Sequence Diagram

Visualize interactions and message flows between components over time.

Context

You are creating sequence diagrams to explain how components interact. Show request/response patterns, timing, error handling. Read flow requirements and interaction sequences.

Domain Context

Based on UML sequence diagrams and flow documentation:

• Synchronous Flow: Client calls service, waits for response. Simple, but blocking.
• Asynchronous Flow: Client sends message, continues without waiting. Service processes later, responds via callback/event.
• Error Handling: Happy path and error paths. Timeouts, retries, circuit breakers.
• Sequence: Order of interactions matters. Some flows have dependencies (A before B before C).

Instructions

1. Identify Actors: Services, external systems, users involved. List vertically on left.

1. Draw Time Axis: Vertical axis = time (top to bottom = early to late).

1. Draw Interactions:

• Solid arrow = synchronous request (waits for response)
• Dashed arrow = asynchronous message (fire-and-forget)
• Label arrow with message name and data

1. Example: Order Processing:

`` Customer → API: POST /orders (order_id, items) API → Database: INSERT order (async) API → Payment Service: Charge card (sync) Payment Service → Stripe: POST /charges Stripe → Payment Service: 200 OK Payment Service → API: 200 OK API → Customer: 200 OK (order_id) Database → Event Service: order.created event (async) Event Service → Email Service: Send confirmation ``

1. Add Alternatives: Show error cases. "If payment fails, rollback order. If timeout, retry with exponential backoff."

Anti-Patterns

• Too Complex Diagram: Show 20 interactions. Result: unreadable. Guard: Focus on one flow; use multiple diagrams for different scenarios.
• Only Happy Path: Never show errors or timeouts. Result: incomplete understanding. Guard: Include error cases, retries, timeouts.
• No Timing Information: Arrows all look the same. Result: unclear latency impact. Guard: Label latency-critical interactions; note timeouts.
• Outdated Sequence: Flow changed (new retry logic, new service), diagram not updated. Result: wrong mental model. Guard: Update when flow changes; document in comments.

Further Reading

• UML 2 Sequence Diagrams — formal sequence diagram syntax
• Enterprise Integration Patterns by Gregor Hohpe — message flow patterns
• Documenting Software Architecture — flow visualization best practices

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: sethdford
• Source: sethdford/claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.