aws-ai-reference-architectures

Most AI-on-AWS examples fall into one of two extremes. On one side, the toy notebook: one file, no IaC, no IAM, no answer for whoever operates it at 2 AM. On the other, the 200-page enterprise white paper — impressive, and nobody reads it to the end before deciding. Neither helps when you need to close a design in a week.

This repository sits in the middle. Six opinionated reference architectures: detailed enough to support a real design, short enough to be read in 10 minutes each. All of them answer the same eight questions, in the same order — problem, components, diagram, decisions, cost, Well-Architected, trade-offs and Terraform skeleton. The repetition is deliberate: once you've read the first one, you know exactly where to look in the sixth.

What I wanted was material I could paste into a design doc without embarrassment. The trade-offs section says when not to use the pattern. The cost table shows the input assumptions, not just the final number. Decisions follow the MADR format, so they become ADRs with minor edits. The repo's dominant language is HCL because Terraform is precisely the part missing from most examples out there.

Each architecture lives in its own numbered folder under architectures/, with the same set of files. Since there are more than two options, the comparison goes in a table:

| # | Architecture | Pattern | Best for |

|---|---|---|---|

| 01 | RAG with Bedrock + OpenSearch | Retrieval-augmented generation | Internal Q&A over docs, knowledge bases |

| 02 | Multi-agent orchestration | Bedrock Agents + Step Functions | Long-running workflows that need durable state |

| 03 | Streaming AI inference | API Gateway + Lambda + Bedrock streaming | Chat UIs with token-level streaming |

| 04 | Event-driven AI processing | EventBridge + SQS + Lambda + Bedrock | Async classification, enrichment, moderation |

| 05 | Fine-tuning pipeline | SageMaker + S3 + MLflow | Custom models on top of foundation models |

| 06 | Secure agentic system | Bedrock Agents + Guardrails + VPC | Multi-tenant production agent with hard guardrails |

These six cover most of what I see in practice. 04 is the one that saves the most money in production — queuing Bedrock calls through SQS turns a spike into a backlog, and a backlog is what avoids throttling at 9 AM on Monday. 06 is the most underestimated: putting an agent behind a public endpoint without Guardrails and without a VPC is the mistake that shows up in the audit, not in the demo. If your case fits none of the six, open an issue with the use case — the repo grows by real case, not by service list.

The format is the same across all six folders, and it's what makes the repo useful for review rather than just reading.

Decisions: 3 to 5 per architecture, in MADR — context, options considered, choice, consequences. A decision that doesn't list the rejected alternative isn't worth the space it takes; the alternative is what tells you whether the choice still holds in your context.

Cost: three S/M/L scales in USD/month, with the input assumptions written out — request volume, tokens per call, index size. The final number alone is misleading. The assumption is what you swap for your own volume and recompute before the budget meeting.

Well-Architected: the findings that matter across all six pillars, not a full checklist. It doesn't replace the Well-Architected Tool — run the formal Tool before any production launch. What's here is what I'd flag in a brownfield review.

Trade-offs: when to use it and, above all, when not to. 03 (streaming) is great for chat and terrible for batch. 05 (fine-tuning) only pays off once prompt engineering and RAG are exhausted.

Terraform: a skeleton with the resources and the wiring between them. No remote state, no production IAM policies, no imposed tagging convention. Names, networking and IAM are yours — that was a decision, not an omission, because every team has a different landing zone.

A public portfolio without a pipeline is a promise, not proof. The cost of maintaining a reference repo isn't writing it — it's keeping it from rotting silently: a link that stops resolving, a dependency with a CVE, a secret committed by accident. That's why the repo carries automation for the parts that matter in public technical work:

• Frontend: lint, static build and npm audit on every push.
• Docs: mkdocs build --strict and deploy to GitHub Pages. Strict mode is the difference between a reference site and a graveyard of links.
• Security: CodeQL, dependency review on PRs, Trivy filesystem scan and Gitleaks for secrets. A leaked secret is the only hard gate; the rest informs.
• Maintenance: Dependabot for GitHub Actions and frontend dependencies.
• Vercel: preview per PR and production on main, via Git integration — no deploy token lives in the repository.

OPERATIONS.md lists the full workflow and required secrets. CONTRIBUTING.md explains how to propose a new pattern or correct an existing one — cost and service-limit corrections are the most useful contribution, because that's what ages fastest.