Sequence Diagram Design

Sequence diagrams show the interaction between components over time — who calls whom, in what order, and what data flows between them. They are the most effective diagram type for documenting API workflows, debugging integration issues, and communicating complex multi-service interactions. A well-designed sequence diagram shows the flow so clearly that the reader can predict what happens when a step fails.

1. Participants and Lifelines List participants left to right in the order they are first called. Label each with its name and type: "Order API (service)," "Payment Gateway (external)," "Order DB (PostgreSQL)." The left-to-right ordering creates a natural reading flow that follows the request path.
2. Messages and Responses Solid arrows for synchronous calls: "POST /payments { amount: $42 }". Dashed arrows for responses: "201 Created { id: pay-123 }". Open arrowheads for asynchronous messages: "OrderPlaced event → message broker." Label every arrow with the operation, the data shape, or the event name. Unlabeled arrows force the reader to guess.
3. Error Paths Show the error path as an alternative fragment. "alt [payment declined]" branches the sequence to show the compensation flow. Error paths in sequence diagrams are where the architectural decisions live — the happy path is straightforward, but the error handling reveals the resilience design. Document at least one error path per sequence diagram.