A sequence diagram shows the conversation between people and systems over time: who asks whom for what, and what comes back. It's the go-to picture for explaining sign-in flows, payments, webhooks and anything else that crosses system boundaries.

How to read a sequence diagram

  • Participants sit across the top: a user, an app, an API, a payment provider.
  • Lifelines run down from each participant, showing time passing.
  • Messages are arrows between lifelines, read from top to bottom. A solid arrow is a request; a dashed arrow is usually a reply.

If you read the arrows in order, you get the whole story of the interaction.

When to use one

  • explaining how sign-in, single sign-on or token refresh works
  • designing an integration with another company's API
  • debugging: drawing what actually happened next to what should have happened
  • reviewing a design, where the order of calls matters

If you only need to show which systems exist and how they connect, an architecture diagram is simpler.

How to make a sequence diagram

1. Choose the scenario

Pick one path, such as "A returning user signs in". Edge cases can get their own diagrams.

2. List the participants

Order them left to right in the order they first take part. Fewer is better.

3. Write the messages in order

Each message is a short verb phrase: "Sign in", "Check password", "Token". Add replies where the answer matters.

4. Check every request has an answer

Unanswered requests are often where the bugs hide.

An example you can type

In Nodeslate, A -> B: message sends, B --> A: reply answers, and participants appear as you name them:

App -> Auth: Sign in
Auth -> Database: Check password
Database --> Auth: OK
Auth --> App: Token

-> C: text carries on from the last participant, and you can click any message to edit or reorder it. The Sign in with a token template is a good starting point.

Try it on the canvasNo account needed.

Tips

  • Name participants the way your team does. "Auth service", not "AuthSvcV2Impl".
  • Keep messages short. Details belong in the docs the diagram links to.
  • Show the reply when it carries information. A token, an error, a status.

Questions

Is a sequence diagram part of UML?

Yes, it comes from UML, but you don't need to know UML to read or draw one. The basic arrows cover most real needs.

Can I keep sequence diagrams in my docs as text?

Yes. Nodeslate can copy a sequence diagram as Mermaid, which renders in GitHub, GitLab and many wikis, and can import Mermaid sequence diagrams too.

Keep reading