dipping your toes into the ocean with Mermaid

It began with a great idea.

“lets do our systems graphs in such a way we can version them in GIT”

Anyway, I believe that is how it started.  I was then told that perhaps the open source tool Mermaid would be the solution to that grand idea.

It did look pretty good.  I tried using this for some trivial graphs and I was amazed at how well it worked.  You could create a small flow chart within a few minutes.  Not only that but the graphs that where created were SVG, that wasn’t really on my radar but it would have been useful a few projects back.

 

Version 1
graph TB
AuthServer(“Oath v2.0)”)
UserDB AuthServer–>UserDB
UserDB –>AuthServer
client(user/browser)–https –>AuthServer
extpgm(ext system) — https –>AuthServer

 

I did like this but to be honest it didn’t really keep the systems properly grouped together.  That was also quickly correct by grouping the systems as a sub graph.

Version 2
graph LR
subgraph Internal Systems
AuthServer(“Oath v2.0)”)
UserDB AuthServer–>UserDBUserDB –>AuthServer
endsubgraph Client Services
Login        client(user/browser)–https –>AuthServer
extpgm(ext system) — https –>AuthServer
end

Mermaid seemed to handle these flows just fine.  Not being content with this I tested the sequence diagrams.  They actually seemed to work even easier.

 

Sequence Diagram
sequenceDiagram
user->>+AuthServer: User credentials
AuthServer ->>+ user: token
Note right of AuthServer: Token valid 6 hours
user->>+MediaServer: requests movie + token
alt token valid
MediaServer ->>+ user: streams content
else token valid
MediaServer –>>- user: request refused
end

I was about to bring all of this to my team leaders attention when I received some feedback from one my teammates. He was correct, color makes things not only less boring but can also visually help with grouping like items together.

Version 3
graph LR
classDef cyan fill:cyan
classDef yellow fill:yellowsubgraph Internal Systems
AuthServer[“Oath v2.0)”]
UserDB(Login data)
DetailsDB(Customer Details)
AuthServer–>|JDBC|UserDB
UserDB –>|WebSphere|AuthServerclass AuthServer yellow
class UserDB cyan
class DetailsDB cyan
end
subgraph Client Services
Login        client(user/browser)–https –>AuthServer
extpgm(ext system) — https –>AuthServerend
linkStyle 2 stroke-width:2px,fill:none,stroke:green;
linkStyle 3 stroke-width:2px,fill:none,stroke:green;

 

It was at this point that I realized that these connections between elements was only one way.  Unfortunately you cannot simply have a line with arrows at each end. I didn’t think that adding a few back arrows would make that big of a change to the diagrams but unfortunately they did.  Not only that as you start to add a lot of different elements, each with bi-directional communication, the nicely ordered elements start to change places.

 

Version 4
graph LR
classDef cyan fill:cyanclassDef yellow fill:yellow
subgraph Internal Systems
AuthServer[“Oath v2.0)”]
UserDB(Login data)
DetailsDB(Customer Details)
Presenter[catalog system]
AuthServer–>|JDBC|UserDB
UserDB –>|WebSphere|AuthServer
class AuthServer yellow
class UserDB cyan
class DetailsDB cyan
end
subgraph Client Services Login
client(user/browser)–https –>AuthServer
AuthServer –>clientAuthServer –>extpgm
extpgm(ext system) — https –>AuthServerend
version 5
graph LR
classDef cyan fill:cyan
classDef yellow fill:yellow
subgraph Internal Systems
AuthServer[“Oath v2.0)”]
UserDB(Login data)
DetailsDB(Customer Details)
Presenter[catalog system]
AuthServer–>|JDBC|UserDB
UserDB –>|WebSphere|AuthServer
class AuthServer yellow
class UserDB cyan
class DetailsDB cyan
end
subgraph Client Services Login
client(user/browser)–https –>AuthServer
AuthServer –>client
AuthServer –>extpgm
extpgm(ext system) — https –>AuthServer
end
client –>Details
DBclient –>Presenter
linkStyle 2 stroke-width:2px,fill:none,stroke:green;
linkStyle 3 stroke-width:2px,fill:none,stroke:green;

The colors of the elements remains easy enough, but as the number of elements increases finding and changing the colors of the lines becomes more and more like software development.  The hacking kind, not the software engineering kind.

The task that I was given had enough elements on it to take up half of a keyboard but this type of graph doesn’t automatically look very good.  It is simply too much.

I did like the few hours that I spent fooling around with Mermaid.  I can see how this might be nice if you have some simple elements that should be graphed.

This example exist on Mermaid page

Perhaps Mermaid is an exceptional tool for either sequence diagrams or gantt charts but I don’t really need that at the moment.

If you really want, you can even add Mermaid to your web pages.  As for me, I am not certain that I would want the diagrams to be outside of my direct control and at the moment human beings are able to make more of the simplifying decisions for item placement.

 

I really with I could give this project two thumbs up but I did encounter a few things that would prevent me, certainly in larger sittings, from using this.

  1. It is not possible to have lines with arrows on each side
  2. It is not possible to simply add notes or legends to flow charts
  3. It is snot possible to have a line from one entire subgraph to another item or subgraph
  4. No influence on the element placement
  5. SVG output from the tool isn’t well supported by Microsoft products, or else there is a problem with the SVG image.
This entry was posted in programming. Bookmark the permalink.

Leave a Reply

Your email address will not be published. Required fields are marked *