aws-pattern-library

In 16 years designing platforms on AWS, I have redrawn the same serverless REST — API Gateway, Lambda, DynamoDB — more times than I can count. Each time in a different tool, with a different box name, without the reasoning from the previous round. The question this repository answers is not "how do you draw a data lake on S3?" — it's "where is the version the team already discussed, with the trade-off written down, so I can paste it into today's PR?".

The real problem: loose diagrams rot. A .drawio in a shared folder doesn't say why Kinesis beat MSK on that project, nor what the 10,000-events-per-second assumption cost. Six months later someone re-derives the decision from scratch and lands somewhere else, for reasons nobody recorded.

What the catalog does: it ties every diagram to an ADR (context, decision, consequences), to the services involved, to the six Well-Architected pillars and to a cost estimate with its assumptions spelled out. That's 22+ patterns across ten categories — Web, API, Data, Events, ML/AI, IoT, Security, DevOps, Hybrid/Networking and Batch — and every one of them goes through code review, because the catalog is code.

Who it's for: the architect who wants to stop redrawing, and the junior who needs a starting point where the trade-off is already encoded instead of discovered in production.

One source of truth: frontend/lib/patterns.ts is a typed array. Each element carries the slug, the category, the Mermaid diagram as a string, the ADR in three fields, the list of services, the per-pillar pointers and the cost note. The TypeScript type is the schema — if a pattern is born without its consequences field, the build fails, not the reader.

Routes are derived, not maintained: the home page builds the category cards and "recently added" from the array; /patterns filters and searches over it; /patterns/[slug] renders one item; /compare puts two side by side. Adding a pattern is one entry; there is no second list to forget to update.

Diagram rendering: Mermaid 11 runs in the browser. The upside is that the diagram is text — the PR diff shows an arrow moved from Kinesis to MSK, something a PNG never shows. The cost is that a diagram with broken syntax fails in the browser of whoever opens the page, not in the build. Open the pattern page before you merge.

Operations: Vercel serves the site, Cloudflare answers DNS, GitHub Actions handles CI, frontend and security. No database, no queue, no Lambda — the cost of keeping this alive for years is the cost of reviewing one TypeScript file, and that is exactly why it was built this way.