Diagramas Mermaid Arquitetura do Documento em Markdown Sem Clicar Em Nada

Seu diagrama de arquitetura era preciso quando você o desenhou. Isso foi há três sprints. Agora ele vive em um slide compartilhado que ninguém atualiza e o engenheiro que construiu o serviço descrito já mudou de equipe. Isso parece familiar?

Os diagramas Mermaid invertem esse problema. Em vez de uma área de desenho com arrastar e soltar que vive fora do seu código, você escreve diagramas como texto — uma sintaxe em Markdown simples que fica no seu README, é controlada por versão com o código e é renderizada onde o Markdown é renderizado. Quando a arquitetura muda, você altera um arquivo de texto. A diferença conta toda a história.

O que é Mermaid (e por que os diagramas como código importam)

Mermaid é uma linguagem aberta de diagramação que renderiza diagramas a partir de texto simples. Você escreve um fluxograma em um bloco de código; um renderizador (ou um visualizador que suporta Mermaid) transforma isso em um diagrama SVG. Sem contas, sem etapas de exportação, sem 'o formato de diagrama não é suportado nesse computador'.

A abordagem de 'diagramas como código' se justifica de várias formas concretas:

• Controle de versão — os diagramas vivem no Git. Você pode comparar suas versões, reverter e anexá-los ao mesmo PR que o código que eles descrevem.
• Sem dependência de fornecedor — o texto é portátil. Mude o renderizador, faça uma cópia do repositório, exporte para a Confluence — a fonte sempre é legível.
• Próximo ao código — um diagrama no mesmo repositório que o serviço que ele descreve é muito mais provável de permanecer preciso do que um que está em um slide compartilhado.
• Amigável para automação — você pode gerar a sintaxe Mermaid a partir do código (esquemas de banco de dados, especificações de API, pipelines de CI) usando scripts ou LLMs.

Antes de mergulhar nas diferentes tipos de diagrama, você pode visualizar qualquer sintaxe Mermaid instantaneamente — sem necessidade de instalação local — usando o Gerador de Diagramas Mermaid em iotools.cloud. Cole, veja o resultado, itere. Use isso ao lado deste guia para executar todos os exemplos em tempo real.

Fluxogramas: O trabalhador principal

Os fluxogramas são o tipo mais comum de diagrama Mermaid e, por boa razão — eles lidam com tudo, desde árvores de decisão simples até fluxos complexos de múltiplos serviços. Aqui está a sintaxe que cobre 90% de casos reais:

flowchart TD
    A[User submits form] --> B{Validation passes?}
    B -- Yes --> C[Save to database]
    B -- No --> D[Return error to client]
    C --> E[Send confirmation email]
    E --> F([End])

Alguns pontos importantes sobre a sintaxe de fluxograma:

• Direção: TD (de cima para baixo), LR (de esquerda para direita), BT (de baixo para cima), RL (de direita para esquerda)
• Formas dos nós: [rectangle], (rounded), ([stadium]), {diamond}, ((circle)), [(cylinder)]
• Rótulos das arestas: -- label --> ou -->|label|
• Subgrupos: agrupa visualmente nós relacionados

Os subgrupos são especialmente úteis para mostrar limites de serviço:

flowchart LR
    subgraph Frontend
        UI[React App]
    end
    subgraph Backend
        API[FastAPI]
        DB[(PostgreSQL)]
    end
    UI --> API
    API --> DB

Diagramas de sequência: Mostrando fluxos de chamadas de API

Os diagramas de sequência são a ferramenta certa quando você precisa mostrar a ordem de interações entre sistemas — uma cadeia de chamadas de API, um fluxo de autenticação, uma sequência de webhook. Eles tornam clara a ordem e a responsabilidade de uma forma que um fluxograma não consegue.

sequenceDiagram
    participant Client
    participant API Gateway
    participant Auth Service
    participant Users DB

    Client->>API Gateway: POST /login {email, password}
    API Gateway->>Auth Service: Validate credentials
    Auth Service->>Users DB: SELECT user WHERE email=?
    Users DB-->>Auth Service: User record
    Auth Service-->>API Gateway: JWT token
    API Gateway-->>Client: 200 OK {token}

Setas sólidas (->>) são solicitações; setas tracejadas (-->>) são respostas. As participant declarações controlam a ordem em que os blocos aparecem no topo do diagrama. Você também pode usar actor para participantes humanos, activate/deactivate para mostrar o tempo de processamento e loop ou alt bloco para fluxos condicionais.

Diagramas de entidade-relação: Esquemas de banco de dados na documentação

Os diagramas de entidade-relação devem estar em cada README de serviço que possui um esquema de banco de dados. A sintaxe de ER do Mermaid é limpa e inclui cardinalidade de forma nativa:

