architecture-diagrams-library

O problema que este repositório resolve não é desenhar — é manter o desenho verdadeiro depois que a arquitetura muda. Um diagrama que existe só como PNG exportado de uma ferramenta visual perde a fonte na primeira troca de máquina, não tem diff e ninguém revisa. Seis meses depois, o documento de arquitetura mostra três filas SQS onde já existem cinco e um Lambda que foi aposentado.

Eu apliquei ao diagrama a mesma disciplina que se aplica a infraestrutura: fonte em texto, num repositório, com pull request. Um .mmd do Mermaid ou um .puml do PlantUML cabe num code review, mostra linha a linha o que mudou e pode ser renderizado pelo pipeline de documentação sem intervenção humana. Quando alguém troca EventBridge por SNS/SQS num ADR, a mudança no diagrama aparece no mesmo PR que a mudança na decisão.

O que o repositório é: um catálogo curado dessas fontes, organizado por tipo (referência AWS, camadas do C4, processo BPMN, topologia event-driven, sequência, estado), mais um frontend em Next.js 16 que renderiza e publica tudo. O que ele não é: uma ferramenta nova de diagramação. Os renderizadores são os de sempre — Mermaid, PlantUML e a biblioteca diagrams em Python — o valor está na curadoria e no fluxo de revisão.

Há duas metades com responsabilidades separadas. As fontes: arquivos de texto em três linguagens de diagrama. Mermaid cobre a maioria — C4 com a sintaxe C4Context/C4Container, sequência, estado e fluxogramas para event-driven — porque renderiza no próprio GitHub e em quase todo gerador de documentação sem plugin. PlantUML entra onde o Mermaid fica curto, principalmente sequências longas com grupos e notas. A biblioteca diagrams em Python fica reservada para arquiteturas AWS onde o ícone oficial do serviço facilita a leitura por quem não é engenheiro.

O frontend: uma aplicação Next.js 16 (App Router, React 19, TypeScript 5, Tailwind CSS 4) em frontend/ que lê as fontes, renderiza e publica o catálogo. Roda na Vercel; o DNS de diagrams.moretes.com é gerenciado no Cloudflare.

A esteira: quatro workflows no GitHub Actions — CI, Frontend, Vercel e Security. O CI valida as fontes no PR; o Security varre dependências; o Frontend constrói o site; o deploy segue para a Vercel. O detalhe que importa: a validação acontece antes do merge, então um .mmd com sintaxe quebrada não chega a main — ele quebra no PR, onde alguém está olhando. Isso é a diferença entre um catálogo que se mantém e uma pasta de arquivos que ninguém confia.

Os documentos operacionais estão no próprio repositório: docs/architecture.md para o desenho do sistema, SETUP.md para o ambiente, OPERATIONS.md para o dia a dia e CONTRIBUTING.md para quem quer adicionar um diagrama.

O caso mais comum não é abrir o site — é abrir um ADR. Quando escrevo uma decisão sobre, digamos, orquestração com Step Functions contra coreografia com EventBridge, cada opção ganha um diagrama de sequência ou de topologia colado do catálogo e ajustado com os nomes reais do domínio. O revisor vê a opção A e a opção B lado a lado, no mesmo Markdown, com o mesmo estilo. Sem isso, cada arquiteto desenha na ferramenta que tem à mão e o comitê de arquitetura gasta os primeiros dez minutos decifrando legenda.

C4 em camadas, não de uma vez: o erro que mais vejo é um único diagrama tentando ser Context e Component ao mesmo tempo. O catálogo separa as quatro camadas em arquivos distintos justamente para que o Context caiba numa tela e o Component possa ser detalhado sem poluir o que o stakeholder de negócio precisa ver.

BPMN ao lado do técnico: quando o processo de negócio e a topologia de eventos vivem no mesmo repositório, a divergência entre eles vira um diff. Um passo de aprovação que existe no BPMN e não tem evento correspondente na topologia é um bug de desenho detectável em revisão — antes de virar um bug de produção às 2h da manhã.

O custo que este repositório reduz não é o de desenhar o primeiro diagrama — é o de manter cinquenta diagramas verdadeiros ao longo de anos, com times que mudam.