# aws-architecture-studio Estúdio open-source para arquitetos AWS: ADRs, diagramas Mermaid e catálogo de serviços em um só lugar. - 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/fernandofatech/aws-architecture-studio - Language: TypeScript - Topics: - Stars: 0 - Forks: 0 - Updated: 2026-05-16T02:08:17Z --- AWS Architecture Studio é uma aplicação Next.js 16 que desenvolvi para consolidar os dois artefatos que arquitetos produzem com mais frequência — Architecture Decision Records e diagramas de sistema — junto a um catálogo de serviços AWS e seis padrões de referência prontos para uso, tudo rodando no navegador sem necessidade de backend. ## Por que construí isso Toda semana gasto um tempo considerável produzindo decision records e diagramas de arquitetura. As ferramentas disponíveis são genéricas demais (templates do Confluence, quadros em branco no Miro) ou pesadas demais (suítes de modelagem enterprise). Queria algo opinativo, rápido e com escopo restrito ao trabalho com AWS. O wizard de ADR segue o formato MADR — o template leve mais adotado — e guia cada seção com um formulário estruturado, renderizando Markdown ao vivo enquanto você digita para que você veja o documento final antes de copiar ou baixar. O construtor de diagramas permite selecionar serviços do mesmo catálogo usado em toda a aplicação, desenhar arestas entre eles e obter o código Mermaid válido para colar em qualquer arquivo Markdown ou wiki. A seção de padrões de referência é a que mais uso em conversas com clientes: seis arquiteturas AWS canônicas (web 3 camadas, API serverless, data lake, microsserviços orientados a eventos, SPA estático, ML em batch), cada uma pré-configurada com diagrama, resumo de ADR, lista de serviços, indicadores do Well-Architected e estimativas de custo. Ter tudo isso em um lugar significa que consigo apresentar um ponto de partida concreto em segundos. ## O que a aplicação cobre - **Wizard de ADR** — formulário MADR em seis etapas com preview Markdown ao vivo, cópia e download em `.md`. - **Construtor de Diagramas** — selecione serviços AWS como nós, conecte-os com arestas e obtenha o código Mermaid renderizado instantaneamente. - **Padrões de Referência** — seis arquiteturas com diagramas, resumos de ADR, indicadores do Well-Architected e notas de custo. - **Catálogo de Serviços AWS** — mais de 37 serviços com descrições curtas, orientação de uso e notas de precificação. - **Totalmente client-side** — Next.js App Router, Mermaid 11 renderiza no navegador; sem chamadas a serviços externos. - **Três pipelines de CI** — workflows separados no GitHub Actions para build/lint, deploy frontend no Vercel e varredura de segurança. ## Estrutura da aplicação e fluxo de dados Tudo roda no navegador. O App Router do Next.js serve páginas estáticas ou renderizadas no servidor; o Mermaid renderiza diagramas no cliente. Não há API backend — os dados do catálogo e os padrões são empacotados em tempo de build. ### 👤 User - Architect browser (user) ### ☁️ Vercel Edge - Vercel CDN / Edge (edge) ### 💻 Next.js App - / Hero + Patterns (frontend) - /adr ADR Wizard (frontend) - /diagrams Diagram Builder (frontend) - /patterns Reference Patterns (frontend) - /services AWS Catalog (frontend) ### 📦 Bundled Data - Service Catalog 37+ services (data) - Pattern Definitions 6 architectures (data) ### 🔧 Client-side Rendering - Mermaid 11 Diagram renderer (compute) - Markdown Live preview (compute) ### 🔒 CI / Security - GitHub Actions CI + Security (ci) ### Fluxos - user -> vercel: Requisição HTTPS - vercel -> home: serve página - home -> adr: navegar - home -> diagrams: navegar - home -> patterns: navegar - home -> services: navegar - catalog -> diagrams: nós de serviço - catalog -> services: entradas do catálogo - patterndata -> patterns: definições de padrões - diagrams -> mermaid: renderizar grafo - adr -> mdpreview: renderizar preview - ci -> vercel: deploy no merge ## Executando localmente 1. **Clonar o repositório** — Execute `git clone https://github.com/fernandofatech/aws-architecture-studio.git` e entre no diretório do projeto. 2. **Instalar dependências** — A aplicação está no subdiretório `frontend/`. Execute `cd frontend && npm install`. Node 18+ é recomendado para coincidir com o runtime do Vercel. 3. **Iniciar o servidor de desenvolvimento** — Execute `npm run dev` dentro de `frontend/`. O Next.js inicia em `http://localhost:3000`. Hot reload está ativo; os diagramas Mermaid renderizam no navegador sem configuração adicional. 4. **Build para produção** — Execute `npm run build` e depois `npm start` para validar o bundle de produção localmente antes do deploy. O workflow de CI executa essa mesma sequência a cada push. 5. **Revisar documentação de operações e setup** — Consulte `OPERATIONS.md` para notas de deploy e `SETUP.md` para configuração por ambiente. `docs/architecture.md` cobre as decisões de design interno. _Setup local completo em quatro comandos_ ```bash git clone https://github.com/fernandofatech/aws-architecture-studio.git cd aws-architecture-studio/frontend npm install npm run dev # → http://localhost:3000 ``` ## Como os quatro módulos se encaixam A aplicação é intencionalmente coesa em vez de fracamente acoplada. Os mesmos dados do catálogo de serviços AWS que alimentam a página de consulta rápida `/services` são a fonte de verdade para o seletor de nós no construtor de diagramas. Quando você seleciona Lambda no construtor, está escolhendo do mesmo registro que exibe sua descrição, modelo de precificação e nota de uso na visão do catálogo. Essa consistência importa: evita a divergência que ocorre quando dados de catálogo e ferramentas de diagrama vivem em sistemas separados. Os padrões de referência funcionam de forma semelhante. Cada padrão em `/patterns/[slug]` é um objeto estruturado contendo uma definição de diagrama Mermaid, um resumo de ADR, uma lista de IDs de serviço que resolvem contra o catálogo, notas dos pilares do Well-Architected e observações de custo. Renderizar a página de detalhe de um padrão é apenas resolver essas referências — sem armazenamento de dados separado, sem API. O wizard de ADR em `/adr` é a parte mais interativa. Percorre seis seções (contexto, drivers de decisão, opções consideradas, resultado da decisão, consequências e status), mantém todo o estado no React e renderiza um documento Markdown compatível com MADR em tempo real. O resultado é um arquivo `.md` simples que você pode commitar diretamente no diretório `docs/decisions/` de um repositório — sem formato proprietário, sem lock-in. A configuração de CI reflete como trato projetos de portfólio: três workflows separados no GitHub Actions (CI geral, build frontend e deploy no Vercel, e varredura de segurança) executam de forma independente para que uma falha de lint não bloqueie um relatório de segurança e vice-versa. > **Usando o output do ADR em um projeto real:** O arquivo `.md` baixado já é compatível com MADR. Coloque-o em `docs/decisions/` no seu repositório, numere-o sequencialmente (ex.: `0012-use-eventbridge-for-routing.md`) e ele renderizará corretamente no GitHub sem pós-processamento. O wizard não impõe um esquema de numeração — isso é intencional, pois equipes têm convenções diferentes. ## Perguntas frequentes ### Isso armazena algo no servidor ou envia dados para serviços externos? Não. Todo o estado vive no navegador. O wizard de ADR e o construtor de diagramas são componentes React puros; nada é persistido além do que você explicitamente copia ou baixa. ### Posso adicionar meus próprios serviços AWS ou padrões? Sim. O catálogo e as definições de padrões são arquivos de dados estruturados na base de código. Adicionar um serviço significa adicionar uma entrada ao objeto do catálogo; adicionar um padrão significa adicionar um novo registro estruturado com os campos obrigatórios. A aplicação os resolve em tempo de renderização. ### Qual versão do Node.js preciso? Node 18 ou superior é recomendado. O projeto tem como alvo o runtime do Vercel, que executa Node 18 LTS. Versões anteriores podem funcionar, mas não são testadas no CI. ### O site ao vivo é o mesmo código deste repositório? Sim. O deploy de produção em studio.moretes.com é construído diretamente deste repositório via workflow frontend do GitHub Actions com deploy no Vercel. ## Para quem é isso Esta é uma ferramenta focada para arquitetos de soluções que trabalham principalmente com AWS e querem produzir decision records e diagramas consistentes e vinculáveis sem trocar de contexto para uma ferramenta de diagramação separada ou começar de um template ADR em branco toda vez. É também uma implementação de referência de como estruturo aplicações Next.js: App Router, TypeScript em todo o código, Tailwind para estilização, renderização client-side para componentes interativos e pipelines de CI que tratam segurança como uma preocupação separada da correção do build. Se você está avaliando meu trabalho como arquiteto de soluções ou engenheiro TypeScript/Next.js, o site ao vivo em studio.moretes.com é a forma mais rápida de ver o que faz. Se quiser entender as escolhas de implementação, `docs/architecture.md` no repositório é o ponto de partida correto. Contribuições são bem-vindas pelo processo descrito em `CONTRIBUTING.md`. ## Links - [fernandofatech/aws-architecture-studio — GitHub](https://github.com/fernandofatech/aws-architecture-studio) - [AWS Architecture Studio — Live site](https://studio.moretes.com) - [MADR — Markdown Architectural Decision Records format](https://adr.github.io/madr/) - [Mermaid — Diagramming and charting tool](https://mermaid.js.org/) - [AWS Well-Architected Framework](https://aws.amazon.com/architecture/well-architected/) - [Next.js App Router documentation](https://nextjs.org/docs/app) ## Links - [GitHub repository](https://github.com/fernandofatech/aws-architecture-studio)