# architecture-diagrams-library Diagramas de arquitetura como código: AWS, C4, BPMN e eventos, revisáveis em PR - URL: https://fernando.moretes.com/open-source/architecture-diagrams-library - Markdown: https://fernando.moretes.com/open-source/architecture-diagrams-library/guide.md?lang=pt - GitHub: https://github.com/fernando-moretes/ref-architecture-diagrams-library - Language: TypeScript - Topics: - Stars: 0 - Forks: 0 - Updated: 2026-09-29T16:16:30Z --- 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 - **Arquiteturas AWS:** desenhos de referência renderizados com Mermaid e com a biblioteca `diagrams` em Python. - **C4 Model:** as quatro camadas, Context, Container, Component e Code. - **BPMN:** fluxos de processo de negócio, para quando a conversa é com a área e não com o time de plataforma. - **Event-driven:** topologias com EventBridge, SNS/SQS e Kafka. - **Sequência e estado:** diagramas em Mermaid e PlantUML. - **Snippets:** trechos prontos para colar em ADRs, RFCs e documentos de arquitetura. ## 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. ### 🔧 Fonte versionado - Mermaid AWS, C4, sequência, estado (data) - PlantUML sequência e estado (data) - diagrams (Python) AWS (data) ### 🔐 Revisão: GitHub - Pull request diff do fonte (ci) - GitHub Actions CI, Frontend, Security (ci) ### ▲ Vercel: publicação - Next.js 16 App Router + Tailwind 4 (frontend) ### 📤 Consumo - ADR / RFC snippet colado (external) - Leitor catálogo no navegador (user) ### Fluxos - author -> mermaid: escreve - author -> plantuml: escreve - author -> pydiagrams: escreve - mermaid -> pr: commit - pr -> actions: dispara - actions -> next: build e deploy - next -> reader: serve o catálogo - mermaid -> adr: snippet copiado ## 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](https://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.git` e entre na pasta. O README ainda aponta para o endereço antigo `fernandofatech/architecture-diagrams-library`; o repositório atual mora na org `fernando-moretes`. 2. **Suba o frontend local**: `cd frontend`, depois `npm install` e `npm 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. _Quickstart do catálogo local_ ```bash git clone https://github.com/fernando-moretes/ref-architecture-diagrams-library.git cd ref-architecture-diagrams-library/frontend npm install npm run dev ``` > **Diagrama 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 - [GitHub: fernando-moretes/ref-architecture-diagrams-library](https://github.com/fernando-moretes/ref-architecture-diagrams-library) - [Architecture Diagrams Library (catálogo ao vivo)](https://diagrams.moretes.com) - [Mermaid](https://mermaid.js.org) - [PlantUML](https://plantuml.com) - [Diagrams (Python)](https://diagrams.mingrammer.com) - [C4 Model](https://c4model.com) ## 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. ## Links - [GitHub repository](https://github.com/fernando-moretes/ref-architecture-diagrams-library)