1---2name: sequence-diagram3description: Choose a sequence diagram when the user needs to explain ordered messages, calls, responses, or time-dependent collaboration between participants.4---56# Sequence diagram78## What and why910A sequence diagram tells a time-ordered interaction story. It is strongest for an API request, authentication exchange, event flow, incident trace, or one scenario across services and people. It is not a deployment map, class structure, or a complete behavioral specification.1112## Model it13141. Name the scenario and trigger, including success or failure scope.152. Choose participants that send, receive, or transform a message; omit passive infrastructure.163. Order messages top-to-bottom and label intent, not implementation trivia.174. Use activation, return, loop, alternative, optional, and parallel fragments only when they clarify behavior.185. Mark asynchronous messages, timeouts, retries, and external boundaries explicitly.1920UML 2.5.1 defines interaction and combined-fragment semantics. See [UML interaction guidance](references/uml-interactions.md).2122## Story and styling2324Make the primary path easy to scan, then place alternatives in `alt`/`opt` regions. Use participant types consistently and distinguish synchronous calls from asynchronous signals. Keep lifelines aligned; use restrained color for external systems, errors, or trust boundaries. Never encode meaning by color alone.2526## Renderer routing2728Prefer `mermaid` for lightweight docs, `plantuml` for expressive UML fragments, `seqdiag` for compact message-focused diagrams, or `d2` when the sequence is part of a broader technical illustration. Preserve the user's renderer choice. `bpmn` is appropriate only when the requested story is a formal business process with BPMN events, tasks, and message flows.2930## Review3132- Is the scenario boundary and trigger explicit?33- Does vertical order represent time without implying false duration?34- Are request/response direction, async behavior, errors, and retries unambiguous?35- Are fragments labeled with meaningful guards?36- Is the diagram readable without relying on tiny labels or color alone?3738## Limits and opportunities3940diagram.zip renders sequence sources but does not execute a UML interaction validator or check trace completeness. A future integration could validate UML fragment nesting and provide conformance diagnostics.