{"id":3162,"date":"2019-03-22T18:07:23","date_gmt":"2019-03-22T18:07:23","guid":{"rendered":"https:\/\/blog.paranoidprofessor.com\/?p=3162"},"modified":"2019-03-22T18:07:23","modified_gmt":"2019-03-22T18:07:23","slug":"dipping-your-toes-into-the-ocean-with-mermaid","status":"publish","type":"post","link":"https:\/\/blog.paranoidprofessor.com\/index.php\/2019\/03\/22\/dipping-your-toes-into-the-ocean-with-mermaid\/","title":{"rendered":"dipping your toes into the ocean with Mermaid"},"content":{"rendered":"

It began with a great idea.<\/p>\n

“lets do our systems graphs in such a way we can version them in GIT”<\/p><\/blockquote>\n

Anyway, I believe that is how it started.\u00a0 I was then told that perhaps the open source tool Mermaid would be the solution to that grand idea.<\/p>\n

It did look pretty good.\u00a0 I tried using this for some trivial graphs and I was amazed at how well it worked.\u00a0 You could create a small flow chart within a few minutes.\u00a0 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.<\/p>\n

\"\"<\/p>\n

 <\/p>\n\n\n\n\n
Version 1<\/th>\n<\/tr>\n
graph TB
\nAuthServer(“Oath v2.0)”)
\nUserDB\u00a0AuthServer–>UserDB
\nUserDB –>AuthServer
\nclient(user\/browser)–https –>AuthServer
\nextpgm(ext system) — https –>AuthServer<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

 <\/p>\n

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

\"\"<\/p>\n\n\n\n\n
Version 2<\/th>\n<\/tr>\n
graph LR
\nsubgraph Internal Systems
\nAuthServer(“Oath v2.0)”)
\nUserDB\u00a0AuthServer–>UserDBUserDB –>AuthServer
\nendsubgraph Client Services
\nLogin\u00a0 \u00a0 \u00a0 \u00a0\u00a0client(user\/browser)–https –>AuthServer
\nextpgm(ext system) — https –>AuthServer
\nend<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

Mermaid seemed to handle these flows just fine.\u00a0 Not being content with this I tested the sequence diagrams.\u00a0 They actually seemed to work even easier.<\/p>\n

\"\"<\/p>\n

 <\/p>\n\n\n\n\n
Sequence Diagram<\/th>\n<\/tr>\n
sequenceDiagram
\nuser->>+AuthServer: User credentials
\nAuthServer ->>+ user: token
\nNote right of AuthServer: Token valid 6 hours
\nuser->>+MediaServer: requests movie + token
\nalt token valid
\nMediaServer ->>+ user: streams content
\nelse token valid
\nMediaServer –>>- user: request refused
\nend<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

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.<\/p>\n

\"\"<\/p>\n\n\n\n\n
Version 3<\/th>\n<\/tr>\n
graph LR
\nclassDef cyan fill:cyan
\nclassDef yellow fill:yellowsubgraph Internal Systems
\nAuthServer[“Oath v2.0)”]
\nUserDB(Login data)
\nDetailsDB(Customer Details)
\nAuthServer–>|JDBC|UserDB
\nUserDB –>|WebSphere|AuthServerclass AuthServer yellow
\nclass UserDB cyan
\nclass DetailsDB cyan
\nend
\nsubgraph Client Services
\nLogin\u00a0 \u00a0 \u00a0 \u00a0\u00a0client(user\/browser)–https –>AuthServer
\nextpgm(ext system) — https –>AuthServerend
\nlinkStyle 2 stroke-width:2px,fill:none,stroke:green;
\nlinkStyle 3 stroke-width:2px,fill:none,stroke:green;<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

 <\/p>\n

It was at this point that I realized that these connections between elements was only one way.\u00a0 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.\u00a0 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.<\/p>\n

\"\"\"\"<\/p>\n

 <\/p>\n\n\n\n\n\n\n
