How to create a sequence diagram from verified interactions
Turn one bounded scenario into ordered participants and messages, use branches only when the source supports them, and review the diagram against contracts and traces.
Start with one named scenario and its verified source, place participants from left to right, then write messages from top to bottom in the order the scenario requires. Distinguish calls, asynchronous signals and returns without treating their arrow style as runtime proof. Add alternatives, loops or parallel fragments only when the contract explicitly supports them, and version the finished diagram after comparing it with current API or event documentation and an authorized trace.
Bound one scenario and name the evidence
Choose one concrete path such as an order-status lookup, payment rejection or background retry. State whether the diagram is intended behavior, a design proposal or a reconstruction of an observed event. Keep success, error and retry paths separate until each can be read without guessing.
- Write a scenario title that names the trigger and outcome.
- Identify the contract, requirement, trace or interview that supports it.
- Choose one start event and one stopping point.
- Remove unrelated setup and downstream work.
Place participants in a stable left-to-right order
List every person, interface, service, queue or datastore that sends or receives a message in this scenario. Put the initiating actor first, then follow the main direction of the interaction. Use short stable identifiers with descriptive aliases; Mermaid renders explicitly declared participants in source order.
Write messages from top to bottom
Create one line for each meaningful interaction and name it with an action plus the important object. A solid request arrow can express a declared call, an open arrow an asynchronous signal and a dotted arrow a declared return. Those notations communicate the model you supplied; they do not establish blocking behavior, delivery, elapsed time or success.
Add control fragments only when the source requires them
Use an alternative fragment for mutually exclusive paths, an optional fragment for a conditional path without an else branch, a loop for bounded repetition and a parallel fragment for explicitly concurrent paths. If the evidence does not specify the condition, retry limit or concurrency relationship, keep it out of the diagram and record it as an open question.
Review the artifact against contracts and traces
Compare participant names and messages with current API, event and service contracts, then inspect authorized observability data separately. OpenTelemetry describes a trace as the path of a request through an application, composed of spans with runtime context; that evidence can reveal actual timing, status, parent-child relationships and missing calls that an authored diagram cannot. Record the reviewed version and update date beside the artifact.
Check the primary references
Check the source against the result
Scenario: a customer asks a web app for an order status. The web app calls the Orders API, the API returns the current status, and the web app presents it to the customer. Declared order: Customer → Web app → Orders API → Web app → Customer.
Mermaid source: sequenceDiagram; autonumber; actor p1 as Customer; participant p2 as Web app; participant p3 as Orders API; p1->>p2: Request order status; p2->>p3: GET /orders/{orderId}; p3-->>p2: 200 order status; p2-->>p1: Show current status.
The four arrows preserve the supplied order and both returns have an earlier opposite-direction request. They do not prove that the endpoint exists, that either call was synchronous in production, that the response took a particular time, that the status was delivered successfully or that concurrent work did not occur. Reconcile the artifact with the current contract and an authorized trace before making runtime claims.
Turn an ordered interaction manifest into editable structure
Declare the participants and message kinds, inspect unmatched returns, preview an accessible SVG and download the Mermaid source without sending the manifest to a server.
Open Sequence Diagram Generator