erDiagram
    USER {
        int id PK
        string email
        string name
        timestamp created_at
    }
    ORDER {
        int id PK
        int user_id FK
        decimal total
        string status
    }
    ORDER_ITEM {
        int id PK
        int order_id FK
        int product_id FK
        int quantity
    }
    USER ||--o{ ORDER : "places"
    ORDER ||--|{ ORDER_ITEM : "contains"

Notação de cardinalidade: || é exatamente um, o| é zero ou um, o{ é zero ou muitos, |{ é um ou muitos. A etiqueta da relação ("places", "contains") vai entre aspas no final.

Diagramas de estado: Modelagem de fluxos e máquinas de estado

Qualquer vez que você tiver um entidade que muda de estado — uma ordem, uma assinatura, um job de CI — um diagrama de estado é mais preciso do que um fluxograma. A sintaxe de diagrama de estado do Mermaid mapeia diretamente à forma como você definiria uma máquina de estado no código:

stateDiagram-v2
    [*] --> Pending
    Pending --> Processing : payment received
    Processing --> Shipped : warehouse picks order
    Shipped --> Delivered : carrier confirms
    Shipped --> Returned : customer initiates return
    Delivered --> [*]
    Returned --> Refunded : refund processed
    Refunded --> [*]

[*] marca os estados de início e fim. As transições carregam o evento que as aciona. Você pode aninhar estados para estados compostos e usar note bloco para anotar transições com contexto adicional.

Diagramas de classe: Estruturas OOP para documentos de onboarding

Os diagramas de classe são mais úteis quando se está onboarding engenheiros para uma base de código orientada a objetos ou documentando um modelo de domínio. O Mermaid cobre herança, interfaces, composição e assinaturas de métodos:

classDiagram
    class Animal {
        +String name
        +int age
        +makeSound() void
    }
    class Dog {
        +String breed
        +fetch() void
    }
    class Cat {
        +boolean isIndoor
        +purr() void
    }
    Animal <|-- Dog : extends
    Animal <|-- Cat : extends

Os modificadores de visibilidade seguem a convenção UML: + público, - privado, # protegido. As setas de relação cobrem associação (-->), herança (<|--), composição (*--), e agregação (o--).

Onde Mermaid é renderizado nativamente

O ponto principal do Mermaid é seu suporte nativo nas ferramentas que os desenvolvedores já usam:

• GitHub — os blocos de código Mermaid (```mermaid) são renderizados em READMEs, issues, descrições de solicitação de código e wikis desde 2022.
• GitLab — suporte nativo para arquivos Markdown e páginas de wiki.
• Notion — cole um bloco de código Mermaid em um bloco de código definido como "Mermaid" e ele será renderizado inline.
• VS Code — a extensão de suporte ao Mermaid na visualização Markdown renderiza os diagramas na janela de visualização integrada.
• Obsidian — o Mermaid é renderizado nativamente sem nenhum plugin.
• Docusaurus, MkDocs, Astro — existem plugins do Mermaid para todos os principais geradores de sites estáticos.
• Confluence — através do aplicativo Mermaid Diagrams for Confluence.

Se você estiver escrevendo documentação que será publicada no GitHub ou no GitLab, os diagramas Mermaid funcionam sem configuração.

Pitfalls e Quando Usar Algo Diferente

O Mermaid não é perfeito para todas as situações. Alguns pontos para observar:

• Layouts complexos — o algoritmo de layout automático do Mermaid nem sempre produz resultados limpos para grandes gráficos. Se você tiver 50+ nós com muitas arestas cruzadas, você pode precisar reorganizar ou dividir os diagramas manualmente.
• Renderização em Confluence — a Confluence nativa não suporta Mermaid; você precisa de um aplicativo pago. Se sua equipe vive na Confluence, planeje para isso ou use o draw.io em vez disso.
• Tipos de diagrama não padrão — diagramas de rede, diagramas de implantação e diagramas C4 de arquitetura exigem trabalhos ou não são bem suportados.
• Controle de estilo — as opções de tema do Mermaid são limitadas. Para diagramas com cores e fontes personalizadas, você gastará tempo lutando com o renderizador.

As principais alternativas a saber:

• PlantUML — sintaxe mais antiga e mais verbosa, mas com suporte mais rico ao UML e melhor integração com a Confluence. Exige Java localmente ou um renderizador em servidor.
• D2 — ferramenta mais nova de diagramas como código com controle melhor de layout e tratamento melhor de diagramas grandes. Menor adoção no ecossistema do que o Mermaid, mas está crescendo rapidamente.
• draw.io / Excalidraw — ferramentas com interface gráfica para quando você precisa de controle visual preciso e não se importa com o diagrama vivendo fora do controle de versão.

Para a maioria das documentações de desenvolvedores — READMEs de serviços, fluxos de API, guias de onboarding — o Mermaid cobre bem o caso de uso e o suporte nativo do GitHub torna o aprendizado uma boa justificativa.

Visualização do Mermaid Sem Instalar Nada

Se você estiver experimentando a sintaxe ou quiser compartilhar um diagrama com alguém que não tenha um renderizador local instalado, o Gerador de Diagramas Mermaid em iotools.cloud oferece uma visualização em tempo real sem inscrição, sem instalação e sem configuração. Cole seu código Mermaid, veja o diagrama renderizado e copie o resultado.

É útil para verificar a sintaxe do diagrama antes de commitar, compartilhar uma versão renderizada em uma mensagem no Slack ou prototipar um diagrama que você depois colará em um README.

Comece com um Fluxograma

Se você nunca escreveu um diagrama Mermaid, comece com um fluxograma. Escolha um processo no seu códigobase que você já queria documentar — o ciclo de requisição, um job de fundo, um pipeline de deploy — e escreva isso em 10 minutos usando a sintaxe Mermaid. Cole-o no seu README em um ```mermaid bloco e empurre. O GitHub renderizará automaticamente.

Esse único diagrama, controlado por versão e vivendo ao lado do código que ele descreve, vale mais do que um slide que ninguém confia.

Você também pode gostar