# aws-pattern-library

22 arquiteturas AWS com diagrama, ADR, pilares e custo, prontas para copiar

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

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

- GitHub: https://github.com/fernando-moretes/ref-aws-pattern-library

- Language: TypeScript

- Topics: 

- Stars: 1

- Forks: 0

- Updated: 2026-09-29T16:17:11Z

---

O AWS Pattern Library é um catálogo versionado com mais de 22 arquiteturas de referência AWS. Cada padrão tem diagrama Mermaid, ADR no formato contexto, decisão e consequências, os serviços envolvidos, indicações do Well-Architected e uma estimativa de custo com as premissas escritas.

## Por que este repositório existe

Depois de anos desenhando plataformas sobre AWS, percebi que eu redesenhava os mesmos diagramas toda semana. Um três camadas atrás de ALB, um data lake em S3, uma saga em Step Functions. A cada pull request, o mesmo ADR voltava a ser escrito do zero, com outras palavras e às vezes com outro trade-off, porque ninguém lembrava do que tinha sido decidido da última vez.

O custo disso não é o de desenhar o diagrama, é o de manter dez versões dele espalhadas em wikis, slides e PRs, cada uma dizendo uma coisa. Quando o padrão vive num catálogo versionado, a decisão fica num lugar só, com histórico no Git e revisão por pull request.

Tem um segundo motivo, que pesa tanto quanto o primeiro. Quem está começando em arquitetura costuma copiar o diagrama e deixar a decisão para trás. Aqui o diagrama vem sempre junto do ADR, então quem copia o desenho leva o trade-off e as consequências junto, em vez de só as caixinhas.

O repositório é **referência**, não produto. Ele não provisiona nada na sua conta: não tem Terraform, CDK nem CloudFormation. Ele entrega o raciocínio documentado, e a implementação continua sendo trabalho seu, do jeito que o seu contexto pedir.

## O que cada padrão traz

- **Diagrama:** `flowchart` Mermaid renderizado no cliente, fácil de colar num README ou PR que já renderiza Mermaid.
- **ADR:** contexto, decisão e consequências, compatível com o formato MADR.
- **Serviços:** a lista de serviços AWS envolvidos, com links diretos a partir do catálogo.
- **Well-Architected:** indicações para os seis pilares: Excelência Operacional, Segurança, Confiabilidade, Eficiência de Performance, Custo e Sustentabilidade.
- **Custo:** estimativa acompanhada das premissas. Número de custo sem premissa não serve para decidir nada.

## O que tem no catálogo

A lista do README soma 22 padrões em dez categorias:

| Categoria | Padrões |
|---|---|
| Web | três camadas, SPA estática, WordPress gerenciado |
| API | REST serverless, GraphQL gerenciado com AppSync |
| Dados | data lake em S3, lakehouse com Iceberg |
| Eventos | microsserviços event-driven, sagas com Step Functions, streaming com MSK |
| ML / IA | inferência em tempo real, inferência em lote, RAG com Bedrock |
| IoT | ingestão de telemetria em escala |
| Segurança | rotação de segredos, postura com GuardDuty + Security Hub |
| DevOps | deploy blue/green, plataforma EKS, CI/CD com CodePipeline |
| Híbrido / Rede | multi-account com Transit Gateway, DR entre regiões |
| Batch | AWS Batch com EC2 Spot |

A escolha segue o que aparece repetidamente em revisão de arquitetura, não o que é novidade. Três camadas e data lake em S3 não são assunto de palestra, mas são o que você mais vai desenhar num ano normal.

## Como o catálogo funciona

Um único arquivo TypeScript alimenta todas as rotas. O Mermaid renderiza no navegador e o deploy sai pela Vercel.

### 🔧 GitHub: código e CI

- frontend/lib/patterns.ts fonte única dos padrões (data)
- GitHub Actions CI, Frontend, Security (ci)

### ▲ Vercel: Next.js 16

- / categorias e recentes (frontend)
- /patterns busca e filtro (frontend)
- /patterns/[slug] diagrama, ADR, pilares, custo (frontend)
- /compare dois padrões lado a lado (frontend)

### 🌐 Navegador: renderização

- Mermaid 11 flowchart no cliente (compute)

### Fluxos

- contrib -> data: adiciona uma entrada
- data -> ci: valida no PR
- data -> home: alimenta
- data -> list: alimenta
- data -> detail: alimenta
- data -> compare: alimenta
- visitor -> list: busca
- list -> detail: abre o padrão
- detail -> mermaid: desenha o diagrama

