Low friction Diagrams-as-Code

Last week GitHub announced that they now support rendering Mermaid diagrams from within markdown files. If you haven’t heard of them, Mermaid diagrams allow you to define different types of diagrams using a special code syntax which can be embedded within markdown files.

I’ve been broadly aware of them for a while but have never dug in further, mainly because of the lack of rendering in tools that others who’d be consuming my diagrams would be using. Given this announcement, I’m now particularly keen to try it out for the following serverless use cases:

Async event flows in general are a great benefit that serverless architectures bring, but can be very difficult for developers to piece together solely by reading the codebase, especially Pub-Sub patterns. Documentation (preferably visual) of such use cases is the best way to mitigate this issue, but this is time-consuming. While I use tools such as LucidChart and Excalidraw to create architecture and use case flow diagrams, there is still a ton of friction involved — creating a new canvas, laying everything out, fixing badly snapped arrows, exporting the image to embed, keeping the source shareable so that others in the team can update, etc, etc. Mermaid’s diagram-as-code approach promises to address most of these.

Here’s an example of a StepFunctions workflow that talks to DynamoDB: mermaid-diagram-stepfunctions-example.png

And here’s the associated Mermaid code:

flowchart TD

A[START] -->|buyProduct request| B(Fetch inventory for product from DynamoDB)

B --> C{Items remaining?}

C -->|No| D[Send No Items Remaining Error] --> END

C -->|Yes| E[Select next available inventory item]

E --> F[Mark InventoryItem as Sold in DynamoDB]

F -->|Transaction Succeeds| G[Publish PRODUCT_PURCHASED event] --> END

F -->|Transaction Fails| B

I’m hoping that this GitHub announcement will encourage a significant uptake in diagrams within project READMEs.

Have you used Mermaid for any work projects? What’s been your experience with it?

— Paul

P.S. Thanks to everyone who replied to my email on Friday with suggestions for evergreen articles that had a real impact on you. I’ll aim to share a few of these every Friday.

Join daily email list

I publish short emails like this on building software with serverless on a daily-ish basis. They’re casual, easy to digest, and sometimes thought-provoking. If daily is too much, you can also join my less frequent newsletter to get updates on new longer-form articles.

    View Emails Archive

    ☎️ Serverless Clarity Call

    Need quick guidance on a specific issue on your AWS serverless project? Or just wondering where to start with serverless?

    Book a call and ask me anything.

    Learn more >>

    🛫 Serverless Launchpad

    Ready to start building your new AWS serverless project but need help with getting everything setup?

    The Serverless Launchpad is a done-for-you DevOps service installed in under a week. You get a leading-practice multi-account AWS environment, a scaffolded codebase and architecture including the common AWS serverless services, isolated cloud environments for individual developers, automated delivery pipelines right through to production and much more. Everything is IaC, extensively documented and handed over to your developers.

    Learn more >>