# aws-ai-reference-architectures Seis arquiteturas de IA na AWS com ADR, custo S/M/L, Well-Architected e Terraform - URL: https://fernando.moretes.com/open-source/aws-ai-reference-architectures - Markdown: https://fernando.moretes.com/open-source/aws-ai-reference-architectures/guide.md?lang=pt - GitHub: https://github.com/fernando-moretes/app-aws-ai-reference-architectures - Homepage: https://fernando-moretes.github.io/app-aws-ai-reference-architectures/ - Language: HCL - Topics: ai, architecture, aws, bedrock, github-actions, mlops, moretes, portfolio, reference-architecture, sagemaker, solution-architecture, terraform, well-architected - Stars: 0 - Forks: 0 - Updated: 2026-09-08T20:37:07Z --- Seis arquiteturas de referência para IA na AWS — cada uma com diagrama, decisões em formato ADR, custo em três escalas, revisão Well-Architected e esqueleto Terraform — escritas para serem lidas em 10 minutos e portadas para um design doc real. ## Por que este repositório existe A maioria dos exemplos de IA na AWS cai em um de dois extremos. De um lado, o notebook de brinquedo: um arquivo, sem IaC, sem IAM, sem resposta para quem opera aquilo às 2h da manhã. Do outro, o white paper corporativo de 200 páginas — impressionante, e que ninguém lê até o fim antes de decidir. Nenhum dos dois serve quando você precisa fechar um design em uma semana. Este repositório fica no meio. São seis arquiteturas de referência **opinadas**: detalhadas o suficiente para sustentar um design real, curtas o suficiente para serem lidas em 10 minutos cada. Todas respondem às mesmas oito perguntas, na mesma ordem — problema, componentes, diagrama, decisões, custo, Well-Architected, trade-offs e esqueleto Terraform. A repetição é proposital: depois de ler a primeira, você sabe exatamente onde procurar na sexta. O que eu queria era material que pudesse ser copiado para dentro de um design doc sem vergonha. A seção de trade-offs diz quando **não** usar o padrão. A tabela de custo mostra as premissas de entrada, não só o número final. As decisões seguem o formato MADR, então viram ADR com poucas edições. A linguagem dominante do repo é HCL porque o Terraform é justamente a parte que mais falta nos exemplos que circulam por aí. ## As seis arquiteturas Cada arquitetura vive numa pasta própria em `architectures/`, numerada, com o mesmo conjunto de arquivos. Como são mais de duas opções, a comparação vai em tabela: | # | Arquitetura | Padrão | Serve para | |---|---|---|---| | 01 | RAG com Bedrock + OpenSearch | Retrieval-augmented generation | Q&A interno sobre documentos, knowledge bases | | 02 | Orquestração multiagente | Bedrock Agents + Step Functions | Workflows longos que precisam de estado durável | | 03 | Inferência com streaming | API Gateway + Lambda + Bedrock streaming | Chat com streaming token a token | | 04 | Processamento event-driven | EventBridge + SQS + Lambda + Bedrock | Classificação, enriquecimento e moderação assíncronos | | 05 | Pipeline de fine-tuning | SageMaker + S3 + MLflow | Modelos customizados sobre foundation models | | 06 | Sistema agentic seguro | Bedrock Agents + Guardrails + VPC | Agente multi-tenant em produção com guardrails rígidos | Os seis cobrem a maior parte do que vejo em prática. A 04 é a que mais economiza dinheiro em produção — enfileirar chamadas ao Bedrock por SQS transforma pico em fila, e fila é o que evita throttling às 9h de segunda. A 06 é a mais subestimada: colocar um agente atrás de um endpoint público sem Guardrails e sem VPC é o erro que aparece na auditoria, não no demo. Se o seu caso não cabe em nenhuma das seis, o caminho é abrir uma issue com o use case — o repo cresce por caso real, não por lista de serviços. ## Como o repositório se publica Uma fonte (as seis pastas) alimenta dois destinos: o site de documentação no GitHub Pages e a landing estática na Vercel. A esteira de segurança roda sobre tudo. ### 📚 Repo — fonte - architectures/01..06 diagrama, ADR, custo, WA, TF (data) - docs/ MkDocs Material (strict) (frontend) - frontend/ landing estática sem deps (frontend) ### 🔧 GitHub Actions — CI - docs.yml build strict + deploy (ci) - CodeQL · Trivy · Gitleaks dependency review (security) ### 🌐 Publicação - GitHub Pages site de documentação (external) - ▲ Vercel preview por PR + produção (edge) ### Fluxos - archs -> docs: conteúdo - docs -> docsci: push em main - docsci -> pages: deploy - frontend -> vercel: integração Git - archs -> sec: varredura - frontend -> sec: lint + npm audit - reader -> pages: lê a arquitetura - reader -> vercel: navega o catálogo ## Como cada arquitetura é montada O formato é o mesmo nas seis pastas, e é ele que faz o repo servir para revisão e não só para leitura. **Decisões:** 3 a 5 por arquitetura, em MADR — contexto, opções consideradas, escolha, consequências. Decisão que não lista a alternativa rejeitada não vale o espaço que ocupa; é a alternativa que diz se a escolha ainda faz sentido no seu contexto. **Custo:** três escalas S/M/L em USD/mês, com as premissas de entrada escritas — volume de requisições, tokens por chamada, tamanho do índice. O número final sozinho engana. A premissa é o que você troca pelo seu volume e recalcula antes da reunião de orçamento. **Well-Architected:** os achados que importam nos seis pilares, não uma checklist inteira. Não substitui o Well-Architected Tool — use o Tool formal antes de qualquer lançamento em produção. O que está aqui é o que eu apontaria numa revisão de brownfield. **Trade-offs:** quando usar e, principalmente, quando **não** usar. A 03 (streaming) é ótima para chat e péssima para batch. A 05 (fine-tuning) só se paga quando prompt engineering e RAG já esgotaram. **Terraform:** esqueleto com os recursos e a ligação entre eles. Sem remote state, sem policies IAM de produção, sem convenção de tag imposta. Nome, rede e IAM são seus — foi uma decisão, não uma omissão, porque cada time tem um landing zone diferente. ## Como instalar e usar 1. **Clone e escolha uma arquitetura** — `git clone https://github.com/fernando-moretes/app-aws-ai-reference-architectures.git` e abra a pasta em `architectures/` que corresponde ao seu caso. Leia do início ao fim uma vez — são 10 minutos — antes de copiar qualquer coisa. 2. **Sirva a documentação localmente** — O site é MkDocs Material. Com Python 3 disponível: `pip install mkdocs-material` e `mkdocs serve` na raiz. O CI roda `mkdocs build --strict`, então link quebrado derruba o build — o mesmo comando vale para conferir antes de abrir um PR. 3. **Rode a landing do catálogo** — `frontend/` é uma página estática sem dependências de runtime; os scripts de lint, build e `npm audit` estão no `package.json` dela. Para ver localmente basta servir a pasta com qualquer servidor estático. 4. **Adapte o esqueleto Terraform** — Dentro da pasta da arquitetura, aponte o provider para a sua conta e região, adicione o backend de remote state e substitua as policies IAM placeholder. Só então `terraform init` e `terraform plan`. Faça isso numa conta sandbox: o esqueleto não conhece o seu landing zone. 5. **Porte as decisões para o seu design doc** — Copie as decisões MADR e a seção de trade-offs. Troque as premissas da tabela de custo pelo seu volume e recalcule. É esse trecho, e não o Terraform, que sustenta a conversa com quem aprova o orçamento. _Quickstart: docs locais, landing e plan do esqueleto_ ```bash git clone https://github.com/fernando-moretes/app-aws-ai-reference-architectures.git cd app-aws-ai-reference-architectures # 1. Documentation site (MkDocs Material, same strict mode as CI) pip install mkdocs-material mkdocs build --strict && mkdocs serve # http://127.0.0.1:8000 # 2. Static catalog landing (no runtime deps) cd frontend && npm install && npm run build && cd .. # 3. Terraform skeleton — sandbox account only cd architectures/01-rag-bedrock-opensearch # edit provider/backend/IAM first, then: AWS_PROFILE=sandbox terraform init AWS_PROFILE=sandbox terraform plan ``` > **O que o Terraform daqui não faz:** O IaC é esqueleto por decisão: mostra recursos e ligação, não módulo pronto. Não há remote state, as policies IAM são ponto de partida e não há convenção de tag. Um `terraform apply` sem essa adaptação cria recursos com nomes genéricos numa conta que talvez não seja a certa — e OpenSearch e endpoints SageMaker cobram por hora enquanto estiverem de pé. Confira `aws sts get-caller-identity` antes de qualquer apply. ## O que roda em CI Portfólio público sem esteira é promessa, não prova. O custo de manter um repo de referência não é escrevê-lo — é evitar que ele apodreça em silêncio: link que para de resolver, dependência com CVE, segredo commitado por descuido. Por isso o repo carrega automação para as partes que importam em trabalho técnico público: - **Frontend:** lint, build estático e `npm audit` a cada push. - **Docs:** `mkdocs build --strict` e deploy no GitHub Pages. O modo strict é a diferença entre um site de referência e um cemitério de links. - **Segurança:** CodeQL, dependency review nos PRs, Trivy no filesystem e Gitleaks para segredo. Segredo vazado é a única trava dura; o resto informa. - **Manutenção:** Dependabot para GitHub Actions e para as dependências do frontend. - **Vercel:** preview por PR e produção em `main`, via integração Git — nenhum token de deploy vive no repositório. O `OPERATIONS.md` lista o fluxo completo e os segredos necessários. `CONTRIBUTING.md` explica como propor um padrão novo ou corrigir um existente — correção de custo e de limite de serviço é a contribuição mais útil, porque é o que envelhece mais rápido. ## Perguntas frequentes ### Por que só seis arquiteturas? Porque seis cobrem a maior parte dos workloads de IA que passam por mim, e cada uma custa horas para manter atualizada em custo, limite de serviço e Well-Architected. Vinte padrões desatualizados valem menos que seis corretos. Caso novo entra por issue, com o use case descrito. ### Posso usar o Terraform direto em produção? Não. É esqueleto: recursos e ligação, sem remote state, sem IAM de produção, sem rede adaptada ao seu landing zone. Use como ponto de partida e revise cada policy antes do primeiro `apply` fora de sandbox. ### Os números de custo são confiáveis? São estimativas com premissas explícitas para S/M/L. A premissa é o que vale — troque pelo seu volume de requisições e tokens e recalcule. Preço de modelo no Bedrock muda com frequência; conferir a tabela oficial antes de apresentar é obrigatório. ### Isso substitui o AWS Well-Architected Tool? Não. As seções WA são os achados salientes que eu apontaria numa revisão. Antes de qualquer lançamento em produção, rode o Tool formal — é ele que gera o registro auditável. ## Referências - [fernando-moretes/app-aws-ai-reference-architectures (GitHub)](https://github.com/fernando-moretes/app-aws-ai-reference-architectures) - [Documentation site (GitHub Pages)](https://fernando-moretes.github.io/app-aws-ai-reference-architectures/) - [Catalog landing (Vercel)](https://aws-ai-reference-architectures.vercel.app) - [Production portfolio — ai-architectures.moretes.com](https://ai-architectures.moretes.com) - [MADR — Markdown Architectural Decision Records](https://adr.github.io/madr/) - [AWS Well-Architected Framework](https://docs.aws.amazon.com/wellarchitected/latest/framework/welcome.html) - [Amazon Bedrock — documentation](https://docs.aws.amazon.com/bedrock/) - [MkDocs Material](https://squidfunk.github.io/mkdocs-material/) ## Veredito Use este repositório quando precisar fechar um design de IA na AWS em dias, não semanas, e quiser começar de decisões com alternativa registrada, custo com premissa explícita e uma lista do que não fazer. Serve para arquiteto e tech lead que vai escrever o design doc, e para quem revisa um sistema existente contra Well-Architected. Não use se procura módulos Terraform prontos para `apply`, ou uma taxonomia exaustiva de padrões — o repo é opinado por escolha e cobre seis casos que se repetem na prática. O trade-off é claro: menos padrões, cada um mantido; o preço de manter é o que decide o que entra. ## Links - [GitHub repository](https://github.com/fernando-moretes/app-aws-ai-reference-architectures) - [Homepage](https://fernando-moretes.github.io/app-aws-ai-reference-architectures/)