DEV Community

Cover image for How I learned to Relax and Embrace Swim Lane Flowcharts in Mermaid
Daniel R. Przybylski
Daniel R. Przybylski

Posted on • Updated on

How I learned to Relax and Embrace Swim Lane Flowcharts in Mermaid

Swim lanes, Mermaid? See what I did there?

The more ubiquitous something is in software development, the more arcane it seems to be. We see this illustrated perfectly with Git: it's command line interface is used across many different operating systems and development environments as well as hosting platforms, but I so often have to look up how to perform an operation in the CLI if it's not one of the basic commit, push, pull, merge or branch operations or not wrapped by the IDE or Git GUI program that I'm using at the time.

Markdown is another example. It needs to be text based and not dependent on any other language, but it needs to recognize other languages' syntaxes, It's not HTML but it can embed some HTML, and it also embeds other websites' entities like Twitter and Github.

We all know that Markdown can transform text containing certain characters and arrangements so it looks like a table, and it can present code blocks in a format that look like that particular code's language. Mermaid is similar to how those features work, but it's a bit smarter, and it requires its own syntax that is neither necessarily an analog of a what it is showing nor similar to a familiar programming language.

Not another mark-up language?!

Yes, it's basically another, but compact, mark-up language. However, we're not here to talk about the syntax or features of Mermaid. We're here to consider a process that can make utilizing the subgraph feature to create the look and feel of swim lanes so that if you're like me, you don't get bogged down trying to compile Mermaid in your head while you should really be thinking of the process flow that you're trying to document.

Let's talk flowcharts

I've been using flow charts for so long that I first created them in engineering notebooks (that's something made of paper), and I had a metal flowchart shape template so I could draw those shapes neatly. Now we use LucidChart, Visio and in Markdown, we use Mermaid. With enterprise systems, the swim lane flowchart is particularly useful showing which system is doing the work or decision making before it gets sent to a different system or possibly kicked back because of an error situation.

So what should we do?

First, don't be afraid to sketch it out on paper. From that, identify your systems: the lanes, then identify your operations: the shapes and their contained text. Most importantly, don't worry about the decision flow for now!

Swim lanes

mermaid
    graph LR;
    subgraph ERP

    end
    subgraph CreditService

    end
    subgraph Middleware

    end
    subgraph POS

    end
Enter fullscreen mode Exit fullscreen mode

Here, I've created a single graph with four swim lanes: POS, Middleware, CreditService and ERP.

If what is happening in the above code block isn't obvious, then you're not ready for this article. Look at the references down below to learn the basics like I did first.

I have my main graph going left to right and my swim lanes which are represented as subgraphs are coded in reverse: i.e. the POS lane will appear at the top while the ERP will appear at the bottom.

You need to put this code into a Markdown editor like Github capable of presenting Mermaid. You will naturally have to precede the mermaid keyword with the three back-ticks and close it at the bottom as well. I don't know how to escape that here in the dev.to environment.

You should see:
Subgraphs as Swim Lanes

Operations

In this example, there is an online point-of-sale (POS) system. The customer places an order and then custom middleware sends that order to a credit handling service. This is a service which checks to see that the customer is doing okay financially without actually processing any currency like your credit cards do. If the credit check is okay, the order is placed, but if the credit check is not okay, then we let the customer know. Those operations (not the flow) manifest as this:

mermaid
graph LR;
    erporder[POST order]
    creditcheck{credit good?}
    creditquery[query credit service]
    posplaceorder[customer places order]
    posinformcustomer[Inform customer]
Enter fullscreen mode Exit fullscreen mode

Again, check these operations alone in a Mermaid-capable editor. You want to make sure that these entities are working before the next step...

Atomic operations

Place operations in lanes

Now we want to merge these two sets of entities, but keep in mind that we still aren't worried about flow. We just want to make sure that our operations are in their appropriate swim lane:

mermaid
graph LR;
    subgraph ERP
    erporder[POST order]
    end
    subgraph CreditService
    creditcheck{credit good?}
    end
    subgraph Middleware
    creditquery[query credit service]
    end
    subgraph POS
    posplaceorder[customer places order]
    posinformcustomer[Inform customer]
    end
Enter fullscreen mode Exit fullscreen mode

Notice, that we have the operation declarations each placed in their lane. The POS has two operations it is responsible for performing.

Yes, please check it before the next step.

Stay in your lane!

Lastly, we add the process flow

mermaid
graph LR;
    subgraph ERP
    erporder[POST order]
    end
    subgraph CreditService
    creditcheck{credit good?}--yes-->erporder
    end
    subgraph Middleware
    creditquery[query CIT]-->creditcheck
    end
    subgraph POS
    posplaceorder[customer places order]--webhook-->creditquery
    citcreditcheck--no-->posinformcustomer[Inform customer]
    end
Enter fullscreen mode Exit fullscreen mode

First, let's review:

  • There is an online point-of-sale (POS) system.
  • The customer places an order
  • Then custom middleware sends that order to a credit handling service.
    • This is a service which checks to see that the customer is doing okay financially without actually processing any currency like your credit cards do.
  • If the credit check is okay, the order is placed,
  • but if the credit check is not okay, then we let the customer know.

How do we do it?

  • The customer places an order

So we start by putting the flow line from posplaceorder declaration to the creditquery reference that I added in the POS subgraph. Note the creditquery is still declared with its display text in the CreditService subgraph, I'm just referencing it in the POS subgraph to show the connection. And in this case, I added the webhook text to the flow line to indicate that I would like to trigger this with a webhook.

  • Then custom middleware sends that order to a credit handling service.

It's my middleware that links the POS to the credit service, so the flow line is placed in the Middleware subgraph and a reference to the creditservice is added.

  • If the credit check is okay, the order is placed,

So we place a flow line with a 'yes' comment from the creditcheck to a reference to the ERP order process.

  • but if the credit check is not okay, then we let the customer know.

Alternatively, we place a 'no' flow line from a reference to the
creditcheck to the posinformcustomer declaration in the POS subgraph.

It's a swim lane flowchart

What to take away

  • Identify your system elements: your swim lanes that will be implemented as subgraphs.
  • Identify your operations: your flowchart shapes that contain the atomic operations of your algorithm or process.
  • Stay in your lane: Place your operation declarations in their appropriate subgraphs
  • Connect the dots: placing flow lines between your operation declarations and as many operation references as you need.

When it comes to significant graphical documentation, you'll want to use a dedicated application like Visio or LucidChart, but for explaining your tasks or task comments in Github, learn to swim with the sharks by embracing Mermaid.

References

Discussion (0)