Intro
Stefan Hofer: Welcome to another episode of the GOTO Book Club. My name is Stefan Hofer. I am a consultant and coach, and I model domains, business processes, and software architecture using different notations and diagramming techniques. I have also written a book about one, "Domain Storytelling," and I had the pleasure of being interviewed for this channel. Today, I am the interviewer, and I could not have asked for a better book to discuss. Today we are going to discuss "Creating Software with Modern Diagramming Techniques, Build Better Software with Mermaid." The author is Ashley Peacock. Ashley, welcome to the GOTO Book Club. Do you want to introduce yourself to our viewers?
Ashley Peacock: Hi, I'm Ashley Peacock. I live in the UK. I'm a staff-level software engineer for a UK insurance company. I've been diagramming for a very long time. And as Stefan said, I wrote a book all about it called "Creating Software with Modern Diagramming Techniques."
Diagrams as Code
Stefan Hofer: Awesome. So let's talk about diagrams and not just drawing diagrams by hand, which is probably the most natural way to approach diagramming, but also diagrams as code. That is a concept that I believe has become quite popular in the last couple of years, and you built your book around this concept or the notation, the tooling you use is built around that. Can you give us an introduction to diagramming as code for someone who is not familiar with that concept yet?
Ashley Peacock: Sure. So historically, if you wanted to draw a diagram, you might reach for a tool like Visio or more modern ones, draw.io, diagrams.net is really popular these days, and you essentially use the UI to draw boxes, lines, label the lines, and so forth. That works well, so if you're just getting started, but it has problems. For one, it can be a little slow, but the other kind of problem comes from the fact that it's not machine-readable. So if you ever look at the format that that diagram is saved in, you won't be able to read it, right? You can't diff it. You can't version control it. So what diagrams as code does is it allows you to write your diagrams as you would write HTML, for example. So there's a simple markup, and it takes that markup and converts it into an image, effectively. It's the simple way to put it.
Stefan Hofer: And do you still have control over the layout then, or is that completely generated by the tooling?
Ashley Peacock: It depends on which tooling you use. In some, you have more control than others, so a really kind of modern one is called D3, and that gives you a lot of control over the layout, but it's more similar to writing code than it is diagrams as code. It's still diagrams as code, but it's more like writing, you know, Java or C-sharp. With tools like Mermaid, for example, the notation is super simple, and you do have some control over the layout, but perhaps not as much as you might like. You might kind of have to have an acceptance that it might not look as pretty as if you drew it by hand, but that's the trade-off you make for having ease of creating the diagram and, you know, version control and all these things. So I guess it's like most things in software engineering, it's a trade-off.
Stefan Hofer: So less control, but less, moving stuff, a pixel to the left or the right, so that's then one of the advantages if it's generated, right?
Ashley Peacock: Yes. One of the other benefits is, you know, you can also store this. By store, I mean, if you're storing on draw.io, for example, it's stuck in draw.io. So if we work together and you leave the company and go somewhere else and it's on your draw.io account and you leave, suddenly we no longer have access to that diagram. Perhaps it's quite common for companies to kind of wipe people's Google accounts and so forth, whereas if you've stored that somewhere else because, you know, it's just text, it's readily available and much more accessible.
Stefan Hofer: All right. That's great. Now, you apply these diagrams as a code approach to several different diagram types and notations in your book. Can you give us a brief overview before we go into the technical details of how Mermaid works? Can you give us a brief overview of which diagram types and notations you choose which are covered in your book?
Ashley Peacock: I'll go with three because I cover a few more in the book, but I think the three main ones that I use most commonly and the three I find most useful in no particular order. The first one would be a sequence diagram. So this is how you model interactions between either it can be services or it can be kind of people if you like. So people in like a business process, for example. And the way it works is you have essentially kind of nodes. So you'd have kind of maybe two here and lines going between them and it just shows the interactions between those things. So let's take, if you're building, let's say a service, let's say an application that allows users to sign in, and you wanna model that sign-in flow. You might have, you know, the front end that makes an API call to the backend with, you know, the credentials for the user. And the backend might respond with, you know, the 200 okay, for example, in the happy path.
The sequence diagram allows you to model those flows in a way that's kind of very visual and very easy to understand. The second one would be the C4 model. And that's written or created by Simon Brown. And it's a way to model your software architecture. So it can be quite hard to model your software architecture sometimes, or describe it sometimes, or, you know, show it to other people, right? It can be complicated. You know, so it's a very nice way to get different views of your architecture. So there are four different views in the C4 model so that's where the C4 comes from. The first one, I'm gonna cover two of them because I think the latter two are not quite as used as much, but the first one is called context. And it's a very, very high-level view of your architecture. So it's meant to be non-technical. It would just be systems and how they interact with each other. So it gives you a very good glance at what each system is doing in the architecture. You can give it the responsibilities of each service in the architecture and the users that are using those services.
And then the next view down would be container, which is described as the single deployable units. So if you had, let's say, a backend service that's built using Rails and you had a MongoDB database, those would be two containers. And then you would describe the interactions between those. And then the other two, you drill more down. So you go into, like, components, which are, like, namespaces or modules. And then you can go into classes. But you're then getting really, really into detail. So I don't normally do those.
Stefan Hofer: Okay. Great. So we have two sequence diagrams and a C4 model, which itself is like a set of abstractions and diagram types. And what's the third one that you want to discuss?
Ashley Peacock: So the last one would be the domain model diagram. And that's kind of how it sounds really. It's a way of describing the problem domain that your software is working in. So if we take this recording, for example, we're recording on a bit of software, and you might have, you know, participants might be something in your domain. After we're finished, you might have a recording that will be something in your domain. You have speakers and so forth in your domain. You have all these domain entities, and it's just a way of documenting, you know, what's in your domain in a diagram and describing the relations between them. So does each participant have many recordings or one recording? And so forth, things like that.
Stefan Hofer: So if I want to categorize those three notations or diagram types, sequence diagrams are defined in the UML. So it's like very formally defined, right? C4 is more like a set of abstractions. Different notations are possible, and it's defined by Simon Brown. And the last one, the domain models, that's more like a free form, not defined, there's no standard for that, right?
Ashley Peacock: That'd be correct, yeah.
Mermaid’s Versatility
Stefan Hofer: Okay. So that means that Mermaid, the tooling that you describe in your book, can do all of that. So it's a broad spectrum from formally defined model languages to, like, free-form modeling. Everything is possible with that tooling. Would you agree with that?
Ashley Peacock: Yes. I think it has a kind of base set of diagram types that it supports. So it doesn't have, you know, a domain model diagram type, but it does have something called a flowchart. And the flowchart is kind of like the most generic diagram type you get in Mermaid. So you can kind of do whatever you like with it. So if you have a diagram that doesn't fit into the normal types, I would use a flowchart. So in the case of the book, I use a flowchart for the C4 model, and I use it for the domain model diagram. Mermaid is adding support for the C4 diagram slowly into it so it has, like, the native syntax. So you could use that now. It only supports I think, one, the kind of highest-level context diagram at the moment. And it also uses the, I think it's PlantUML notation. So to me, it's a lot more complicated than normal Mermaid because you have to learn a different notation, which is the PlantUML notation. And, finally, the sequence diagram is natively supported so that's kind of its diagram type in Mermaid with its kind of syntax. But if anyone's ever used, you know, UML, it uses the syntax for UML.
Stefan Hofer: Okay. Great. So, now, we've started to touch on the topic of Mermaid itself. So from diagrams as code, we move now to one specific tooling to create diagrams from code and that is Mermaid. So how does Mermaid work? Can you give us an overview of what is required to use it?
Ashley Peacock: Well, you need JavaScript. So it's primarily written in, I think, JavaScript and TypeScript. So it has the kind of... I think it was the first one that I used that was easy to run pretty much everywhere, right? Because JavaScript runs everywhere. It runs in your browser. You can run it on the Edge. You can run it on servers. You can run it anywhere, right? If you look at historically, some of the kind of perhaps problems with prior ones... So if you take the main one, it probably was PlantUML. And that had all the kind of same diagram types that Mermaid has, but it was written in Java, which, you know, Java's a fine language, but it doesn't run everywhere, right? You need to make sure Java is installed. You can't just run it in the browser. It doesn't run in the browser. So Mermaid kind of has this big selling point that it's super easy to run wherever you want.
And to explain kind of what it is, it's, you know, a tool for creating diagrams as code. The documentation is good. So you'd be able to go on there, look through all the diagram types, and you'd very quickly be able to create diagrams from the examples written in the docs and create all these different types of diagrams. Then it will take what you write. There's, like, a live editor, so you can do it live and it'll update it live. And then you can export images from the diagram if you want. And then there are some other things you can do that are kind of its big selling points.
Stefan Hofer: So if I understand it correctly, Mermaid defines a markup language, or you would call it a domain-specific language for describing the diagrams in the form of code. And then there's a tooling that's also called Mermaid to create the actual visual diagrams out of that code. So I could probably write Mermaid diagrams in my favorite text editor, and then just apply the tools and have them generate the diagrams. Is that correct?
Ashley Peacock: The Mermaid library on GitHub has many different kinds of parts to it. And one of them would be, for example, like, a CLI tool. So if you want to, you could, you know, write a diagram in Mermaid and then use the CLI on your, you know, command line to generate the images. Like I said, there's a live editor that, again, is part of the Mermaid package. It's all kind of open-source.
Stefan Hofer: So there is a live editor. That's maybe nice for actually creating the diagrams for the first versions maybe so I can see, like, live. If I enter this line of code, this is how it's going to be rendered, which is nice for Modular. But once I have the actual DSL file, I could, like, integrate the generation of documentation into my build process because there are CLI tools available. Is that correct?
Ashley Peacock: Yes, you definitely could. The other kind of big selling point that I would say is probably the main reason I started using it is a lot of engineers these days, use GitHub or GitLab, for example. They're probably the main two kinds of version control providers. And while being able to do it with the CLI is nice, doing it in the live editor is nice. If you export an image out of these tools, which you could do with draw.io, right? And you want to store it in version control. So let's say you want to put your architecture diagrams in your README or in your repository with your code, right? Which is a nice place to put your diagrams that relate to your code. So you might put your domain model in there. You might put your architecture diagram, and your C4 model in there. Now, if you put an image in there, that's fine. That's better than having nothing at all. But what will happen, as I said earlier, is if you leave and you create that diagram, I have to go and try and find that file. And if I can't find that file, because you probably didn't commit it to version control, I'm gonna have to either redraw the diagram if I wanna update it, which could take ages, or probably more likely I can't be bothered because I can't find this diagram to recreate it.
So with GitHub, GitLab, and some others, you can take the Mermaid markup, so the simple markup, put it in GitHub, you know, in code tags with Mermaid. So the three backticks with Mermaid. And then when that markdown file is viewed on GitHub in the browser or GitLab, it will render that diagram for you with no work. So then you have your single source of truth for your diagram stored in your code repository. And whenever anyone wants to view it, it will render it for you without any kind of work whatsoever.
Stefan Hofer: So that sort of integration, as I said, it's a big selling point. But speaking of selling, you said open-source, so I don't need to buy Mermaid, right?
Ashley Peacock: No, it's all open-source, so anyone can contribute. There's a product they sell on the side, basically, the people that kind of wrote it for you to kind of store your diagrams if you want. But the main primary library is all open-source and anyone can contribute, anyone can use it. And it's gone beyond GitLab and GitHub, you know, tools that you probably use like Jira, Notion, Trello, and many, many others. They all have kind of Mermaid plugins that you can use.
Stefan Hofer: That's cool. So everybody is free to build their plugins or their tooling using the Mermaid DSL. And then every Mermaid diagram would also work with that plugin or that tooling that you've built on your own, right?
Ashley Peacock: Exactly.
Comparing Diagramming Tools: PlantUML, Structurizr & Mermaid
Stefan Hofer: Okay. That's good. Do you know how long a Mermaid has been around? I'm asking because, you know, sometimes diagrams or notations change, get extended, maybe it's not compatible always. So do you have any experience? Do the old diagrams created with other versions still work? How is that?
Ashley Peacock: So far, I've not had a diagram of mine break. So I think they're very careful to ensure backward compatibility. I think especially since they've been on, you know, GitHub, for example, I think it would be a bad look if they suddenly broke, you know, tens of thousands, hundreds of thousands. I don't know how many diagrams have been created on GitHub but I assume it's very, very high. As I said, it's a big selling point, I think, is the GitHub and GitLab integration. So I think if they would wanna look after that integration, I think.
They do add new ones. So, like I said, they're constantly adding new diagram types. So besides kind of the ones I talked about, you get, you know, class diagrams for, you know, modeling your code. You can even do things like, you know, Gantt charts if you wanna structure your kind of releases or something like that. They have kind of mind maps for, like, ideation, and they're adding kind of new ones all the time.
In terms of how long it's been around, I can't remember when it was released. It's not, like, old-old. I would say, it's probably been around for I think about five years, but I wouldn't wanna be quoted on it. It's still relatively new. And it does have a very active kind of contributor base on GitHub. So it is very well maintained.
Stefan Hofer: I think the PlantUML has been around for a bit longer. So that's another diagram as code approach that you mentioned earlier. It owned its language and its tooling. That's one I've used before. Another tooling, another diagramming language that I've used before for the C4 model is Structurizr, the tooling by Simon Brown. I'm sure there are other toolings out there that I haven't used before. Do you want to compare them a little bit with Mermaid? So you brought up a point already with the GitHub integration. So maybe that's the selling point, as you called it, for Mermaid. But maybe you can expand on that a little bit.
Ashley Peacock: I would say that the differentiator is kind of the fact that it's available on GitHub is its biggest selling point for sure. But besides that, I think earlier on I talked about how, you know, PlantUML is written in Java, which means that you can't just run anywhere, right? The setup is not easy. You know, you find things online, you know, for editing PlantUML. But if you actually wanna kind of run it locally, for example, in your IDE, there are probably plugins for it, but it's gonna be a bit more annoying. You have to install Java, and so forth. With Mermaid, you don't have to do that. The DSL is, like, if you use PlantUML, for example, and you haven't heard of Mermaid before, and you're interested in trying Mermaid, if you want to migrate, the syntax is identical because it's UML syntax for at least for the most part for Mermaid. So you'd probably be able to take all your diagrams written in PlantUML and just put them in Mermaid and maybe a few minor tweaks and everything would just kind of work. So then you get the benefits of Mermaid without any pain of migration really.
Structurizr is specifically made for the C4 model, and it has its kind of DSL that is specific to that. I've used it a little bit. I think it's slightly different because it's a modeling tool, right? So if you were creating a backend service that was called, I don't know, I'm gonna call it "the backend" because I'm terrible at thinking names, like most engineers. In the Structurizr DSL, you would define the backend service and you might say it's a Ruby on Rails service and you'd find that once and then anywhere you use it, you just kind of reference that model because you've made that model for that thing. With Mermaid, it's just a simple DSL, right? So you'd have to maybe if you're doing two versions of the C4 model that I talked about, the content and the container, you would have duplication between the two. And if you want to change the name of one thing and all of them, you'd have to go change it all, and so forth. However, if you wanted to model, because modeling is slightly different, if you want to use that model as I spoke about, you can do it in Structurizr and then you can export it to a bunch of different languages. So you can export it to Mermaid, or you can export it to PlantUML. I think it does D3 these days. It does all sorts. So while it is its own DSL and it's very specific to the C4 model, you can still get Mermaid, you know, from that tool if you wanted to then put in version control, for example.
Stefan Hofer: Okay. That's good. And if you have a diagrams-as-code approach like with Mermaid, refactoring doesn't sound as scary anymore. Renaming stuff is a lot easier if you have it in your IDE, maybe some support there. You check it into your repository, and everything is fine. And you know that it still works, right?
Ashley Peacock: If you're using GitHub, for example, you could... You know, when you raise the PR, you just click view file and you'll see it all looks fine. And one of the other kind of, you know, let's say, me and you're working on improving or changing our domain model that we work on together, you might request a broadcast. But if you're doing, you know, draw.io or something where the format is completely unreadable, or just an image, it's really hard to diff an image, right? You can look at it if it's quite big, it can be hard to see the nuances in it. Whereas with Mermaid because it's just text, you would easily see what I changed. You know, like you just said, if you rename something and maybe I missed one or something, you would easily be able to see in the diff that I missed it, most likely anyway, because it's just text, but you're used to kind of reviewing diffs in that way, right? So, yeah, it's really easy to.
Benefits of Mermaid in Code Refactoring
Stefan Hofer: Now, as I said, I've used a little bit of PlantUML and Structurizr before, so I found it easy to transition to Mermaid. I had never tried Mermaid before I read the book. So your book does a very nice job in guiding readers, step by step to applying Mermaid, you know, starting simple. You have your first diagram, like with, I don't know, three or five lines of code, and then expand on that. And then you go through the different notations that you've described. And we see, like, okay, some have, like, their diagram type, like, native support and others use a more general one and then you adapt it to your needs. So that is easy to follow in your book. I would assume that also people who have never used a diagrams-as-code approach before will have an easy time getting started with Mermaid if they read your book and follow the examples in there.
Ashley Peacock: I think that's the general feedback I've had, I think especially because engineers, as you know, they're used to writing complicated code and a simple text-based market is pretty easy for anyone to grasp. So, yeah, I think it's pretty easy to get up to speed with.
Stefan Hofer: Cool. So I'm curious, why did you decide to write a book about Mermaid in diagrams as code? There's quite good documentation also online regarding the tooling. So why the book? What got you there to make this decision? It's a lot of effort to write a book.
Ashley Peacock: It is. I think many years ago. I remember, I guess everyone that does diagrams maybe has that kind of epiphany moment where they kind of realize the kind of power of a diagram, I'm sure you have your own. And I hadn't written any diagrams before, I didn't know what UML was, but I was trying to explain things at work, and no one was getting it. And I maybe couldn't even explain it that well myself, which is probably why they weren't getting it, but I was kind of just throwing kind of words if you like. And I drew a very bad diagram, you know, it wouldn't have been based on any type of diagram I knew because I didn't know anything. But then everyone suddenly got it, and I got it better and I could explain it better. So, at that point, and this was many, many years ago, I could kind of see the power of diagrams.
I think I don't remember when I saw Mermaid the first time, but I kind of saw it and thought, "Oh wow. This is kind of cool." And I started playing around with it. And I had a look at the diagramming books. I was curious if there was a book on Mermaid, for example. And even just looking at diagramming books, there hadn't been one written for, like, 15 or 20 years, something ridiculous like that, the last one. I don't know, I think it was, like, Uncle Bob or someone, who wrote one a long time ago, all about kind of UML, for example. And things have moved forward a long way since that time. So I thought, you know, lots of things have changed. You know, I'll write a book, you know, it seems like there's a gap for that for more modern, newer engineers. They're probably not gonna wanna read a book about UML because while UML is very good, it has a bit of a kind of old-school reputation, I would say. I don't think it's rare you kind of work with someone, they kind of work without a UML diagram these days, right? But at least with Mermaid, it makes it seem a little bit more cool, a bit more kind of easier to use. You don't have to draw. It's an easier sell if you like, is probably why I wrote the book and just to kind of bring it up to modern speed I guess.
Stefan Hofer: So my takeaway here is that Mermaid makes UML look cool again?
Ashley Peacock: There you go, you could say that.
Stefan Hofer: Okay. But actually, it's about more than UML or your book is about more than UML. This is something that I think is a benefit over just reading online documentation that is provided for the tooling because you have an opinion on what diagrams and what notations to use and when to use them. So you made a conscious choice of which diagram types to include in your book and describe them with Mermaid. So maybe let's go back from the concrete tooling with Mermaid a little bit to the topic of diagramming and modeling in general. So you had the sequence diagram, you had the C4 model for architecture, and the domain model. Why these? And not some other... Why not BPNN or whatever?
Ashley Peacock: So I think when I wrote the book, and this partly comes from the publisher, Pragmatic, they like it to be kind of hands-on and you know, as you go through the book, it should model kind of real-world things. And there should be kinds of activities for people to do because if you kind of read a book and don't do anything, you don't learn as much if there are activities for you to do during the book. And then if you go and do them, it kind of reinforces that learning. So that's their general approach. And I've never written a book before, so I was very happy with all their kind of guidance and their direction. But as you kind of go through the book, I kind of tried to make it like you would do your day job if you were building a brand-new service and you'd go through different stages, right?
A business requirement comes up for you to do this thing and you realize, you know, maybe you're starting to work in a brand-new domain. So, you know, the first thing you're gonna need to do is understand the domain with a domain or a diagram. So the first chapter is on domain modeling and drawing a domain model. You then might want to talk about the sequence flows, you know, understand the interactions that you have going on in your systems. That could be people or services and kind of understanding a very high level because sequence diagrams are super high level. The interactions and how your system is gonna talk to your current existing systems, for example, and then see how that plays in. And then again, you might then define your architecture with the C4 model, for example.
And then I think it goes into things like, you might decide how you want to structure your code base. So you might reach for class diagrams, and you don't need to model, you know, all of the classes that you're ever gonna write because that's gonna take a very long time. You might just kind of play around with how you wanna kinda organize your code with a class diagram. And, similarly, you can also use class diagrams for refactoring. So, you know, if you jumped forward six months, you might need to do some refactoring. You're gonna have maybe loads of classes at play and maybe it's becoming a little bit, you know, tricky. Maybe you made a bit of a mess somewhere and you just wanna understand how everything fits together. So you draw a class diagram, and you can kind of very quickly and easily rearrange them with Mermaid. So it's one of its, you know, another one of its selling points. You can iterate quickly. So if you're doing a domain model and you want to try out different names or different relationships, you could do that, you know, in a few minutes versus if you're a meeting with someone and you've got to draw the boxes and move them all around. It's gonna be really painful both for the person and everyone watching while they move these things around versus you can quickly iterate on with things with Mermaid.
How “Tomorrow” Could Look Like
Stefan Hofer: Before, you said you researched other and also older books on this topic of diagramming and modeling, some even, like, 20 years old. If we were 20 years from now and some new developer was, you know, exploring what the forefathers wrote 20 years ago and they would discover your book, I wonder if Mermaid will still be around in 20 years. Well, maybe it's a completely different version. And, you know, the DSL code might not be valid anymore. Nevertheless, I would argue that your book would still have value because it's not just about Mermaid. It's about those diagramming techniques and also when to apply them. There's some advice there, even if you don't use Mermaid itself, maybe some other tooling. Yes, the listings of code, of course, they only make sense with Mermaid. But there's some more general advice there for how to use diagramming to build better software. So that's what I like about your book.
Ashley Peacock: Thank you very much. Maybe if you jump forward to those 20 years in the future and what things might look like, I think one thing that's starting to happen, it hasn't kind of quite got that yet, is it would be cool if you could draw these diagrams and you could turn those diagrams into real things. So this is starting to happen a little bit. I can't remember the name of the tool. It's escaping me now. But there's one way you can draw things on like AWS using their stuff and it will take that diagram and deploy it in AWS. I saw it kind of the other day and these days, let's say, you like the idea of Mermaid, but you don't wanna learn syntax. Everyone these days knows about ChatGPT, and ChatGPT is an expert on Mermaid.
So, you know, the other day, literally yesterday, I was working on something with some friends just from a side project. And we were talking about, you know, how you design the database. And that's one of the diagram types I forgot to mention you can use an empty relationship diagram to model your kind of database using Mermaid that's the diagram type. And we were kind of just talking about it out loud. And one of the guys, you know, he couldn't quite grasp what we got to, because we now had like seven, eight, nine tables. So he drew out on paper, but I was like, "Well, we could just we could just draw it with Mermaid." And I just told, you know, ChatGPT, I said, "Here are the tables, here are their relations." And, you know, in 30 seconds, I had a diagram that I didn't even have to learn or draw anything from Mermaid. It did it for me. So I think that it's really powerful.
Stefan Hofer: So that's one way from, you know, a description to a formal architecture diagram. But he also said, you know, from a diagram to running software. So maybe we'll see a rebirth of the model with an architectural or model-driven development. So that was my opinion. Interesting approach, like 20 years ago, but never really, at least not in general purpose, software development kept the promises that were made with that. But maybe with the new tooling and AI, it deserves a second chance. Who knows? So I'll see a new book on the horizon by Ashley Peacock.
Outro
Stefan Hofer: Okay, Ashley, is there anything else that you want to mention that we haven't discussed yet?
Ashley Peacock: No, I don't think so. I think if you're interested in the topic, you're interested in the book, it's available, you know, on Amazon, "Creating Software with Modern Diagramming Techniques." You can go get it today. And I hope you enjoy Mermaid. Thank you.Stefan Hofer: Great. I enjoyed talking to you and enjoyed your book. And, yeah, I'm looking forward to your next one