aws-ai-reference-architectures

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í.

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.

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.

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.