3.1 Sequence Diagrams

What are Sequence Diagrams?

  1. Explain purpose: interactions between actors/components.

  2. Show basic sequenceDiagram keyword.

  3. Participants and messages.

1. Explain Purpose: Interactions Between Actors/Components

While flowcharts are great for showing process steps and decisions, sometimes you need to focus on who is doing what — and in what order. That’s where sequence diagrams come in.

✅ What is a Sequence Diagram?

A sequence diagram shows how different actors or components interact over time to complete a specific task or process. It’s like watching a conversation unfold, step by step.

In software development, sequence diagrams are commonly used to:

  • Map out how users, services, and systems exchange information.

  • Visualize API calls, service requests, or message passing.

  • Clarify who starts an action and how other parts respond.

✅ Who are the Actors and Components?

  • Actors: Usually people or external systems — like a user, admin, or customer.

  • Components: Parts of your system — like a web app, backend server, database, or external API.

Each actor or component is shown as a participant in the diagram. Arrows between them represent messages, requests, or responses.

✅ Why Use Sequence Diagrams?

Sequence diagrams help you:

  • Understand how pieces of a system communicate.

  • Find gaps or misunderstandings in your process logic.

  • Share clear, step-by-step interactions with your team.

  • Document real-time flows like login processes, checkout systems, or API chains.

Example Use Case: Imagine a user logging in:

  • The User sends a login request to the Frontend.

  • The Frontend calls the Backend Auth Service.

  • The Auth Service checks the Database.

  • A response flows back through each step.

A sequence diagram maps each of these interactions in order, showing the entire communication chain at a glance.

In short:

📌 Sequence diagrams illustrate who talks to whom, when, and in what sequence — making complex interactions easy to understand and communicate.

2. Show Basic sequenceDiagram Keyword

Now that you know what sequence diagrams are for, let’s look at how to write one in Mermaid. The key to starting any sequence diagram is the sequenceDiagram keyword. This tells Mermaid, “Render the following lines as a sequence diagram, not a flowchart.”

✅ How to Start

A sequence diagram always begins with:

Below that, you define:

  • Participants (the actors or components in the interaction).

  • Messages (the arrows showing who sends what to whom).

✅ Basic Syntax Example

Here’s a simple example:

✅ What This Does

Breaking it down:

  • sequenceDiagram starts the diagram block.

  • participant declares each actor or component:

    • User

    • Frontend

    • Server

  • Arrows like User->>Frontend: Click Login show the message flow:

    • ->> means a message from one participant to another.

    • The text after the colon : is the message label that appears on the arrow.

✅ Arrow Types

For now, remember the basics:

  • ->> → solid arrow showing a request or action.

  • -->> → solid arrow with a dashed return, often used for responses.

These arrows show direction and sequence, so you see who initiates an action and who replies.

✅ When to Use

Use sequenceDiagram when you want to:

  • Show the order of messages.

  • Visualize real-time interactions, like API calls.

  • Document who initiates and who responds.

In short:

📌 sequenceDiagram is your keyword to switch from flowcharts to interaction flows — helping you describe who talks to whom, step by step.

3. Participants and Messages

Once you know how to start a sequenceDiagram, the next step is to understand its two core parts: participants and messages. Together, they describe who is involved in your process and how they interact step by step.

✅ What Are Participants?

Participants are the people, systems, or components that take part in the interaction. In a sequence diagram, each participant appears at the top of the diagram as a vertical lifeline.

You declare a participant with:

Example:

  • Each participant will appear in order, left to right, in the diagram.

  • The order you list them in your code determines how they are laid out.

✅ What Are Messages?

Messages are the arrows between participants that show who sends what to whom — and in what order. Each message describes an action, request, or response.

The basic format is:

  • ->> draws a solid arrow pointing right (or down the timeline).

  • The text after the colon : appears as the label on the arrow.

✅ Example: Participants + Messages

Here’s a simple login request:

What’s happening here:

  • User interacts with Frontend (clicks Login).

  • Frontend talks to Server (sends the credentials).

  • Server replies to Frontend (returns an authentication token).

  • Frontend tells User the result (shows success or failure).

✅ Tips for Good Participants and Messages

✔️ Keep names clear and simple — use User, API, DB, Payment Service, etc. ✔️ Use clear message labels — “Send Request”, “Return Data”, “Show Result”. ✔️ Keep the order logical — list participants in the order they naturally appear. ✔️ Use ->> for requests and -->> for responses — this keeps your diagram clear and consistent.

In short:

📌 Participants show who is involved. 📌 Messages show what happens between them, step by step. Together, they bring your sequence diagram to life.

PreviousCHAPTER 3Next3.2 Sequence Diagram Syntax

Last updated