architecture-diagrams-library
Diagramas de arquitetura como código: AWS, C4, BPMN e eventos, revisáveis em PR
git clone https://github.com/fernando-moretes/ref-architecture-diagrams-library.gitOuvir guia
gerado ao ouvirGerado apenas no primeiro play
Com tecnologia Amazon Polly + OmniVoice
O Architecture Diagrams Library é um catálogo versionado de diagramas como código (AWS, C4, BPMN, topologias event-driven, sequência e estado) servido por um frontend Next.js 16, para que um desenho de arquitetura passe pelo mesmo pull request que a infraestrutura que ele representa.
Por que este repositório existe
A pergunta que importa num diagrama de arquitetura não é "ele está bonito?", é "ele ainda descreve o sistema que está em produção?". Na maioria dos times que vi, a resposta é não. O diagrama nasce como screenshot de uma ferramenta visual, é colado num ADR ou numa wiki e envelhece no primeiro refactor. Ninguém revisa a imagem, porque não existe diff de PNG que alguém consiga ler.
O custo disso não aparece no dia em que o desenho é feito. Aparece meses depois, quando alguém toma decisão de plantão olhando uma fila SQS que já foi trocada por EventBridge, ou quando a auditoria pede o fluxo de dados atualizado e o time precisa redesenhar tudo do zero.
Tratar diagrama como código resolve a parte mecânica do problema:
- Revisável: a mudança no desenho aparece no pull request, linha a linha, ao lado da mudança no Terraform.
- Diffável: dá para ver o que mudou entre duas versões sem abrir duas imagens lado a lado.
- Embutível: o mesmo fonte alimenta ADRs, RFCs e pipelines de documentação.
A disciplina que já aplicamos à infraestrutura deveria valer para a representação visual dela. Este repositório é o meu catálogo dessa disciplina: padrões que reuso em documentos de arquitetura, guardados em fonte e não em imagem.
O que o catálogo cobre
diagrams em Python.Do fonte ao documento
O fonte do diagrama vive no Git, passa por revisão e CI, e é publicado pelo frontend ou copiado como snippet para um ADR.
- Mermaid · AWS, C4, sequência, estado
- PlantUML · sequência e estado
- diagrams (Python) · AWS
- Pull request · diff do fonte
- GitHub Actions · CI, Frontend, Security
- Next.js 16 · App Router + Tailwind 4
- ADR / RFC · snippet colado
- Leitor · catálogo no navegador
Como funciona por dentro
O repositório tem duas metades com papéis diferentes.
O fonte dos diagramas: arquivos em Mermaid, PlantUML e diagrams (Python). Escolhi três formatos de propósito, porque cada um tem um custo de manutenção diferente. Mermaid renderiza direto no GitHub e na maioria dos geradores de documentação, então é o padrão para tudo que vai parar num ADR. PlantUML continua melhor para diagramas de sequência longos e máquinas de estado com muitas transições. A biblioteca diagrams gera desenhos AWS com os ícones oficiais, útil quando o público espera ver o ícone do serviço e não uma caixa com o nome.
O frontend: uma aplicação Next.js 16 com App Router, React 19, TypeScript 5 e Tailwind CSS 4, na pasta frontend/. É ela que apresenta o catálogo navegável, publicado na Vercel com DNS pela Cloudflare em diagrams.moretes.com.
A esteira: quatro workflows no GitHub Actions (CI, Frontend, Vercel e Security). O que eles validam em detalhe está em OPERATIONS.md e SETUP.md; não vou repetir aqui o que o repositório já documenta.
A consequência prática dessa divisão: para usar um diagrama num documento seu, você não precisa rodar o frontend. Basta abrir o fonte e copiar. O frontend existe para descoberta, não como dependência.
Instalar e usar
- 1
Clone o repositório
git clone https://github.com/fernando-moretes/ref-architecture-diagrams-library.gite entre na pasta. O README ainda aponta para o endereço antigofernandofatech/architecture-diagrams-library; o repositório atual mora na orgfernando-moretes. - 2
Suba o frontend local
cd frontend, depoisnpm installenpm run dev. É o mesmo catálogo publicado, rodando na sua máquina. - 3
Escolha o diagrama pelo público
C4 Context para quem decide, Container e Component para quem constrói, sequência para quem vai depurar o fluxo, BPMN para a área de negócio.
- 4
Copie o fonte, não a imagem
Cole o bloco Mermaid no seu ADR ou RFC. Assim o desenho entra no seu PR e passa a ter diff, que é o objetivo inteiro do repositório.
- 5
Contribua por pull request
Padrão novo ou correção segue
CONTRIBUTING.md. Licença MIT.
git clone https://github.com/fernando-moretes/ref-architecture-diagrams-library.git
cd ref-architecture-diagrams-library/frontend
npm install
npm run devDiagrama como código também apodrece
Versionar o fonte não garante que ele bata com produção, só torna a divergência visível. Se o PR que troca SQS por EventBridge não toca no diagrama, nada falha: o desenho fica errado em silêncio, agora com histórico no Git. A regra que funciona é tratar o diagrama como parte do definition of done da mudança de infraestrutura.
Perguntas frequentes
Preciso de Python para usar o catálogo?
Não para navegar nem para copiar Mermaid. Python só entra se você quiser regenerar os desenhos AWS feitos com a biblioteca diagrams.
Por que três formatos em vez de um só?
Porque cada um tem um ponto forte diferente: Mermaid renderiza no GitHub, PlantUML lida melhor com sequência longa e estado, diagrams traz os ícones oficiais da AWS. Padronizar em um só obrigaria a aceitar o ponto fraco dele em todo caso.
Posso usar os diagramas em documentos da minha empresa?
Sim, a licença é MIT. Mantenha o aviso de copyright se copiar trechos substanciais.
Referências
Para quem é
Use este catálogo quando você escreve ADRs ou RFCs com frequência, seu time revisa infraestrutura por pull request e você quer que o desenho tenha o mesmo ciclo de vida do código. Ele rende mais em times que já documentam em Markdown, porque o Mermaid cola sem conversão. Se a sua documentação vive numa ferramenta visual fora do Git e ninguém revisa diagrama em PR, o ganho é pequeno: o problema aí é de processo, não de formato.
Deep dives de arquitetura, AWS, IA e mercado: direto no seu email. Grátis.
Sem spam · cancele quando quiser