Let's Create Sequence Diagram Using Mermaid

#Tools

A few years back, I shifted to remote work due to the pandemic. When I discussed some system workflows with teammates, I always used an online whiteboard to draw diagrams, thinking it would have the same result as the physical one. I was wrong, my mouse skills weren't good enough making it too hard to understand. 🤯

Then, I found Mermaid in a document written by a colleague. I was amazed at how easily we could turn code into diagrams. Since then, I've been using it every time I want to explain something as a diagram. It can help create many types of diagrams, but today I'll focus on the sequence diagram.

Let's briefly go over what the sequence diagram is...

It's a type of diagram that shows how actors or objects interact with each other in a time sequence. Umm... It might sound a bit too brief, but let's look at this example

I ask my brother to make me a coffee ☕

We can draw a simple sequence diagram like this

sequenceDiagram
    actor I
    actor My brother
    participant Coffee machine
    I->>My brother: Hey! Make me a coffee
    My brother->>Coffee machine: Walk to
    Coffee machine->>Coffee machine: Make a coffee
    Coffee machine->>My brother: Coffee's ready
    My brother->>I: Take coffee

In this diagram, my brother and I are the actors, and the coffee machine is an object. The line with an arrow shows the interaction between the actor and the object. It's easy to understand, right?

Why Mermaid?

As mentioned earlier, using a mouse to draw diagrams on an online whiteboard was too challenging. Even with other drag-and-drop tools, it can still be time-consuming.

Mermaid is a tool that helps generate diagrams using code-based input (diagram as code). Here's what the code looks like for the above diagram

123456789
sequenceDiagram
    actor I
    actor My brother
    participant Coffee machine
    I->>My brother: Hey! Make me a coffee
    My brother->>Coffee machine: Walk to
    Coffee machine->>Coffee machine: Make a coffee
    Coffee machine->>My brother: Coffee's ready
    My brother->>I: Take coffee

Tada! 🎉 I guess you can probably map each line of code to the diagram easily. But let's go through it together

  • I defined two actors (My brother and I) and a participant (or object), the coffee machine
  • The syntax of the lines below is in this pattern [origin][message][destination]: [message text]
    • The origin => What creates interaction
    • The destination => What receives the interaction
    • The message =>How they interact

Let's see another example, what if my brother isn't in the mood to help me make coffee?

sequenceDiagram
    actor I
    actor My brother
    participant Coffee machine
    I->>My brother: Hey! Make me a coffee
    alt He's in a good mood
    My brother->>Coffee machine: Walk to
    Coffee machine->>Coffee machine: Make a coffee
    Coffee machine->>My brother: Coffee's ready
    My brother->>I: Take coffee
    else
    My brother->>I: Make it yourself. I'm not your barista.
    end

We can also add the alternative (if/else) to our diagram, which is generated from the below code

12345678910111213
sequenceDiagram
    actor I
    actor My brother
    participant Coffee machine
    I->>My brother: Hey! Make me a coffee
    alt He's in a good mood
      My brother->>Coffee machine: Walk to
      Coffee machine->>Coffee machine: Make a coffee
      Coffee machine->>My brother: Coffee's ready
      My brother->>I: Take coffee
    else
      My brother->>I: Make it yourself. I'm not your barista.
    end

You can see more examples and syntax here

I want to use it now! Where can I use it!?

There are many ways we can use/embed the Mermaid, here are some of them

  1. Online editor - mermaid.live
  2. Install as a dependency - npm

I didn't lie to you. did I? It's really simple and quick. I hope Mermaid helps you the next time you need to create diagrams. See you in the next post! 👋🏻