Mermaid Chart: Diagramando suas soluções de software like a boss

O que é diagramação de software?

Cada vez que um software novo nasce, um dos primeiros passos após o levantamento dos requisitos do sistema é a diagramação da solução proposta. A diagramação de arquitetura de software é uma atividade crucial para comunicar as decisões de design, estrutura e componentes de um sistema de software.

A diagramação é um processo que requisita colaboratividade do time no desenvolvimento da solução, além de colocar o time na mesma página no que tange ao conhecimento das regras e requisitos do sistema. Não menos importante que a colaboratividade, a diagramação dá de presente uma documentação visual da solução, suas integrações e tecnologias utilizadas.

Muitos outros benefícios (e desvantagens) podem ser listados em relação à diagramação de software, porém, esta não é a intensão deste post. Dito isto vamos ao que interessa!

O que é Mermaid Chart?

Mermaid é uma linguagem de marcação de texto que permite criar gráficos e diagramas usando uma sintaxe simples e legível por humanos. Esses gráficos podem ser incorporados em documentos, apresentações, páginas da web e outros tipos de conteúdo.

Mermaid Charts é um recurso específico do Mermaid que permite criar diversos tipos de gráficos e diagramas, incluindo:

• Diagramas de Fluxo
• Diagramas de Sequência
• Diagramas de Classe
• Diagramas de Estado

Como funciona?

O Mermaid Chart funciona convertendo a sintaxe de marcação de texto fornecida pelo usuário em elementos gráficos e diagramas. O usuário escreve o código Mermaid usando uma sintaxe específica para descrever o tipo de gráfico ou diagrama que deseja criar e essa sintaxe é projetada para ser intuitiva e fácil de entender, mesmo para aqueles que não estão familiarizados com linguagens de programação.

Como crio um diagrama?

Antes de tudo, para conhecer a sintaxe e brincar um pouco, acesse o Live Editor. Se você quer criar um diagrama, o primeiro passo é escolher o tipo de diagrama que você deseja criar e, então, transformar a ideia da solução de software para a sintaxe Mermaid. Digamos que você queira criar um diagrama de fluxo:

%% Aqui você define o tipo de diagrama
flowchart LR
%% Aqui você pode definir suas entidades
    A[FrontEnd]
    B[Clients RestAPI]
    C[(PostgreSQL)]
    D[["RabbitMQ\nQueue"]]
    E[OtherAPI RestAPI]

%% Aqui você define os relacionamentos entre as entidades
    A -->|HTTP requests| B
    subgraph Clients API Context
    B -->|writes & reads| C
    B -->|posts message| D
    end
    E -->|listens message|D

O código acima resulta no diagrama a seguir:

flowchart LR
A[FrontEnd]
B[Clients RestAPI]
C[(Postgres)]
D[["RabbitMQ\nQueue"]]
E[OtherAPI RestAPI]
A -->|HTTP requests| B
subgraph Clients API Context
B -->|writes & reads| C
B -->|posts message| D
end
E -->|listens message|D

Para conhecer mais da sintaxe e os diagramas que Mermaid suporta, acesse a Documentação.

DICA BÔNUS:

Diagramar utilizando o Mermaid tem uma ótima vantagem que é integrar com GitHub Actions na pipeline de CI dos seus repositórios. O Mermaid possui actions para gerar as imagens no formato SVG dentro do seu repo. Para utilizar a action basta acessar este repositório.