# aws-architecture-studio ADR, diagrama Mermaid e padrões AWS num estúdio só, open source e sem backend - URL: https://fernando.moretes.com/open-source/aws-architecture-studio - Markdown: https://fernando.moretes.com/open-source/aws-architecture-studio/guide.md?lang=pt - GitHub: https://github.com/fernando-moretes/ref-aws-architecture-studio - Language: TypeScript - Topics: - Stars: 0 - Forks: 0 - Updated: 2026-09-29T16:19:24Z --- AWS Architecture Studio é uma aplicação Next.js 16 que junta, numa ferramenta só, os dois artefatos que mais consomem a semana de um arquiteto: o registro de decisão (ADR, no formato MADR) e o diagrama, ligados a seis padrões de referência e a um catálogo de mais de 37 serviços AWS. ## Por que esse repositório existe A pergunta que me levou a escrever isso não foi "como desenho mais rápido?". Foi outra: por que o ADR que escrevi há oito meses não bate com o diagrama que está no slide de hoje? Em toda equipe de arquitetura que acompanhei, decisão e diagrama nascem em ferramentas diferentes, em formatos diferentes, e envelhecem em ritmos diferentes. O ADR fica num wiki, o diagrama fica num arquivo binário de ferramenta de desenho, e a lista de serviços considerados fica na cabeça de quem estava na reunião. Seis meses depois ninguém sabe se o diagrama ainda representa a decisão. O custo disso não está em produzir o artefato. Está em mantê-lo coerente ao longo dos anos, e em quem herda o sistema e precisa reconstruir o porquê de cada escolha. O estúdio ataca isso de um jeito simples: - **ADR em Markdown:** sai como `.md`, entra no repositório do sistema e é versionado junto com o código. - **Diagrama como texto:** a saída é código Mermaid, que também vai para o Git e gera diff legível em pull request. - **Vocabulário comum:** os serviços do diagrama vêm do mesmo catálogo que descreve quando usar cada um e o que observar no preço. O objetivo é que decisão e diagrama virem documentação que acumula valor, e não slide que se joga fora depois da reunião. ## Os quatro módulos - **ADR Generator (`/adr`):** assistente em seis passos, aderente ao MADR, com preview em Markdown ao vivo, botão de copiar e download como `.md`. - **Diagram Builder (`/diagrams`):** você escolhe serviços do catálogo, liga nós com arestas e o Mermaid renderiza no navegador; o código-fonte sai pronto para copiar. - **Reference Patterns (`/patterns`):** seis padrões curados (web em 3 camadas, API serverless, data lake, microsserviços event-driven, SPA estática, ML em batch), cada um com diagrama, resumo de ADR, serviços, ponteiros do Well-Architected e notas de custo. - **AWS Catalog (`/services`):** mais de 37 serviços com descrição de uma linha, quando usar e observações de preço. ## Como as peças se conectam O fluxo de uso: o catálogo e os padrões alimentam o assistente de ADR e o construtor de diagramas; a saída de ambos é texto (Markdown e Mermaid) que vai para o repositório do seu sistema. ### ▲ Vercel: Next.js 16 App Router - /patterns 6 reference patterns (frontend) - /services 37+ AWS services (data) - /adr 6-step MADR wizard (frontend) - /diagrams node + edge builder (frontend) ### 🌐 Navegador: renderização / Browser: rendering - Markdown preview live (compute) - Mermaid 11 client-side render (compute) ### 📤 Saída / Output - adr.md copy / download (storage) - Mermaid source copy (storage) - Repo do sistema Git + PR review (external) ### Fluxos - architect -> patterns: parte de um padrão - architect -> adr: preenche a decisão - architect -> diagrams: desenha o fluxo - services -> diagrams: fornece os nós - services -> patterns: referenciado por - adr -> preview: renderiza ao vivo - diagrams -> mermaid: gera código Mermaid - preview -> md: exporta - mermaid -> src: exporta - md -> git: commit - src -> git: commit ## Como funciona por dentro A stack é deliberadamente curta: Next.js 16 com App Router, React 19, TypeScript 5, Tailwind CSS 4 e Mermaid 11. O deploy é na Vercel, com DNS pela Cloudflare. O código da aplicação mora em `frontend/`, e é dali que você roda tudo. Três escolhas definem o comportamento: **Mermaid renderiza no cliente.** O diagrama não passa por servidor de renderização nem por API de terceiros. O navegador recebe o texto e desenha o SVG. Isso deixa o custo de operação perto de zero e tira uma dependência de rede do caminho de quem está desenhando. **ADR segue o MADR.** O assistente de seis passos não inventa formato: contexto, opções consideradas, decisão e consequências entram na estrutura do Markdown Architectural Decision Records. Isso importa no dia em que o ADR precisar ser lido por alguém que nunca viu a ferramenta. **Saída é texto, não estado.** Pelo que o README descreve, o valor do estúdio está no que sai dele (`.md` e código Mermaid), não em uma base de dados interna. O padrão de arquitetura e o catálogo são conteúdo curado do próprio repositório, servidos pelas rotas `/patterns`, `/patterns/[slug]` e `/services`. A página de detalhe de cada padrão (`/patterns/[slug]`) é a que mais uso: ela junta, no mesmo lugar, o diagrama, o resumo da decisão, a lista de serviços, os pilares do Well-Architected que pesam ali e onde o custo costuma escapar. ## Instalar e usar 1. **Clone o repositório**: `git clone https://github.com/fernando-moretes/ref-aws-architecture-studio.git` e entre na pasta `frontend/`. A aplicação Next.js inteira está ali. 2. **Instale e suba o servidor de desenvolvimento**: `npm install` e depois `npm run dev`. Abra `http://localhost:3000`. Não há credencial AWS envolvida: nada aqui chama a sua conta. 3. **Comece por um padrão**: Em `/patterns`, escolha o mais próximo do seu caso (API serverless, data lake, event-driven). Leia o resumo de ADR e as notas de custo antes de desenhar qualquer coisa. 4. **Escreva a decisão em `/adr`**: Percorra os seis passos e acompanhe o Markdown no preview. Baixe o `.md` e salve em `docs/adr/` do repositório do sistema, numerado. 5. **Desenhe em `/diagrams` e versione o código**: Monte nós a partir do catálogo, ligue as arestas, copie o código Mermaid e cole dentro do próprio ADR ou num `.md` ao lado. GitHub e a maioria das wikis renderizam Mermaid direto. _Quickstart local, exatamente como no README_ ```bash git clone https://github.com/fernando-moretes/ref-aws-architecture-studio.git cd ref-aws-architecture-studio/frontend npm install npm run dev # open http://localhost:3000 ``` > **O download é o seu save:** O README não descreve persistência de rascunho nem conta de usuário. Trate o botão de download do ADR e o copiar do Mermaid como o único jeito de guardar o trabalho: fechou a aba antes de exportar, conte com refazer. ## O que ele não faz Vale ser explícito, porque é aqui que expectativa errada vira frustração. - **Não é ferramenta de desenho livre.** O Diagram Builder gera Mermaid, e Mermaid tem limites de layout. Para um diagrama de apresentação com posicionamento fino, ferramenta de desenho visual continua ganhando. - **Não lê a sua conta AWS.** Nada é descoberto a partir de recursos reais. O diagrama mostra o que você declara, não o que está rodando. - **Não calcula custo.** As notas de preço do catálogo e dos padrões apontam onde o custo costuma crescer; para número, use o AWS Pricing Calculator. - **O catálogo é curado, não completo.** São mais de 37 serviços, escolhidos pelo uso em arquitetura de soluções, não a lista inteira da AWS. Essas fronteiras são escolha, não falta de tempo: cada integração a mais seria uma dependência a manter, e o valor do estúdio está em produzir texto versionável com o mínimo de peças móveis. ## Perguntas frequentes ### Preciso de conta AWS para usar? Não. A aplicação roda local com `npm run dev` e não chama nenhuma API da AWS. O catálogo e os padrões são conteúdo do próprio repositório. ### O ADR gerado segue algum padrão? Segue o MADR (Markdown Architectural Decision Records). O arquivo `.md` funciona em qualquer repositório que já use esse formato, sem conversão. ### Posso editar o diagrama depois? Sim, porque a saída é código Mermaid. Você edita o texto direto no seu repositório; a ferramenta serve para chegar ao primeiro rascunho rápido, não para ser o lugar onde o diagrama mora. ### Qual a licença? MIT. Pode usar, adaptar o catálogo para o contexto da sua empresa e redistribuir mantendo o aviso de copyright. ## Referências - [GitHub: fernando-moretes/ref-aws-architecture-studio](https://github.com/fernando-moretes/ref-aws-architecture-studio) - [AWS Architecture Studio (produção)](https://studio.moretes.com) - [MADR: Markdown Architectural Decision Records](https://adr.github.io/madr/) - [Mermaid documentation](https://mermaid.js.org/) - [AWS Well-Architected Framework](https://aws.amazon.com/architecture/well-architected/) ## Para quem serve Use o estúdio quando você já versiona documentação junto com o código, quer ADR no formato MADR sem montar template à mão, e prefere diagrama como texto que passa por code review. Ele rende mais em equipe pequena de arquitetura ou plataforma que produz várias decisões por mês e perdeu o rastro entre ADR e diagrama. Não use se o entregável é um diagrama de apresentação com layout fino, ou se você precisa de inventário a partir de recursos reais: aí o problema é outro, e esta ferramenta não tenta resolvê-lo. ## Links - [GitHub repository](https://github.com/fernando-moretes/ref-aws-architecture-studio)