UML Sequence Diagram

UML might be 20+ years old at this stage but it's still incredibly useful - especially when describing 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.