aws-architecture-studio

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.

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.

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.