Sequence diagram tool

It is the fastest way to settle an argument about what calls what, and the fastest way to spot a round trip nobody needed.

Where a sequence diagram helps

• Designing an API interaction before you build it
• Explaining an authentication or payment flow
• Debugging by drawing what you believe happens, then checking it
• Documenting an integration between two systems

Drawing the lifelines and messages

1. Open the template, which has a browser, an API and a database with messages between them.
2. Rename each participant box along the top.
3. Add a participant by copying a box and dragging a dashed lifeline down from it.
4. Draw a message as a straight connector from one lifeline to another and label it.
5. Use a dashed connector for a return, which is the convention readers expect.
6. Keep messages in strict top-to-bottom order, because that is the whole point of the diagram.

Conventions worth following

Time only goes down

Never draw a message going upwards. If you need to, the participants are in the wrong order.

Solid out, dashed back

A solid arrow is a call, a dashed one is the response. Readers rely on this without thinking about it.

Name the message, not the intention

GET /orders tells a reader more than “fetch the data”.

A self-call loops back

Draw a short connector from a lifeline to itself for work a participant does on its own.

A worked example: signing in

Four lifelines, left to right: the User, the Browser, the Server and the Database. The user submits a form; the browser sends the email and password to the server; the server asks the database for the account; the database returns it; the server checks the password and sends back a session; the browser shows the dashboard.

Drawn as a sequence, the order of those six messages is obvious, and so is the question the diagram forces: what happens when the password is wrong? Adding that as an alternative fragment, a boxed section labelled with the condition, is usually where a team discovers the part of the flow nobody had specified.

Sequence diagram questions