## Como funciona por dentro

A stack é Next.js 16 com App Router, React 19, TypeScript 5, Tailwind CSS 4 e Mermaid 11. O deploy é na Vercel e o DNS passa pela Cloudflare.

A decisão que mais importa é que **o catálogo inteiro mora em `frontend/lib/patterns.ts`**. Não tem banco, CMS nem API: um padrão novo é uma entrada nesse arquivo, e a home, a busca, a página de detalhe e o comparador passam a mostrar o padrão sem nenhuma outra mudança. A troca é explícita: você perde edição por quem não programa e ganha revisão por pull request, histórico no Git e zero infraestrutura para operar.

As rotas são quatro:

- `/`: hero, cards por categoria e o que foi adicionado por último.
- `/patterns`: busca e filtro no catálogo.
- `/patterns/[slug]`: o padrão completo, com diagrama, ADR, pilares e custo.
- `/compare`: dois padrões lado a lado, útil quando a dúvida é "saga em Step Functions ou coreografia por eventos?".

O Mermaid renderiza no cliente. Isso deixa o diagrama como texto no código-fonte, que dá para revisar linha a linha num diff, em vez de uma imagem PNG que ninguém consegue revisar.

O CI roda em GitHub Actions com workflows separados de CI, frontend e segurança. Um aviso prático: os badges do README ainda apontam para `fernandofatech/aws-pattern-library`, o endereço anterior à migração para a org `fernando-moretes`.

## Instalar e usar

1. **Clone o repositório**: `git clone https://github.com/fernando-moretes/ref-aws-pattern-library.git`. A aplicação fica no diretório `frontend/`, não na raiz.

2. **Instale as dependências**: `cd ref-aws-pattern-library/frontend && npm install`. Use um Node compatível com Next.js 16.

3. **Suba o servidor local**: `npm run dev` e abra o endereço que o Next.js imprimir, normalmente `http://localhost:3000`. Não precisa de credencial AWS: nada aqui chama a AWS.

4. **Copie o que precisa**: Em `/patterns/[slug]`, leve o `flowchart` Mermaid e o ADR para o seu repositório ou PR. Revise a estimativa de custo contra o seu volume: as premissas do catálogo não são as suas.

5. **Adicione um padrão**: Crie uma entrada em `frontend/lib/patterns.ts` e abra um pull request. Leia o `CONTRIBUTING.md` antes; `OPERATIONS.md` e `SETUP.md` cobrem operação e configuração.

_Quickstart local_

```bash
git clone https://github.com/fernando-moretes/ref-aws-pattern-library.git
cd ref-aws-pattern-library/frontend
npm install
npm run dev
```

> **A estimativa de custo é ponto de partida:** Cada padrão traz custo com premissas justamente porque o número muda com o volume, a região e o modelo de compra. Antes de levar o valor para uma proposta, refaça a conta no AWS Pricing Calculator com a sua carga. Copiar o número sem copiar a premissa é o erro mais comum com esse tipo de material.

## Perguntas frequentes

### Isso provisiona recursos na minha conta?

Não. É um site estático de referência. Não há IaC no repositório, e a aplicação não chama a AWS.

### Posso usar os ADRs no meu trabalho?

Pode. A licença é MIT. Trate o ADR como rascunho: o contexto do seu sistema quase sempre muda pelo menos uma consequência.

### Por que não um CMS?

Porque um padrão de arquitetura merece revisão como código. Com um arquivo TypeScript, cada mudança passa por pull request e fica no histórico do Git.

## Referências

- [GitHub: fernando-moretes/ref-aws-pattern-library](https://github.com/fernando-moretes/ref-aws-pattern-library)
- [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](https://mermaid.js.org/)
- [AWS Pricing Calculator](https://calculator.aws/)

## Para quem serve

Use quando você desenha os mesmos padrões AWS com frequência e quer um ponto de partida que já traga diagrama, ADR e trade-off juntos, ou quando precisa dar a alguém júnior um material que ensina a decisão e não só o desenho. Não use como substituto de IaC nem como orçamento: ele não provisiona nada, e o custo só vale depois que você trocar as premissas pelas suas. Se o seu time quer um catálogo interno, o modelo de um arquivo TypeScript revisado por PR é fácil de copiar e não deixa nenhuma infraestrutura para manter.

## Links

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