aws-architecture-studio
ADR em MADR, diagrama em Mermaid e catálogo AWS num só app — sem slide descartável
git clone https://github.com/fernando-moretes/ref-aws-architecture-studio.gitOuvir guia
gerado ao ouvirGerado apenas no primeiro play
Com tecnologia Amazon Polly + OmniVoice
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
.md.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.
- /adr · wizard MADR 6 passos
- /diagrams · nós + arestas → Mermaid
- /patterns/[slug] · 6 padrões curados
- /services · catálogo 37+ serviços
- Mermaid 11 · render client-side
- ADR .md · copiar / baixar
- Fonte Mermaid · copiar
- ci / frontend / security · workflows
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 emfrontend/; a raiz do repo guarda docs e workflows. - 2
Instale e suba o dev server
npm install && npm run dev, depois abrahttp://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
.mde faça commit emdocs/adr/NNNN-titulo.mdno 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.
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 + pricingO 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
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.
Deep dives de arquitetura, AWS, IA e mercado — direto no seu email. Grátis.
Sem spam · cancele quando quiser