Mermaid vs. canvas de diagramas: quando diagramas como código funcionam e quando não

Poucos debates sobre ferramentas duram tanto em times de engenharia quanto este. Algumas pessoas querem todo diagrama como código, em Mermaid, revisado em pull requests. Outras querem um canvas onde possam mover caixas e enxergar o sistema. Os dois lados têm razão, só que sobre diagramas diferentes.

Este guia compara Mermaid e um canvas de diagramas com honestidade: o que cada um faz bem, onde cada um falha, uma tabela de decisão para casos comuns e o mesmo sistema pequeno desenhado dos dois jeitos.

O que o Mermaid faz bem

O Mermaid transforma algumas linhas de texto em um diagrama. Isso traz vantagens reais:

• Ele vive ao lado do código. Um diagrama em um arquivo Markdown muda no mesmo pull request que o código que ele descreve, e quem revisa vê o diff.
• Ele é renderizado onde os engenheiros já estão. GitHub e GitLab renderizam blocos de código Mermaid em arquivos Markdown, issues e pull requests, e ferramentas como Notion e Obsidian também os exibem.
• Nenhuma ferramenta ou conta extra. Quem pode editar o arquivo pode editar o diagrama.
• Diagramas de sequência são excelentes. Para um fluxo de requisições entre quatro serviços, a sintaxe de sequência do Mermaid é difícil de bater.
• Assistentes de IA escrevem Mermaid com fluência. Peça um fluxograma Mermaid a qualquer assistente de chat e, na maioria das vezes, você recebe uma sintaxe válida.

Onde o Mermaid deixa a desejar

• Você não controla o layout. O Mermaid posiciona os nós automaticamente. Adicione uma conexão e a imagem pode se reorganizar sozinha; passando de algumas dezenas de nós, fica difícil de ler.
• Diffs de texto escondem mudanças visuais. Uma mudança de uma linha em um pull request pode mover metade do diagrama, e quem revisa só vê a linha.
• O vocabulário é limitado para infraestrutura. As formas de fluxograma são genéricas. Existem tipos de diagrama mais novos para arquitetura e C4, mas eles são menos maduros que fluxogramas e diagramas de sequência.
• Quem não é da engenharia raramente edita. Product managers, designers e times de suporte conseguem ler o resultado, mas em geral não mexem no código-fonte.
• Não há uma sessão compartilhada ao vivo. Você edita texto no seu editor; não há cursores nem revisão ao vivo, e ninguém vê uma mudança chegar.

O que um canvas faz bem

• O layout é seu. A posição carrega significado: a borda de uma zona de confiança, o fluxo de uma requisição da esquerda para a direita, o cluster no meio.
• Nós tipados e frames. Em um canvas como o Archboard, um Service do Kubernetes ou um contêiner C4 é um nó com portas, e namespaces ou VPCs são frames que abrigam o seu conteúdo.
• Todo mundo pode editar. Pessoas que nunca abrem o repositório ainda conseguem corrigir um rótulo ou adicionar uma nota.
• Colaboração e compartilhamento ao vivo. Várias pessoas, e também agentes de IA, editam ao mesmo tempo com cursores, e um link ao vivo ou um embed mantém todo leitor na versão atual.

Onde um canvas deixa a desejar

• Ele se distancia do código se atualizá-lo não fizer parte do seu fluxo de trabalho. Por padrão, um canvas não está no pull request.
• Alguns formatos são opacos. Um PNG ou um arquivo proprietário não pode ser comparado por diff nem gerado. O Archboard atenua isso com exportação JSON e um JSON Schema publicado, mas um documento JSON ainda não é um bloco Markdown de dez linhas.
• Ele exige uma ferramenta. Leitores podem ver um link de compartilhamento sem conta, mas quem edita precisa de uma.

Uma tabela de decisão

O padrão: o Mermaid vence quando o diagrama pertence a uma mudança e vive no código. Um canvas vence quando o diagrama pertence ao time e sobrevive a qualquer mudança isolada.

O mesmo sistema, dos dois jeitos

Aqui está um sistema pequeno em Mermaid:

flowchart LR
  user([Customer]) -->|HTTPS| web
  subgraph shop [Online shop]
    web[Web app] -->|JSON| api[Orders API]
    api -->|SQL| db[(Orders DB)]
    api -->|OrderPlaced| q[[order-events]]
    q --> worker[Email worker]
  end
  worker -->|SMTP| mail[Email provider]

Ele é legível, gera diffs limpos e o GitHub o renderiza. Agora, o mesmo fluxograma em um canvas. Nós o passamos a um agente de IA conectado ao Archboard via MCP, com um mapeamento dos ids do Mermaid para tipos de nó: user para uma pessoa C4, web, api e worker para contêineres C4, db para Postgres, q para um Tópico, mail para um sistema externo. O agente desenhou tudo em um passo, e um segundo passo organizou o diagrama em duas linhas:

O subgraph virou um frame, os nós viraram nós tipados com portas, e o resultado é um ponto de partida que agora você pode organizar, anotar e compartilhar como qualquer outro diagrama.

Use os dois, de propósito

Uma divisão que funciona para a maioria dos times:

1. Mermaid para diagramas que pertencem a uma mudança: diagramas de sequência em documentos de design e pull requests, máquinas de estados ao lado do código, fluxogramas pequenos em READMEs.
2. Um canvas para diagramas que pertencem ao time: visões gerais de sistemas, infraestrutura, revisões de segurança, onboarding.
3. Conecte os dois. Comece pelo Mermaid quando você já o tiver: um agente conectado ao Archboard via MCP pode transformar um fluxograma Mermaid em um diagrama de canvas com tipos de nó reais. Exporte o canvas como JSON para o repositório quando quiser que ele seja revisado junto com o código, e coloque no README um link para o diagrama ao vivo.

Perguntas frequentes

Posso colar Mermaid no editor do Archboard? Diretamente, ainda não. Um agente de IA conectado via MCP pode desenhar um fluxograma Mermaid, incluindo subgraphs, como um diagrama de canvas com tipos de nó reais. Outros tipos de diagrama do Mermaid, como diagramas de sequência, não são convertidos.

Um diagrama de canvas aparece em pull requests? Não sozinho. Exporte-o como JSON ou SVG para o repositório se quiser que ele seja revisado junto com o código, ou coloque no pull request um link para o diagrama ao vivo.

Diagramas como código estão sempre mais atualizados? Só se alguém os atualizar. Um bloco Mermaid em que ninguém mexe fica desatualizado tão rápido quanto um canvas; a diferença é que ele fica mais perto da mudança que deveria atualizá-lo.

E o PlantUML ou o Structurizr? Os mesmos trade-offs. O PlantUML é forte em UML e diagramas de sequência; o Structurizr foi feito para modelos C4 como código. Escolha pensando em quem edita o diagrama e por quanto tempo ele precisa viver.

Com qual dos dois os assistentes de IA lidam melhor? Com os dois. Assistentes escrevem Mermaid com fluência e, via MCP, um agente também pode editar um canvas diretamente, onde as pessoas veem a mudança ao vivo e podem desfazê-la.

Comece grátis — um assento, sem cartão de crédito.