Within your team, do you usually document the workflows of your apps? Have you ever felt lost when trying to understand how they work? Calm down, it has happened to all of us and it is totally normal, when our application gets bigger it usually becomes more complex and we can forget some internal or external interaction with another application. To solve this, we can use a tool to visualize those flows.

What is Mermaid

Mermaid is a tool, built with Javascript, that allows us to create diagrams and graphs from code. Markdown. It is a perfect tool to complete our README with complete and easy-to-edit flowcharts.

We are talking about creating flows, but with Mermaid we can also create database schemas, state machines, OOP schemas or even temporary graphs to manage projects.

How to use Mermaid

For those who have written Markdown, If you are using Mermaid, using Mermaid is going to be very easy. To test, we can use the editor that we have available from its web.

The first line we have to write defines the type of graph we are going to implement. If we want to draw a flowchart, we have to write flowchart TD. We can also use sequence diagrams, class diagrams, state diagrams or state machines, Entity-Relationship, Gantt and even Git graphs. There is an example of each in the online editor so we can start testing.

Creating our first example

Let's take for example a case in which our application consists of a frontend, where our user is going to register, and then edit his profile, add medical information that will have to be validated with another external application.

sequenceDiagram
    Frontend->>>+Backend: User send email and password
    Backend->>>Frontend: Login, send token
    Frontend->>>Backend: Edit medical information
    Backend->>>+External Medical Application: Send user data
    External Medical Application->>>Backend: Confirm data
    Backend->>>Frontend: Confirm data editing

As we can see, the whole graphic has been developed with code Markdown. To declare an entity within this flow we only have to write its name, and add a + if it is the first time we send a flow. We don't have to worry about the arrows, Mermaid takes care of knowing where they have to point.

We can do something more complex. For example, an application where we are going to describe internal flows using asynchrony or simply specifying that internal processing is occurring with processes in other threads.

sequenceDiagram
    participant b as Bank
    participant m as Microservice
    participant mobile as Mobile App
    participant u as User

    u->>>mobile: Pay by internet
    mobile->>>m: Create payment order
    activate m
    m->>>m: Scheduler to check payments
    deactivate m
    m->>>b: Send payment data
    activate b
    b->>>b: Make payment
    b->>>m: Payment confirmed
    deactivate b
    m->>>mobile: Send push
    mobile->>>u: Read push

In this example, we have chosen to declare the participants and the actor at the top, using an alias. Internally we will refer to them as b, m, mobile o u, but the complete names (Bank, Microservice, Mobile App and User) will appear in the chart.

We can see that we have introduced activate m y deactivate m sandwiching another instruction. With this, Mermaid will create a little bar indicating that something is being processed in that interval but we have also added a stream to itself to specify that it is executing.

Here we leave you the documentation in case you want to review it.

More types of graphics

Entity - Relationship

erDiagram
    USER {
        string id PK
        string email
        string birth_date
        string first_name
        string last_name
    }

    USER ||...|{ ORDER: has

    ORDER {
        string user_id FK, PK
        string reference PK
        string order_date
        float price
        string address
    }

    USER ||..|{ BANK DATA: has
    
    BANK_DATA {
        string id PK
        string user_id FK
        string account_number
    }

Here we can see how to create an Entity-Relationship diagram and we can also specify the different types of relationships (O-N, 1-1, 0-N, 1-N) as well as the keys that are primary (PK) or foreign (FK). Here its documentation: http://mermaid.js.org/syntax/entityRelationshipDiagram.html

State diagram

A simple example to renew the DNI:

flowchart TD
    A[Renew ID] --> B{It's expired}
    B -->|Yes| D[Appointment] --> B -->|No| E[Renew from web] --> B -->|No| E[Renew from web] --> B
    B -->|No| E[Renew from web] --> E --> F --> F
    E --> F
    D --> F[DNI renewed] D --> F

Here the most interesting thing is how to create a decision node to branch the graphs, in this case it is done by enclosing between braces ({}) the text describing a node.

Documentation of flowcharts: http://mermaid.js.org/syntax/stateDiagram.html

Conclusions

As you may have noticed, it is very easy to make complete graphs to be able to document our flows in the README of our projects. From here we encourage you to use them, sure that in the long run it is a decision that you will end up appreciating.