# aws-ai-reference-architectures Seis arquiteturas de referência AWS para IA — diagramas, IaC e análise Well-Architected. - 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/fernandofatech/aws-ai-reference-architectures - Homepage: https://ai-architectures.moretes.com - 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-05-16T02:23:15Z --- aws-ai-reference-architectures é um portfólio bilíngue de seis arquiteturas de referência para cargas de trabalho de IA na AWS, cada uma com diagrama Mermaid, decisões arquiteturais justificadas, análise de custo em três escalas, revisão Well-Architected e um esqueleto Terraform funcional. ## Por que este repositório existe A maioria dos exemplos de IA na AWS disponíveis publicamente cai em um de dois extremos: notebooks de brinquedo sem IaC nem segurança, ou white papers corporativos de 200 páginas que ninguém termina de ler. Este repositório ocupa o meio-termo deliberadamente. Cada arquitetura responde a um conjunto fixo de perguntas: qual é o problema, quais serviços e por quê, quais são as três a cinco decisões que realmente importam (com justificativa e alternativas), quanto custa nos tamanhos S/M/L, o que o Well-Architected Framework aponta, e quando *não* usar esse padrão. O formato é consistente entre as seis arquiteturas para que você possa comparar padrões lado a lado ou usar uma seção específica — por exemplo, a tabela de custos ou as decisões no formato MADR — sem precisar ler tudo. O IaC é intencionalmente esqueleto: mostra os recursos e o cabeamento, mas não tenta ser um módulo Terraform genérico que nenhuma equipe usa de verdade. ## O que está incluído - **Seis padrões cobertos:** RAG com Bedrock + OpenSearch, orquestração multi-agente, inferência de streaming, processamento orientado a eventos, pipeline de fine-tuning com SageMaker/MLflow e sistema agêntico seguro com Guardrails. - **Decisões arquiteturais no formato MADR** — cada decisão inclui contexto, opções consideradas, justificativa e consequências, prontas para copiar em seu próprio ADR. - **Análise de custo em três escalas** — tabelas com premissas explícitas para tamanhos S, M e L, úteis em conversas de orçamento com stakeholders. - **Revisão Well-Architected** por arquitetura, cobrindo os seis pilares — complemento, não substituto, da AWS Well-Architected Tool formal. - **Pipeline de CI completo** com CodeQL, Trivy, Gitleaks, revisão de dependências e deploy automático no GitHub Pages (docs) e Vercel (landing). - **Site bilíngue** (PT/EN) publicado em ai-architectures.moretes.com, construído com HTML/CSS/JS puro sem dependências de framework. ## Como o repositório está organizado Cada arquitetura é uma pasta independente com documentação, diagrama e IaC. Dois destinos de publicação são mantidos em paralelo via GitHub Actions. ### 📁 Repo - architectures/ 01–06 (data) - docs/ MkDocs Material (frontend) - frontend/ Static landing (frontend) - .github/workflows/ CI + security (ci) ### ☁️ Publish - GitHub Pages Docs site (external) - Vercel Landing site (edge) ### 🔒 Security - CodeQL SAST (security) - Trivy FS scan (security) - Gitleaks Secret scan (security) ### Fluxos - arch -> docs: fonte de conteúdo - arch -> frontend: catálogo - ci -> docs: build + deploy - ci -> vercel: deploy automático - docs -> pages: publica - frontend -> vercel: publica - ci -> codeql: executa - ci -> trivy: executa - ci -> gitleaks: executa ## As seis arquiteturas em detalhe **01 — RAG com Bedrock + OpenSearch** cobre o padrão de geração aumentada por recuperação para bases de conhecimento internas. É o ponto de entrada mais comum para equipes que querem Q&A sobre documentação corporativa sem fine-tuning. **02 — Orquestração multi-agente** usa Bedrock Agents combinado com Step Functions para fluxos de trabalho de longa duração que precisam de estado durável entre etapas — o caso onde uma única chamada de LLM não é suficiente. **03 — Inferência de streaming** mostra como conectar API Gateway, Lambda e o streaming nativo do Bedrock para UIs de chat com resposta token a token, sem polling. **04 — Processamento de IA orientado a eventos** é o padrão assíncrono: EventBridge + SQS + Lambda + Bedrock para classificação, enriquecimento e moderação de conteúdo em escala, desacoplados do produtor. **05 — Pipeline de fine-tuning** cobre o ciclo completo com SageMaker, S3 e MLflow — preparação de dados, treinamento, registro de experimentos e promoção de modelos. Útil quando um modelo de fundação genérico não atinge a qualidade necessária. **06 — Sistema agêntico seguro** é o padrão mais complexo: Bedrock Agents com Guardrails, isolamento de VPC e controles multi-tenant. É o ponto de partida para quem precisa colocar um agente em produção com restrições reais de segurança e compliance. ## Como instalar e usar localmente 1. **Clone o repositório** — Execute `git clone https://github.com/fernandofatech/aws-ai-reference-architectures.git` e entre na pasta com `cd aws-ai-reference-architectures`. 2. **Leia uma arquitetura diretamente no terminal ou no editor** — Cada arquitetura é autodocumentada. Abra, por exemplo, `architectures/01-rag-bedrock-opensearch/README.md` no seu editor ou use `cat` para inspecionar o conteúdo. Não há dependências de runtime para leitura. 3. **Sirva o site de documentação localmente (opcional)** — Instale as dependências Python com `pip install mkdocs-material` e execute `mkdocs serve` na raiz. O site estará disponível em `http://127.0.0.1:8000`. 4. **Sirva o frontend de catálogo localmente (opcional)** — Entre em `cd frontend` e execute qualquer servidor HTTP estático, por exemplo `python3 -m http.server 8080`. Não há etapa de build — o frontend é HTML/CSS/JS puro. 5. **Inspecione e adapte o esqueleto Terraform** — Cada pasta de arquitetura contém um subdiretório `terraform/` com arquivos `.tf` que declaram os recursos principais. Execute `terraform init` dentro de qualquer um deles para validar a sintaxe. Ajuste nomes, tags, políticas IAM e estado remoto antes de qualquer `terraform apply`. 6. **Execute as verificações de segurança localmente** — Instale Trivy e Gitleaks e execute `trivy fs .` e `gitleaks detect --source .` na raiz para replicar as verificações que o CI executa em cada push. _Fluxo completo: clonar, ler e servir o site de docs_ ```bash # Clone git clone https://github.com/fernandofatech/aws-ai-reference-architectures.git cd aws-ai-reference-architectures # Read an architecture (no dependencies needed) cat architectures/01-rag-bedrock-opensearch/README.md | less # Serve the MkDocs documentation site locally pip install mkdocs-material mkdocs serve # → open http://127.0.0.1:8000 # Serve the static catalog frontend cd frontend && python3 -m http.server 8080 # → open http://127.0.0.1:8080 # Validate a Terraform skeleton (no AWS credentials needed for init) cd ../architectures/04-event-driven-ai-processing/terraform terraform init terraform validate ``` > **O IaC é esqueleto, não módulo:** Os arquivos Terraform mostram os recursos e o cabeamento corretos para cada padrão, mas não estão prontos para `terraform apply` em produção. Cada equipe precisa adaptar: nomes de recursos, tags obrigatórias, políticas IAM com least privilege real, configuração de estado remoto (S3 + DynamoDB) e integração com o pipeline de CI/CD existente. Usar o esqueleto diretamente em produção sem essas adaptações é um risco. ## Como o repositório funciona internamente O repositório tem três camadas de conteúdo que são mantidas separadas por design. A camada de **arquitetura** vive em `architectures/` e é o núcleo do projeto. Cada subpasta contém um `README.md` estruturado com as seções fixas descritas acima, um arquivo `diagram.mmd` com o diagrama Mermaid, e um diretório `terraform/` com o esqueleto IaC. Toda a documentação técnica está aqui — o resto do repositório é infraestrutura de publicação. A camada de **documentação** em `docs/` usa MkDocs Material para gerar um site navegável publicado no GitHub Pages. O workflow `docs.yml` executa um build estrito (falha em avisos) e faz deploy automaticamente em cada push para `main`. A camada de **frontend** em `frontend/` é um catálogo estático sem dependências de framework, conectado ao Vercel via integração Git. Previews automáticos são gerados para cada pull request; o deploy de produção acontece no merge para `main`. O pipeline de CI cobre quatro preocupações distintas: qualidade do frontend (lint + audit), qualidade da documentação (build estrito), segurança (CodeQL + Trivy + Gitleaks + revisão de dependências) e manutenção (Dependabot para Actions e dependências do frontend). Os workflows são independentes — uma falha no scan de segurança não bloqueia o deploy de docs, e vice-versa. ## Perguntas frequentes ### Posso usar o código Terraform diretamente em um projeto de cliente? Sim, com adaptações. O esqueleto mostra os recursos corretos e o cabeamento entre eles, mas você precisará ajustar políticas IAM, nomes de recursos, tags, estado remoto e integração com seu pipeline antes de qualquer deploy. Trate como ponto de partida, não como módulo pronto. ### Por que seis arquiteturas e não mais? Seis padrões cobrem a maioria das cargas de trabalho de IA que encontro na prática. Mais padrões sem a mesma profundidade de análise não agregam valor. Se o seu caso de uso não se encaixa em nenhum dos seis, abra uma issue com o contexto. ### A revisão Well-Architected substitui a AWS Well-Architected Tool? Não. A revisão aqui destaca os achados mais relevantes para cada padrão específico e serve como preparação ou complemento. A Tool formal da AWS deve ser usada antes de qualquer lançamento em produção. ### O site funciona sem JavaScript? O frontend de catálogo usa JavaScript para funcionalidades de navegação, mas o conteúdo principal é acessível. O site de documentação (MkDocs Material) requer JavaScript para a busca e navegação completas. > **Como usar em revisões de design existentes:** Para revisões de sistemas já em produção (brownfield), vá direto para a seção Well-Architected da arquitetura mais próxima do seu padrão atual e compare ponto a ponto com o que você tem. As seções de trade-offs também são úteis para justificar ou questionar decisões tomadas no passado em um contexto de revisão técnica. ## Para quem é este repositório Este repositório é útil para arquitetos de soluções e engenheiros sênior que precisam de um ponto de partida estruturado para designs de IA na AWS — não um tutorial, não um white paper, mas algo que você pode abrir em uma reunião de design e usar diretamente. É igualmente útil para quem está avaliando meu trabalho como arquiteto: cada decisão está justificada, cada trade-off está explícito, e o pipeline de CI reflete as práticas que aplico em projetos reais. Se você está começando com IA na AWS e quer entender os padrões antes de escrever código, comece pela arquitetura 01 ou 04. Se você já tem um sistema em produção e quer identificar gaps, vá para a seção Well-Architected da arquitetura correspondente. ## Referências - [GitHub — fernandofatech/aws-ai-reference-architectures](https://github.com/fernandofatech/aws-ai-reference-architectures) - [Portfolio site — ai-architectures.moretes.com](https://ai-architectures.moretes.com) - [Project documentation — GitHub Pages](https://fernandofatech.github.io/aws-ai-reference-architectures/) - [AWS Bedrock documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/what-is-bedrock.html) - [AWS Well-Architected Framework](https://docs.aws.amazon.com/wellarchitected/latest/framework/welcome.html) - [MADR — Markdown Architectural Decision Records](https://adr.github.io/madr/) - [MkDocs Material](https://squidfunk.github.io/mkdocs-material/) ## Links - [GitHub repository](https://github.com/fernandofatech/aws-ai-reference-architectures) - [Homepage](https://ai-architectures.moretes.com)