# aws-pattern-library

22+ AWS architectures with diagrams, ADRs and cost notes — ready to copy.

- URL: https://fernando.moretes.com/open-source/aws-pattern-library

- Markdown: https://fernando.moretes.com/open-source/aws-pattern-library/guide.md?lang=en

- GitHub: https://github.com/fernandofatech/aws-pattern-library

- Language: TypeScript

- Topics: 

- Stars: 0

- Forks: 0

- Updated: 2026-05-16T02:08:25Z

---

AWS Pattern Library is a versioned, searchable catalog of 22+ AWS reference architectures — each one ships with a Mermaid diagram, an ADR, Well-Architected pointers, and a cost estimate, all browsable through a Next.js frontend deployed at patterns.moretes.com.

## Why I built this

Every solution architect I know — including myself — has rebuilt the same EventBridge fan-out diagram or the same S3 data-lake ADR at least a dozen times across different clients and teams. The knowledge exists, but it lives in slide decks, Confluence pages, and people's heads. None of those places are version-controlled, searchable, or easy to copy into a pull-request description.

This library is my answer to that problem. I wanted a single place where a recurring AWS pattern is captured *once*, with enough context to be immediately useful: what problem it solves, which services are involved, what trade-offs the architecture encodes, which Well-Architected pillars it touches, and a rough cost envelope with stated assumptions. The ADR format (context → decision → consequences) is deliberate — it forces me to document *why*, not just *what*.

The secondary goal is pedagogical. Junior architects and engineers joining a team often lack the vocabulary to evaluate trade-offs. A catalog that already encodes those trade-offs gives them a starting point that is honest about the downsides, not just the happy path.

## What each pattern includes

- **Mermaid flowchart** rendered client-side — no external image hosting, no stale PNGs.
- **ADR (Architecture Decision Record)** in MADR-friendly format: context, decision, consequences.
- **Services list** with deep links so readers can jump straight to the relevant AWS documentation.
- **Well-Architected pointers** across all six pillars: Operational Excellence, Security, Reliability, Performance, Cost, Sustainability.
- **Cost estimate with stated assumptions** — not a blank promise, but a rough envelope you can sanity-check.
- **Side-by-side comparison** via the `/compare` route — pick any two patterns and diff their pillars and services.

## Coverage across ten domains

The 22+ patterns span the scenarios I encounter most often in production engagements:

- **Web** — three-tier app, static SPA, managed WordPress.
- **API** — serverless REST with API Gateway + Lambda, managed GraphQL with AppSync.
- **Data** — data lake on S3, lakehouse with Apache Iceberg.
- **Events** — event-driven microservices, Step Functions sagas, MSK streaming pipelines.
- **ML / AI** — real-time inference, batch inference, GenAI RAG with Amazon Bedrock.
- **IoT** — telemetry ingest at scale via IoT Core.
- **Security** — secrets rotation with Secrets Manager, GuardDuty + Security Hub posture management.
- **DevOps** — blue/green deploys, EKS platform baseline, CodePipeline CI/CD.
- **Hybrid / Networking** — multi-account VPC mesh with Transit Gateway, cross-region DR.
- **Batch** — AWS Batch with EC2 Spot for cost-optimised compute.

The catalog is intentionally broad rather than deep. Each entry is a starting point — a documented decision that a team can adopt, adapt, or explicitly reject. The point is not to be prescriptive; it is to make the conversation faster by giving everyone a shared vocabulary and a concrete artefact to mark up.

## How the catalog works end-to-end

A single TypeScript file (patterns.ts) is the source of truth. The Next.js App Router generates every page from it — no CMS, no database.

### 📝 Source of Truth

- patterns.ts All 22+ entries (data)

### ⚙️ Build & CI

- GitHub Actions CI / Security / Frontend (ci)
- Next.js 16 App Router + SSG (frontend)
- Mermaid 11 Client-side render (frontend)

### 🌐 Delivery

- Vercel Hosting + CDN (edge)
- Cloudflare DNS (network)

### 👤 User

- Browser patterns.moretes.com (user)

### Flows

