UML Sequence Diagram

UML might be 20+ years old at this stage but it’s still incredibly useful - especially in a Micro-service world.

Drawing the diagrams themselves, with a tool like VISO or OmniGraffle, does get old quite quickly though when changes are rapid.

I’ve started using Mermaid for generating the system diagrams from ‘code’ directly. It’s much less work as things change and is really easy to setup.

The simplest way to get started is to install the CLI version of mermaid:

yarn global add mermaid.cli

Once your up and running, you can produce diagrams by writing out a document containing the sequence:

sequenceDiagram
	participant C as Client
	participant MS1 as Microservice 1
	participant MS2 as Microservice 2

    C->>MS1: Make Request
	activate MS1
    MS1->>MS2: Internal Request
	activate MS2
	MS2-->>MS1: Data
	deactivate MS2
	MS1-->>C: Response data
	deactivate MS1

And running the build command:

mmdc -i test.mmd -o test.svg

The syntax for generating the diagrams is reasonably intuitive, but there are a couple of gotchas - most of which cause the diagram to not render. It’s worth checking the diagram reference to make sure your syntax is correct as the CLI interface doesn’t give feedback.