aws-ai-reference-architectures
Seis arquiteturas de IA na AWS com decisões, custo S/M/L e Terraform
git clone https://github.com/fernando-moretes/app-aws-ai-reference-architectures.gitcerca de 4 min · áudio gerado ao tocar
Seis arquiteturas de referência para cargas de IA na AWS (RAG, multi-agente, streaming, event-driven, fine-tuning e agente seguro), cada uma com diagrama Mermaid, decisões no formato MADR, custo em três escalas, revisão Well-Architected e um esqueleto Terraform que dá para ler em 10 minutos.
Por que este repositório existe
O material sobre IA na AWS costuma cair em um de dois extremos. De um lado, o notebook de exemplo: um arquivo, nenhuma IaC, nenhuma linha sobre IAM ou rede. Funciona na demo e não sobrevive à primeira revisão de segurança. Do outro, o white paper de 200 páginas: correto, completo e impossível de usar numa reunião de design de uma hora.
A pergunta que me interessa não é "qual serviço usar?", é "o que eu preciso decidir antes de escrever a primeira linha, e quanto isso vai custar para manter?". Este repositório fica no meio do caminho: seis arquiteturas opinativas, detalhadas o bastante para servir de ponto de partida de um design real e curtas o bastante para caber numa leitura antes da reunião.
Cada arquitetura responde às mesmas oito perguntas, na mesma ordem: problema, componentes e por quê, diagrama, as 3–5 decisões que importam (com alternativas), custo mensal em USD nas escalas S, M e L, achados Well-Architected nos seis pilares, trade-offs (quando usar e quando não usar) e o esqueleto Terraform. A estrutura fixa é deliberada: quem já leu uma sabe onde procurar em todas as outras.
As seis arquiteturas
Como ler, conforme o que você precisa
O repositório não foi pensado para leitura de ponta a ponta. Cada pasta em architectures/ é autocontida, e o ponto de entrada muda com a pergunta que você traz:
- Design novo: leia a arquitetura correspondente inteira e copie a seção de trade-offs para o seu design doc. É ali que estão as condições em que o padrão deixa de valer.
- Revisão de ambiente existente (brownfield): abra direto a seção Well-Architected e compare com o que está rodando. Os achados estão organizados pelos seis pilares, então a conversa com o time vira checklist.
- Conversa de custo: as tabelas trazem três dimensionamentos (S, M, L) com as premissas de entrada escritas. A premissa importa mais que o número; mude o volume e refaça a conta.
- Inspiração para ADR: as decisões seguem o formato MADR. Copie, adapte o contexto e registre a sua.
Na prática, o uso mais frequente é o segundo: pegar um sistema que já existe e descobrir o que ficou para trás em segurança ou operação.
Do Markdown ao leitor: como o repositório é publicado
O conteúdo mora em Markdown, Mermaid e HCL; a esteira valida e publica em dois destinos.
- architectures/ · 6 pastas: doc + Mermaid + Terraform
- docs/ · MkDocs Material
- frontend/ · landing estática sem dependências
- MkDocs build strict · lint + build do frontend
- CodeQL, Trivy fs, · Gitleaks, dependency review
- GitHub Pages · site de documentação
- Vercel · landing do catálogo
Como usar
- 1
Clone o repositório
git clone https://github.com/fernando-moretes/app-aws-ai-reference-architectures.gite entre na pasta. Se só quer ler, o site de documentação no GitHub Pages tem o mesmo conteúdo renderizado. - 2
Escolha a arquitetura pelo caso de uso
Use a tabela do README: Q&A sobre documentos vai para a 01, fluxo longo com estado vai para a 02, chat com streaming vai para a 03, processamento assíncrono vai para a 04, modelo customizado vai para a 05, agente multi-tenant vai para a 06.
- 3
Leia decisões e trade-offs antes do Terraform
As 3–5 decisões de cada pasta dizem por que cada serviço está ali e qual alternativa foi descartada. Pular essa parte e ir direto ao HCL é copiar a resposta sem a pergunta.
- 4
Valide o esqueleto Terraform localmente
Dentro da pasta da arquitetura,
terraform init -backend=falseseguido deterraform validateconfirma a fiação dos recursos sem tocar em conta nenhuma. Nomes, tags, rede, policies de IAM e remote state são seus para adaptar. - 5
Rode a documentação localmente (opcional)
O site usa MkDocs Material. Instale com
pip install mkdocs-materiale rodemkdocs serve; o CI usa build estrito, então usemkdocs build --strictantes de abrir PR.
git clone https://github.com/fernando-moretes/app-aws-ai-reference-architectures.git
cd app-aws-ai-reference-architectures
# Valida a fiação do Terraform sem backend e sem credenciais
cd architectures/01-rag-bedrock-opensearch
terraform init -backend=false
terraform validate
cd ../..
# Documentação local (MkDocs Material)
pip install mkdocs-material
mkdocs serve # http://127.0.0.1:8000
mkdocs build --strict # o mesmo build que o CI rodaEsqueleto não é módulo
O HCL mostra recursos e fiação, não um módulo pronto para terraform apply em produção. Ele não traz remote state, convenção de tags nem policies de IAM fechadas para o seu ambiente. Aplicar como está é herdar decisões de rede e permissão que não foram tomadas para você, e esse é o tipo de dívida que só aparece na auditoria.
A esteira em volta do conteúdo
Repositório público de arquitetura tem um risco que pouca gente trata: um exemplo com segredo vazado ou dependência vulnerável vira referência copiada por outras pessoas. Por isso o conteúdo passa pelas mesmas verificações que eu exigiria de código de produção.
Documentação: build estrito do MkDocs. Link quebrado ou página órfã derruba o build, em vez de virar 404 silencioso no site.
Frontend: a landing é estática e sem dependências de runtime; mesmo assim passa por lint, build e npm audit.
Segurança: CodeQL, dependency review, Trivy em modo filesystem e Gitleaks para segredo. O Gitleaks é o que mais importa aqui, porque esqueleto Terraform é exatamente o lugar onde alguém cola uma chave para testar e esquece.
Manutenção: Dependabot para GitHub Actions e dependências do frontend. O deploy da landing sai pela integração Git da Vercel, com preview por PR.
O OPERATIONS.md descreve o fluxo completo e os segredos necessários para quem fizer fork.
Perguntas frequentes
Os números de custo servem para orçamento?
Servem para ordem de grandeza e para a conversa inicial. As premissas de cada escala estão escritas; se o seu volume de tokens ou de documentos for diferente, refaça a conta com a calculadora oficial da AWS antes de comprometer orçamento.
A revisão Well-Architected substitui a ferramenta oficial?
Não. Ela aponta os achados mais salientes de cada padrão. Antes de qualquer lançamento em produção, rode a revisão formal no AWS Well-Architected Tool sobre a sua carga real.
Meu caso não cabe em nenhuma das seis. E agora?
Seis padrões cobrem a maior parte do que vejo na prática, mas não tudo. Abra uma issue descrevendo o caso de uso; correções aos padrões existentes também são bem-vindas, conforme o CONTRIBUTING.md.
Referências
Para quem é
Use este repositório quando você precisa levar a uma reunião de design um ponto de partida com decisões, custo e trade-offs já escritos, ou quando quer revisar um sistema de IA na AWS que já existe contra um checklist por pilar. Não use como biblioteca de módulos Terraform nem como substituto da revisão formal Well-Architected: o valor está nas decisões e nas condições em que cada padrão deixa de valer, não no HCL.
Deep dives de arquitetura, AWS, IA e mercado: direto no seu email. Grátis.
Sem spam · cancele quando quiser