# architecture-diagrams-library Diagramas de arquitetura como código: revisáveis em PR, com diff, sem screenshot que apodrece. - 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-08T20:37:25Z --- Um catálogo de diagramas de arquitetura escritos como código — AWS, C4, BPMN, event-driven, sequência e estado — com fonte versionada, revisão em pull request e um site Next.js que os publica em diagrams.moretes.com. ## Por que diagrama vira código 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. ## O que está no catálogo - **Arquiteturas AWS de referência:** renderizadas com Mermaid e com `diagrams` (Python), para quem precisa dos ícones oficiais dos serviços. - **C4 Model completo:** Context, Container, Component e Code — as quatro camadas, não só a primeira. - **Processos de negócio em BPMN:** o fluxo que o time de produto entende, ao lado do fluxo técnico. - **Topologias event-driven:** EventBridge, SNS/SQS e Kafka, com os padrões de fan-out e DLQ desenhados. - **Sequência e estado:** via Mermaid e PlantUML, para fluxos de autenticação, retry e máquinas de estado de saga. - **Snippets prontos para colar:** em ADRs, RFCs e documentos de arquitetura — o caso de uso mais frequente na prática. ## Do arquivo-fonte ao diagrama publicado O fluxo é o de qualquer código: PR, CI, deploy. O diagrama só existe publicado porque passou pela revisão. ### 📝 Fonte — diagrams as code - Mermaid .mmd — C4, sequência, estado (data) - PlantUML .puml — sequência, estado (data) - diagrams (Python) AWS com ícones oficiais (data) ### 🔧 GitHub Actions - CI lint + validação das fontes (ci) - Security scan de dependências (security) - Frontend build Next.js 16 (ci) ### ▲ Vercel — publicação - Catálogo Next.js App Router + React 19 (frontend) ### 🌐 Cloudflare — borda - DNS diagrams.moretes.com (network) ### Fluxos - author -> mermaid: pull request - author -> plantuml: pull request - author -> pydiagrams: pull request - mermaid -> ci: valida no PR - plantuml -> ci: valida no PR - pydiagrams -> ci: valida no PR - ci -> security: em paralelo - ci -> frontend: merge em main - frontend -> site: deploy - dns -> site: resolve para a Vercel - reader -> dns: navega e copia snippet ## Como o repositório funciona 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. ## Instalar e usar 1. **Clone o repositório** — `git clone https://github.com/fernando-moretes/ref-architecture-diagrams-library.git`. Use a URL nova da org `fernando-moretes`; os badges do README ainda apontam para `fernandofatech`, e o GitHub redireciona, mas redirecionamento não é lugar para depender em automação. 2. **Instale o frontend** — `cd frontend && npm install`. Exige Node 20 ou superior — Next.js 16 não constrói em versões anteriores. O `SETUP.md` lista o que mais o ambiente precisa. 3. **Rode o catálogo local** — `npm run dev` sobe o site em `http://localhost:3000`. Navegue por tipo de diagrama e abra qualquer item para ver a fonte ao lado da renderização. 4. **Copie o snippet para o seu ADR** — Cada diagrama é um bloco de texto. Cole o Mermaid dentro de um fence ```mermaid no Markdown do ADR e o GitHub renderiza na hora, sem build. PlantUML e `diagrams` precisam do renderizador correspondente na sua esteira de docs. 5. **Adicione ou corrija um diagrama por PR** — Siga o `CONTRIBUTING.md`: um arquivo-fonte por diagrama, no diretório da categoria. O CI valida a sintaxe no PR; um diagrama quebrado não passa. Não edite o PNG — ele não existe como fonte de verdade aqui. _Quickstart: do clone ao catálogo rodando, mais a renderização local das três linguagens_ ```bash # 1. Clone (URL nova da org) git clone https://github.com/fernando-moretes/ref-architecture-diagrams-library.git cd ref-architecture-diagrams-library # 2. Frontend do catálogo (Next.js 16 — Node >= 20) cd frontend npm install npm run dev # http://localhost:3000 # 3. Renderizar uma fonte fora do site, se precisar do arquivo # Mermaid -> SVG npx -y @mermaid-js/mermaid-cli -i ../path/to/diagram.mmd -o diagram.svg # PlantUML -> PNG (precisa de Java + plantuml.jar no PATH ou via Docker) plantuml ../path/to/diagram.puml # diagrams (Python) -> PNG (precisa de Graphviz instalado) pip install diagrams python ../path/to/aws_reference.py ``` > **O renderizador Python tem uma dependência fora do pip:** A biblioteca `diagrams` chama o Graphviz por baixo. `pip install diagrams` termina com sucesso e o `python arquivo.py` falha com `ExecutableNotFound: dot` — a mensagem aparece só na primeira execução, não na instalação. Instale o Graphviz pelo gerenciador do sistema (`brew install graphviz`, `apt install graphviz`) antes de tentar renderizar as arquiteturas AWS. ## Como eu uso isto no trabalho de arquitetura 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. ## Perguntas frequentes ### Preciso rodar o frontend para usar os diagramas? Não. As fontes são arquivos de texto no repositório; você pode clonar, copiar o `.mmd` ou `.puml` e colar no seu documento sem instalar nada do Next.js. O site é a vitrine navegável, não um pré-requisito. ### Por que três linguagens de diagrama em vez de uma? Porque nenhuma cobre tudo bem. Mermaid renderiza nativamente no GitHub e é a escolha padrão. PlantUML lida melhor com sequências longas e agrupamentos. `diagrams` em Python é a única das três com os ícones oficiais da AWS, o que muda a leitura para audiência não técnica. Use Mermaid quando puder, as outras duas quando precisar. ### Posso usar os diagramas em material da minha empresa? Sim — a licença é MIT. Copie, adapte, mude os nomes. O que a licença não faz é garantir que o diagrama descreve a sua arquitetura: ele é ponto de partida, e a revisão com quem opera o sistema continua sendo sua. ## Referências - [fernando-moretes/ref-architecture-diagrams-library (GitHub)](https://github.com/fernando-moretes/ref-architecture-diagrams-library) - [Architecture Diagrams Library — catálogo em produção](https://diagrams.moretes.com) - [Mermaid — C4 diagram syntax](https://mermaid.js.org/syntax/c4.html) - [PlantUML — sequence diagrams](https://plantuml.com/sequence-diagram) - [diagrams — Diagram as Code (Python)](https://diagrams.mingrammer.com/) - [C4 model](https://c4model.com/) ## Para quem é Use este repositório quando você escreve ADRs ou RFCs com frequência, quando o time revisa arquitetura em pull request e quando os diagramas do seu wiki já divergiram do que roda em produção pelo menos uma vez. Ele vale menos se o seu fluxo de documentação não passa por Git — a revisão em PR é o mecanismo inteiro, não um detalhe. Comece pelo Mermaid, cole o primeiro snippet no próximo ADR e só instale Graphviz e Java quando um stakeholder pedir o ícone oficial ou uma sequência que o Mermaid não desenha. ## Links - [GitHub repository](https://github.com/fernando-moretes/ref-architecture-diagrams-library)