- patterns_ts -> nextjs: imported at build
- gh_actions -> nextjs: runs build & lint
- nextjs -> mermaid: diagram string passed
- nextjs -> vercel: deploy on push
- vercel -> cloudflare: DNS resolution
- cloudflare -> browser: serves pages
- browser -> mermaid: renders diagram client-side

## Running it locally

1. **Clone the repository** — Use `git clone https://github.com/fernandofatech/aws-pattern-library.git` and enter the directory.

2. **Install dependencies** — Navigate into `frontend/` and run `npm install`. Node 18+ is expected given the Next.js 16 + React 19 stack.

3. **Start the dev server** — Run `npm run dev` inside `frontend/`. The app is available at `http://localhost:3000`. Hot reload is active — any change to `patterns.ts` reflects immediately.

4. **Browse the catalog** — Open `/patterns` to search and filter. Open `/patterns/[slug]` for a full pattern view. Use `/compare` to diff two patterns side by side.

5. **Add a new pattern** — All patterns live in `frontend/lib/patterns.ts`. Add one entry following the existing shape — every route picks it up automatically on the next render. See CONTRIBUTING.md for the full field spec.

6. **Run CI checks locally** — The repo ships three GitHub Actions workflows: CI (lint + type-check), Frontend (build), and Security (dependency audit). You can mirror these locally with `npm run lint`, `npm run build`, and `npm audit`.

_Quickstart — from clone to running dev server_

```bash
git clone https://github.com/fernandofatech/aws-pattern-library.git
cd aws-pattern-library/frontend
npm install
npm run dev
# → http://localhost:3000
```

> **Copying patterns into your own repos:** The ADR text and Well-Architected pointers in each pattern are written to be copy-pasted directly into a pull-request description or a `docs/adr/` folder. The Mermaid source is plain text — paste it into any tool that renders Mermaid (GitHub Markdown, Notion, Confluence, etc.) and it renders without modification.

## Frequently asked questions

### Is there a database or CMS behind the catalog?

No. Everything is a TypeScript object in `frontend/lib/patterns.ts`. Next.js generates static pages from it at build time. There is no runtime data fetching.

### How do I contribute a new pattern?

Add one entry to `frontend/lib/patterns.ts` following the existing structure, then open a pull request. The full field spec is in CONTRIBUTING.md. Every page — listing, detail, compare — picks up the new entry automatically.

### Are the cost estimates reliable?

They are rough envelopes with stated assumptions, not AWS Calculator exports. They are useful for early-stage conversations and order-of-magnitude checks, not for budget commitments.

### Why Next.js and not a static site generator?

The App Router gives me dynamic routes (`/patterns/[slug]`, `/compare`) and client-side interactivity (Mermaid rendering, search filtering) without a separate API. It deploys as a static export on Vercel with zero backend.

## Who this is for

This repository is useful in three situations. First, if you are a solution architect or senior engineer who regularly writes ADRs and architecture diagrams, the catalog is a starting-point library you can fork and extend with your own team's patterns. Second, if you are onboarding to AWS and want concrete, trade-off-aware examples across a broad range of domains — not just the happy-path tutorials — the patterns give you a more honest picture of how production architectures actually look. Third, if you are evaluating my work as a portfolio piece, the codebase itself demonstrates how I structure a TypeScript/Next.js project, how I approach documentation, and how I think about AWS architecture across ten domains.

What it is not: a Terraform module library, a deployable CDK construct, or a replacement for the AWS Well-Architected Tool. It is a documentation artifact — a catalog of decisions, not a catalog of infrastructure code.

## Links

- [GitHub — fernandofatech/aws-pattern-library](https://github.com/fernandofatech/aws-pattern-library)
- [Live site — patterns.moretes.com](https://patterns.moretes.com)
- [Project architecture docs](https://github.com/fernandofatech/aws-pattern-library/blob/main/docs/architecture.md)
- [AWS Well-Architected Framework](https://docs.aws.amazon.com/wellarchitected/latest/framework/welcome.html)
- [MADR — Markdown Architectural Decision Records](https://adr.github.io/madr/)
- [Mermaid — Diagramming and charting tool](https://mermaid.js.org/)
- [Next.js App Router docs](https://nextjs.org/docs/app)

## Links

- [GitHub repository](https://github.com/fernandofatech/aws-pattern-library)