Text Based Charts with Mermaid.JS

Mermaid.JS – https://mermaid-js.github.io/

Mermaid is a charting a diagram and charting tool that I’ve been using on projects this year. It’s effectively a Markdown add-in library which means it generates diagrams based on simple text files. This has been very powerful for me because I often get tripped up in the context-switching that it takes to document a back-end system: building out API calls in Visual Studio or Postman, reviewing responses against sample data, making adjustments to the call, then writing up the details, etc. With Mermaid I also don’t have to remember how to build out specific sections and can instead focus on a simpler grammar – instead of dragging around little lines and arrows I can rapidly type out a chart as I’m working.

The library is generally built as a JS library for HTML files but various editors have plug-ins available as well. I’ve been using “Markdown Preview Mermaid Support” and “Markdown PDF” for Visual Studio Code to preview in realtime and then export charts as PDF, HTML, or images.

A simple example would be the login sequence for a recent project:

Login

```mermaid
sequenceDiagram
participant G as Guest User
participant E as Ecommerce Website
participant A as ERP API

activate G

G->>E: Enter username, password on login screen
E->>+A: CustomerWebService/GetHashInfo(Email Address)
A-->>-E: Salt, Version

activate E
alt Hash Version 1
E->>E: Calculate PBKDF2 hash of password
else Hash Version 2
E->>E: Calculate scrypthash of salt + password
end

E->>+A: CustomerWebService/Auth(Email Address, Hash)
deactivate E
A-->>-E: Return AuthResponse

activate E
alt User Data Returned
E-->>G: Redirect as logged in user
else Exception (User not found)
E-->>G: Display error
end

deactivate E
deactivate G

Already you should be able to see the general direction of the chart, though some sections aren’t easy to visualize as-is. When rendered out with the editor the following chart is created:

It is admittedly not exactly as pretty as something hand-built in Visio or Draw.io/Digrams.net but I think the ease of use is a worthwhile tradeoff. And if something a little easier on the eyes did need to be created this chart would be a fantastic starting poitn.

The text-based nature of the chart also lends itself to easy changes. For example, I built out most of this before I had the hash details from the client. Instead of leaving room or dragging things around for the hash information, I was able to just add in that alt block afterwards with zero cleanup work.

As another example, the registration sequence in a recent project involved a password reset for certain situations. By the time I got around to documenting the Password Reset flow, I realized I could just cut and paste the chart from the registration documentation. Again, zero graphical clean up because the text file still made logical sense which allowed the library to adjust the chart on the fly.

I’m currently exporting images and storing them in our project wiki but these Markdown files could also be stored as live documentation in a source code repository. In fact, people have created build pipelines that generate charts from git repos to be used directly in websites. All in though, even without any special automation, Mermaid.js has helped me rapidly create and update project documentation without the overhead of jumping between tools.