# architecture-diagrams-library Diagramas de arquitetura como código — AWS, C4, BPMN e event-driven, versionados e revisáveis. - 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/fernandofatech/architecture-diagrams-library - Language: TypeScript - Topics: - Stars: 0 - Forks: 0 - Updated: 2026-05-16T01:43:36Z --- Um catálogo curado de diagramas de arquitetura escritos como código — AWS, C4, BPMN, event-driven, sequência e estado — servidos por uma aplicação Next.js e mantidos sob controle de versão para que cada mudança seja revisável em pull request. ## Por que diagramas como código Um diagrama que existe apenas como captura de tela envelhece rapidamente. Quando a infraestrutura muda, a imagem não muda junto — e ninguém sabe quando ela ficou desatualizada. Tratar diagramas como código resolve esse problema: cada arquivo Mermaid, PlantUML ou `diagrams` (Python) vive no repositório, passa por CI, aparece em diffs e pode ser embutido em ADRs, RFCs e pipelines de documentação. Essa disciplina não é nova no mundo de infraestrutura — Terraform e CloudFormation já tornaram a infraestrutura declarativa e auditável. O mesmo raciocínio se aplica às representações visuais dessa infraestrutura. Se um engenheiro altera uma topologia de event-driven e não atualiza o diagrama correspondente, o PR fica incompleto. Com fontes versionadas, a revisão do diagrama faz parte do processo natural de revisão de código. O repositório cobre as camadas que aparecem com mais frequência no meu trabalho diário: arquiteturas de referência AWS, modelos C4 em quatro níveis, fluxos de processo BPMN, topologias de mensageria (EventBridge, SNS/SQS, Kafka) e diagramas de sequência e estado para documentar comportamento em tempo de execução. ## O que está incluído - **Arquiteturas AWS** renderizadas com Mermaid e a biblioteca `diagrams` (Python) — prontas para copiar em documentação técnica. - **C4 Model** em quatro camadas (Context, Container, Component, Code) para comunicar arquitetura em diferentes níveis de detalhe. - **BPMN** para fluxos de processo de negócio — útil quando a audiência inclui stakeholders não técnicos. - **Topologias event-driven** cobrindo EventBridge, SNS/SQS e Kafka com ênfase em padrões de fan-out e roteamento. - **Diagramas de sequência e estado** via Mermaid e PlantUML para documentar comportamento em tempo de execução e máquinas de estado. - **Snippets reutilizáveis** prontos para embutir em ADRs e RFCs, com CI (GitHub Actions) e deploy automático no Vercel. ## Como o repositório está organizado Fontes de diagrama versionadas alimentam um frontend Next.js que é testado em CI e publicado automaticamente no Vercel. ### ✍️ Diagram Sources - Mermaid .mmd files (storage) - PlantUML .puml files (storage) - diagrams (Python) .py files (storage) ### ⚙️ CI Pipeline - GitHub Actions ci.yml (ci) - GitHub Actions security.yml (security) - GitHub Actions frontend.yml (ci) ### 💻 Frontend - Next.js 16 App Router (frontend) - Tailwind CSS 4 + React 19 (frontend) ### ☁️ Hosting - Vercel diagrams.moretes.com (edge) - Cloudflare DNS (network) ### 👤 Visitor - Portfolio visitor browser (user) ### Fluxos - mermaid -> nextjs: importado - plantuml -> nextjs: importado - diagrams -> nextjs: importado - nextjs -> tailwind: estilizado por - ci -> nextjs: lint + build - security -> nextjs: scan - frontend_ci -> vercel: deploy - cloudflare -> vercel: DNS → origin - visitor -> cloudflare: HTTPS ## Stack técnica e decisões de design O frontend é construído com Next.js 16 (App Router), React 19 e TypeScript 5. Tailwind CSS 4 cuida da estilização sem adicionar dependências de componentes pesadas. A escolha do Next.js é pragmática: renderização estática para as páginas de diagrama significa que o Vercel serve HTML pré-gerado, sem cold starts relevantes para visitantes do portfólio. As fontes dos diagramas usam três ferramentas complementares. **Mermaid** é a escolha padrão para diagramas de sequência, estado e fluxos simples — a sintaxe é legível diretamente no GitHub e não exige tooling extra para renderizar em Markdown. **PlantUML** entra para diagramas C4 e casos onde a expressividade do Mermaid não é suficiente. A biblioteca **`diagrams`** (Python) é usada para arquiteturas AWS onde ícones oficiais importam para a audiência. Três workflows de GitHub Actions cobrem o ciclo de vida: `ci.yml` roda lint e build a cada push, `frontend.yml` dispara o deploy no Vercel em merges para a branch principal, e `security.yml` executa varreduras de segurança de forma assíncrona. O DNS é gerenciado pelo Cloudflare, que serve como camada de proxy e proteção na frente do Vercel. Toda a configuração operacional está documentada em `OPERATIONS.md` e `SETUP.md`. ## Rodando localmente 1. **Clone o repositório** — Use `git clone https://github.com/fernandofatech/architecture-diagrams-library.git` e entre no diretório criado. 2. **Instale as dependências do frontend** — Entre na pasta `frontend` e execute `npm install`. Node.js 18+ é recomendado para compatibilidade com Next.js 16. 3. **Inicie o servidor de desenvolvimento** — Execute `npm run dev` dentro de `frontend`. O servidor sobe em `http://localhost:3000` com hot reload. 4. **Consulte a documentação operacional** — Para configuração de variáveis de ambiente, deploy e procedimentos de segurança, leia `OPERATIONS.md` e `SETUP.md` na raiz do repositório. 5. **(Opcional) Gere diagramas Python localmente** — Os arquivos `.py` que usam a biblioteca `diagrams` requerem Python 3 e Graphviz instalados. Execute `pip install diagrams` e depois `python nome_do_diagrama.py` para gerar as imagens. _Sequência completa de instalação e execução local_ ```bash # Clone git clone https://github.com/fernandofatech/architecture-diagrams-library.git cd architecture-diagrams-library # Frontend cd frontend npm install npm run dev # → http://localhost:3000 # (Optional) Python diagrams — requires Graphviz pip install diagrams python path/to/diagram.py ``` > **Snippets prontos para ADRs e RFCs:** Um dos usos práticos do repositório é como biblioteca de referência: em vez de desenhar um diagrama de fan-out SNS/SQS do zero em cada novo projeto, copio o snippet correspondente, ajusto os nomes dos recursos e o embutido diretamente no ADR. Isso reduz o tempo de documentação e garante consistência visual entre projetos. ## Perguntas frequentes ### Posso usar os diagramas nos meus próprios projetos? Sim. A licença é MIT. Atribuição é apreciada mas não obrigatória. ### Preciso de Python para usar o repositório? Não para o frontend. Python e Graphviz são necessários apenas se você quiser regenerar localmente os diagramas `.py` que usam a biblioteca `diagrams`. Os diagramas Mermaid e PlantUML funcionam sem Python. ### Como contribuir com um novo diagrama? Consulte `CONTRIBUTING.md` na raiz do repositório. O fluxo padrão é fork → branch → PR com o arquivo fonte versionado e, se aplicável, a imagem gerada. ### Por que Next.js para um catálogo de diagramas? O App Router com geração estática entrega páginas pré-renderizadas sem custo de servidor, o que é adequado para um portfólio público. Também permite adicionar interatividade (filtros, busca) sem mudar de stack. ## Para quem é este repositório Este repositório é útil em dois contextos distintos. Primeiro, como portfólio técnico: visitantes que avaliam meu trabalho podem ver não apenas os diagramas finais, mas as fontes versionadas, os workflows de CI e as decisões de stack — o que diz mais sobre prática de engenharia do que uma imagem estática. Segundo, como biblioteca de referência reutilizável: arquitetos e engenheiros que trabalham com AWS, event-driven ou C4 podem usar os snippets diretamente em seus próprios ADRs e documentações, adaptando nomes e topologias conforme necessário. Não é um framework ou uma ferramenta de geração de diagramas — é uma coleção curada com infraestrutura de publicação. Se você busca uma ferramenta de diagramação interativa, Mermaid Live ou draw.io são mais adequados. Se você busca exemplos concretos e versionados de padrões de arquitetura que podem entrar diretamente em documentação técnica, este repositório cobre esse espaço. ## Referências e links - [fernandofatech/architecture-diagrams-library — GitHub](https://github.com/fernandofatech/architecture-diagrams-library) - [Live site — diagrams.moretes.com](https://diagrams.moretes.com) - [Project architecture docs](https://github.com/fernandofatech/architecture-diagrams-library/blob/main/docs/architecture.md) - [Mermaid — diagramming and charting tool](https://mermaid.js.org) - [diagrams — diagram as code for cloud infrastructure (Python)](https://diagrams.mingrammer.com) - [PlantUML](https://plantuml.com) - [C4 Model for software architecture](https://c4model.com) - [Next.js App Router documentation](https://nextjs.org/docs/app) ## Links - [GitHub repository](https://github.com/fernandofatech/architecture-diagrams-library)