Version 4<\/th>\n<\/tr>\n
graph LR
\nclassDef cyan fill:cyanclassDef yellow fill:yellow
\nsubgraph Internal Systems
\nAuthServer[“Oath v2.0)”]
\nUserDB(Login data)
\nDetailsDB(Customer Details)
\nPresenter[catalog system]
\nAuthServer–>|JDBC|UserDB
\nUserDB –>|WebSphere|AuthServer
\nclass AuthServer yellow
\nclass UserDB cyan
\nclass DetailsDB cyan
\nend
\nsubgraph Client Services\u00a0Login
\nclient(user\/browser)–https –>AuthServer
\nAuthServer –>clientAuthServer –>extpgm
\nextpgm(ext system) — https –>AuthServerend<\/td>\n<\/tr>\n
version 5<\/td>\n<\/tr>\n
graph LR
\nclassDef cyan fill:cyan
\nclassDef yellow fill:yellow
\nsubgraph Internal Systems
\nAuthServer[“Oath v2.0)”]
\nUserDB(Login data)
\nDetailsDB(Customer Details)
\nPresenter[catalog system]
\nAuthServer–>|JDBC|UserDB
\nUserDB –>|WebSphere|AuthServer
\nclass AuthServer yellow
\nclass UserDB cyan
\nclass DetailsDB cyan
\nend
\nsubgraph Client Services Login
\nclient(user\/browser)–https –>AuthServer
\nAuthServer –>client
\nAuthServer –>extpgm
\nextpgm(ext system) — https –>AuthServer
\nend
\nclient –>Details
\nDBclient –>Presenter
\nlinkStyle 2 stroke-width:2px,fill:none,stroke:green;
\nlinkStyle 3 stroke-width:2px,fill:none,stroke:green;<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

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.\u00a0 The hacking kind, not the software engineering kind.<\/p>\n

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.\u00a0 It is simply too much.<\/p>\n

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

\"\"

This example exist on Mermaid page<\/p><\/div>\n

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

If you really want, you can even add Mermaid to your web pages.\u00a0 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.<\/p>\n

 <\/p>\n

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.<\/p>\n

    \n
  1. It is not possible to have lines with arrows on each side<\/li>\n
  2. It is not possible to simply add notes or legends to flow charts<\/li>\n
  3. It is snot possible to have a line from one entire subgraph to another item or subgraph<\/li>\n
  4. No influence on the element placement<\/li>\n
  5. SVG output from the tool isn’t well supported by Microsoft products, or else there is a problem with the SVG image.<\/li>\n<\/ol>\n","protected":false},"excerpt":{"rendered":"

    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.\u00a0 I was then told that perhaps the open source tool Mermaid … Continue reading →<\/span><\/a><\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":[],"categories":[20],"tags":[],"_links":{"self":[{"href":"https:\/\/blog.paranoidprofessor.com\/index.php\/wp-json\/wp\/v2\/posts\/3162"}],"collection":[{"href":"https:\/\/blog.paranoidprofessor.com\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/blog.paranoidprofessor.com\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/blog.paranoidprofessor.com\/index.php\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/blog.paranoidprofessor.com\/index.php\/wp-json\/wp\/v2\/comments?post=3162"}],"version-history":[{"count":5,"href":"https:\/\/blog.paranoidprofessor.com\/index.php\/wp-json\/wp\/v2\/posts\/3162\/revisions"}],"predecessor-version":[{"id":3175,"href":"https:\/\/blog.paranoidprofessor.com\/index.php\/wp-json\/wp\/v2\/posts\/3162\/revisions\/3175"}],"wp:attachment":[{"href":"https:\/\/blog.paranoidprofessor.com\/index.php\/wp-json\/wp\/v2\/media?parent=3162"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blog.paranoidprofessor.com\/index.php\/wp-json\/wp\/v2\/categories?post=3162"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blog.paranoidprofessor.com\/index.php\/wp-json\/wp\/v2\/tags?post=3162"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}