# aws-architecture-studio ADR em MADR, diagrama em Mermaid e catálogo AWS num só app — sem slide descartável - 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-08T20:38:14Z --- O AWS Architecture Studio é uma aplicação Next.js 16 open-source que reúne os dois artefatos que consomem a semana de um arquiteto de soluções — o registro de decisão e o diagrama — num único lugar, com um wizard de ADR em MADR com preview ao vivo, um construtor de diagramas AWS que renderiza Mermaid, seis padrões de referência curados e um catálogo de 37+ serviços com notas de preço. ## O que está dentro - **ADR Generator:** wizard em seis passos, compatível com MADR, preview Markdown ao vivo, copiar e baixar como `.md`. - **Diagram Builder:** escolhe serviços do catálogo, desenha nós e arestas, renderiza Mermaid ao vivo e copia o fonte — o diagrama vira texto versionável, não imagem. - **Reference Patterns:** seis padrões (3-tier web, API serverless, data lake, microsserviços event-driven, SPA estática, batch ML), cada um com diagrama, resumo de ADR, serviços, ponteiros do Well-Architected e notas de custo. - **AWS Catalog:** 37+ serviços com uma linha de descrição, quando usar e nota de preço — o suficiente para decidir, não para substituir a documentação. - **Stack:** Next.js 16 (App Router), React 19, TypeScript 5, Tailwind CSS 4, Mermaid 11 renderizado no cliente; deploy na Vercel com DNS via Cloudflare. ## Por que existe Depois de anos revisando arquiteturas, o padrão que mais me incomoda não é decisão errada — é decisão sem registro. O diagrama vive num slide que ninguém encontra seis meses depois, e o motivo de ter escolhido SQS em vez de Kinesis morreu na cabeça de quem saiu da equipe. O custo disso não aparece no dia da decisão; aparece na auditoria, na migração ou no incidente às 2h da manhã, quando alguém precisa saber *por que* o sistema é assim. O Studio ataca esse problema com uma aposta simples: se produzir o ADR e o diagrama for mais rápido que abrir o PowerPoint, as pessoas produzem. O wizard força a estrutura do MADR — contexto, opções consideradas, decisão, consequências — para que o registro saia comparável entre times. O construtor de diagramas devolve fonte Mermaid, que cabe num pull request e sofre `diff` como qualquer outro arquivo. A ligação entre as duas coisas e o catálogo de serviços é o que transforma artefato descartável em documentação que se acumula. Cada padrão de referência já traz o diagrama, o resumo de decisão, a lista de serviços e o custo aproximado no mesmo lugar — o ponto de partida para o ADR do seu caso, não o ponto final. ## Como as peças se encaixam Tudo roda no browser: não há backend, banco ou credencial AWS. O catálogo alimenta o construtor de diagramas e os padrões; o wizard e o construtor devolvem texto que você leva para o repositório. ### ▲ Vercel — Next.js 16 App Router - /adr wizard MADR 6 passos (frontend) - /diagrams nós + arestas → Mermaid (frontend) - /patterns/[slug] 6 padrões curados (frontend) - /services catálogo 37+ serviços (data) - Mermaid 11 render client-side (compute) ### 📤 Saída — o que você leva embora - ADR .md copiar / baixar (storage) - Fonte Mermaid copiar (storage) ### 🔧 GitHub Actions — CI - ci / frontend / security workflows (ci) ### Fluxos - architect -> adr: preenche passos - architect -> diagrams: escolhe serviços - architect -> patterns: navega por categoria - services -> diagrams: alimenta a paleta - services -> patterns: lista de serviços - diagrams -> mermaid: fonte gerado - patterns -> mermaid: diagrama do padrão - adr -> md: preview ao vivo - mermaid -> mmd: copiar fonte - ci -> adr: build + security a cada push ## Como funciona por dentro A aplicação inteira vive em `frontend/` e é um Next.js 16 com App Router e React 19. Não existe API própria, banco de dados nem chamada à AWS: o catálogo de serviços e os padrões de referência são dados estáticos no código, e o estado do wizard e do construtor de diagramas fica no cliente. Isso é uma decisão, não uma limitação — um tool de documentação que exige credencial para abrir é um tool que ninguém abre. **O wizard de ADR:** seis passos que mapeiam para as seções do MADR. A cada campo preenchido o preview Markdown é reconstruído ao vivo; o resultado sai por copiar ou por download como `.md`, pronto para o diretório `docs/adr/` do seu repositório. **O construtor de diagramas:** você seleciona serviços do catálogo como nós, liga as arestas e o app gera o fonte Mermaid. O Mermaid 11 renderiza no browser — nenhum servidor de render, nenhuma imagem para hospedar. O que você copia é texto, e texto é o que sobrevive a versionamento. **As rotas:** `/` (hero e padrões em destaque), `/adr`, `/diagrams`, `/patterns` com `/patterns/[slug]` para o detalhe, e `/services`. Tudo em TypeScript 5 com Tailwind CSS 4. **CI:** três workflows no GitHub Actions — `ci`, `frontend` e `security` — rodam a cada push. O deploy é na Vercel, com DNS na Cloudflare. Os documentos `OPERATIONS.md` e `SETUP.md` cobrem a operação; `CONTRIBUTING.md`, a contribuição. ## Instalar e usar 1. **Clone e entre no frontend** — `git clone https://github.com/fernando-moretes/ref-aws-architecture-studio.git && cd ref-aws-architecture-studio/frontend`. Toda a aplicação mora em `frontend/`; a raiz do repo guarda docs e workflows. 2. **Instale e suba o dev server** — `npm install && npm run dev`, depois abra `http://localhost:3000`. Não há variável de ambiente obrigatória nem credencial AWS — o app roda inteiro no browser. 3. **Escreva um ADR em `/adr`** — Percorra os seis passos — contexto, opções, decisão, consequências — acompanhando o preview. Ao terminar, baixe o `.md` e faça commit em `docs/adr/NNNN-titulo.md` no repositório do sistema, não no do Studio. 4. **Desenhe o diagrama em `/diagrams`** — Escolha os serviços do catálogo, ligue as arestas e copie o fonte Mermaid. Cole num bloco ```mermaid dentro do próprio ADR — o GitHub renderiza nativamente, e o diagrama passa a ser revisado no mesmo PR que a decisão. 5. **Comece por um padrão quando o caso for conhecido** — Se o sistema é uma API serverless ou um data lake, abra `/patterns/[slug]` primeiro: o diagrama, o resumo de ADR, os serviços e as notas de custo já estão lá. Adapte; não comece do zero. _Quickstart local — sem credencial AWS_ ```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 # /adr -> six-step MADR wizard, download .md # /diagrams -> pick services, copy Mermaid source # /patterns -> six reference patterns with cost notes # /services -> 37+ AWS services, when-to-use + pricing ``` > **O que o catálogo não é:** As notas de preço e os ponteiros do Well-Architected no catálogo e nos padrões são orientação para a conversa de decisão, não cotação. Preço da AWS muda por região e por mês; antes de colocar um número num ADR que alguém vai auditar, confira na calculadora de preços da AWS e registre a data da consulta no próprio documento. ## Perguntas frequentes ### Preciso de conta AWS para usar? Não. O app não chama nenhuma API da AWS. Ele produz Markdown e Mermaid; o que você faz com eles depois é seu. ### O ADR segue algum formato padrão? Sim, MADR (Markdown Architectural Decision Records). Escolhi MADR porque ele já é o formato que a maioria dos times aceita em revisão sem discussão — e formato que gera discussão não é adotado. ### Por que Mermaid e não uma ferramenta de desenho? Porque Mermaid é texto. Entra no PR, sofre `diff`, renderiza no GitHub sem plugin e não depende de licença de ninguém. Uma imagem exportada de ferramenta de desenho é um artefato que ninguém consegue revisar linha a linha. ### Posso adicionar meus próprios padrões ou serviços? Sim — os dados são estáticos no código, sob licença MIT. Faça um fork, edite o catálogo ou os padrões e abra um PR seguindo o `CONTRIBUTING.md` se achar que vale compartilhar. ## Referências - [fernando-moretes/ref-aws-architecture-studio (GitHub)](https://github.com/fernando-moretes/ref-aws-architecture-studio) - [MADR — Markdown Architectural Decision Records](https://adr.github.io/madr/) - [Mermaid — diagramming and charting tool](https://mermaid.js.org/) - [AWS Well-Architected Framework](https://docs.aws.amazon.com/wellarchitected/latest/framework/welcome.html) - [AWS Pricing Calculator](https://calculator.aws/) ## Quando usar Use o Studio quando: o time já concordou em registrar decisões mas ninguém registra porque o formato é fricção; você quer diagramas que passem por revisão de código em vez de morrer em slide; e o caso cabe em um dos seis padrões ou parte deles. Não use como fonte de preço nem como substituto da documentação da AWS — o catálogo existe para decidir mais rápido, não para cotar. E se o seu time já tem um formato de ADR consolidado e ferramenta de diagrama com histórico, o ganho aqui é pequeno; o valor está em tirar do zero quem ainda não tem nenhum dos dois. ## Links - [GitHub repository](https://github.com/fernando-moretes/ref-aws-architecture-studio)