MermaidJS for Diagrams

I’ve discovered a really easy way for writing diagrams - MermaidJS. I’ve found it to be a handy way for easily diagramming workflows, or when planning out new architecture for projects.

Here’s some examples of little ways you can use it easily.

Example 1: Sequence Diagram

My first example is how a customer would buy tickets for an event.

We want to represent the actions the customer takes when purchasing a ticket. We know the following steps will happen in the journey:

1. The user starts the process by visiting the website.
2. They browse events, choose a ticket type, and add it to their cart.
3. The website handles the user’s shopping cart in the background.
4. The user proceeds to checkout, filling in their billing info.
5. The website processes the payment through a payment gateway.
6. The payment gateway quickly confirms the payment.
7. The website generates and presents the user’s ticket.
8. The user happily receives their ticket while the cart is cleared.
9. The cart sends a friendly ticket receipt to the user’s email.

To then map this out in Mermaid, we can set up a series of actors (each listed as a participant) and then map out the journeys. See the following Mermaid code, and below the resulting diagram:

sequenceDiagram
  participant User
  participant Website
  participant Cart
  participant PaymentGateway
  
  User->>Website: Selects Event
  User->>Website: Chooses Ticket Type
  User->>Website: Adds to Cart
  Website->>Cart: Add Ticket
  User->>Website: Proceeds to Checkout
  Website->>Cart: Review Cart
  User->>Website: Provides Billing Info
  Website->>PaymentGateway: Process Payment
  PaymentGateway->>Website: Payment Confirmation
  Website->>User: Receives Ticket
  Website->>Cart: Empty Cart
  Cart->>User: Ticket Receipt

sequenceDiagram
  participant User
  participant Website
  participant Cart
  participant PaymentGateway
  
  User->>Website: Selects Event
  User->>Website: Chooses Ticket Type
  User->>Website: Adds to Cart
  Website->>Cart: Add Ticket
  User->>Website: Proceeds to Checkout
  Website->>Cart: Review Cart
  User->>Website: Provides Billing Info
  Website->>PaymentGateway: Process Payment
  PaymentGateway->>Website: Payment Confirmation
  Website->>User: Receives Ticket
  Website->>Cart: Empty Cart
  Cart->>User: Ticket Receipt

For more on Sequence Diagrams, refer to the MermaidJS Sequence Diagram documentation.

Example 2: Class Diagrams

Although I have not seen UML diagrams at any place I’ve worked, back at university it was a great way to visualise how classes fit together. I wanted to show how this can be a benefit, as I’ve previously written about this and how planning out a system with UML can help identify any shortcomings when working within Domain Driven Design.

Take a simple payment system for example. You know it requires the ability to process payments, as well as refund and verify them. You might also want to generate invoices for them. As part of this, you know you’ll have users and you’ll want to interact with a payment gateway. You can easily map this out as a class diagram using the following:

classDiagram
  class PaymentSystem {
    +processPayment()
    +refundPayment()
    +verifyPayment()
    +generateInvoice()
  }

  class PaymentGateway {
    +authorizePayment()
    +capturePayment()
    +voidPayment()
    +processRefund()
  }

  class User {
    -name: String
    -email: String
    +makePayment()
    +requestRefund()
  }

  PaymentSystem --|> PaymentGateway : uses
  User --|> PaymentSystem : interacts with

This will output a diagram as follows:

classDiagram
  class PaymentSystem {
    +processPayment()
    +refundPayment()
    +verifyPayment()
    +generateInvoice()
  }

  class PaymentGateway {
    +authorizePayment()
    +capturePayment()
    +voidPayment()
    +processRefund()
  }

  class User {
    -name: String
    -email: String
    +makePayment()
    +requestRefund()
  }

  PaymentSystem --|> PaymentGateway : uses
  User --|> PaymentSystem : interacts with

In this example:

• PaymentSystem is a class that represents the main payment system and includes methods like processing payments, refunding payments, verifying payments, and generating invoices.
• PaymentGateway is a class that represents a payment gateway responsible for authorizing and processing payments, voiding payments, and handling refunds. The PaymentSystem will use the PaymentGateway to perform these tasks.
• User is a class representing users of the payment system. It has properties like name and email and methods for making payments and requesting refunds. Users interact with the PaymentSystem.

By mapping it out in this way, a developer should be able to take this away and work off of it with ease.

For more on Class Diagrams, refer to the MermaidJS Class Diagram documentation.

Example 3: A Pie Chart

MermaidJS doesn’t just handle diagrams - there are some charts you can generate as well. I’ve used pie charts in the past for various reports, but you could just as easily use it within a website for displaying data fetched from an API endpoint.

In this example, we’ll pretend I am representing the latest work my team has been involved with over the last quarter. You can easily fill in the latest data (say number of tickets worked on as well as a classification of the type of ticket) as follows:

pie showData
    title Quarterly Ticket Work Report
    "New Features" : 20
    "Defects" : 7
    "Tech Debt" : 12

This will easily generate a pie chart representation of that data:

pie showData
    title Quarterly Ticket Work Report
    "New Features" : 20
    "Defects" : 7
    "Tech Debt" : 12

This would most likely be best used with the MermaidJS API, which lets you embed it on pages.

For more on Pie Charts, refer to the MermaidJS Pie Chart documentation.

Conclusion

Hopefully by reading this post you will see how easy it is to incorporate diagrams into your own documentation. With Github supporting MermaidJS now, it is an easy way to keep living diagrams close to your codebase to ensure as you build your applications, your diagrams evolve with it. It also offers the benefit of being able to see previous iterations of your diagrams and see how things have evolved over time.