القائمة
Template e guia para ADRs (Architecture Decision Records): quando criar, estrutura, exemplos. Use quando documentar decisões arquiteturais ou criar ADRs.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
Acione o `tech-writer` para criar um novo Architecture Decision Record (ADR).
Padrões Android modernos: Kotlin, Jetpack Compose, MVVM, Hilt, Room, Navigation, Coroutines, testes. Use quando implementar features em Android nativo.
Padrões Angular modernos: Standalone Components, Signals, inject(), HttpClient, RxJS, Testing. Use quando implementar features em Angular ou configurar projeto Angular.
Migração AngularJS para Angular: estratégia incremental, ngUpgrade, dual-boot, padrões de coexistência. Use quando planejar ou executar migração de AngularJS (1.x) para Angular moderno.
Design de API REST seguindo boas práticas. Use quando pedirem para projetar API, definir endpoints, criar contrato REST ou OpenAPI.
Acione o `architect-reviewer` para uma análise arquitetural focada.
استنادا إلى تصنيف SOC المهني
| name | adr-template |
| description | Template e guia para ADRs (Architecture Decision Records): quando criar, estrutura, exemplos. Use quando documentar decisões arquiteturais ou criar ADRs. |
| argument-hint | [contexto adicional] |
Guia para documentar decisoes arquiteturais significativas.
NAO criar ADR para: escolha de nome de variavel, formatacao de codigo, decisoes triviais e reversiveis.
# ADR-NNNN: Titulo curto e descritivo
**Status**: Proposed | Accepted | Deprecated | Superseded by ADR-XXXX
**Date**: YYYY-MM-DD
**Deciders**: Quem participou da decisao
**Technical Story**: Link para issue/ticket (se houver)
## Context
Qual e o contexto e o problema que motivou essa decisao?
Quais forcas estao em jogo (tecnicas, organizacionais, de negocio)?
Qual e a situacao atual e por que ela nao e mais adequada?
## Decision
Qual e a decisao tomada e por que?
Descreva a abordagem escolhida de forma clara e objetiva.
## Alternatives Considered
### Alternativa 1: Nome
- **Descricao**: O que seria feito
- **Pros**: Vantagens
- **Cons**: Desvantagens
- **Por que descartada**: Motivo principal
### Alternativa 2: Nome
- **Descricao**: O que seria feito
- **Pros**: Vantagens
- **Cons**: Desvantagens
- **Por que descartada**: Motivo principal
## Consequences
### Positivas
- Beneficio 1
- Beneficio 2
### Negativas
- Trade-off 1
- Trade-off 2
### Riscos
- Risco identificado e mitigacao planejada
## Compliance
- [ ] Revisado pelo time
- [ ] Alinhado com arquitetura existente
- [ ] Impacto em seguranca avaliado
- [ ] Impacto em custo avaliado
# ADR-0001: DynamoDB para persistencia de pedidos
**Status**: Accepted
**Date**: 2026-03-15
**Deciders**: Time de engenharia
## Context
O servico de pedidos precisa de um banco de dados para armazenar pedidos.
O padrao de acesso e predominantemente key-value (busca por ID) com queries
secundarias por status e data. O volume esperado e 10K pedidos/dia,
com picos de ate 100 pedidos/segundo.
O servico roda como Lambda na AWS, o que favorece servicos gerenciados
sem connection pooling.
## Decision
Usar DynamoDB com:
- Partition key: `orderId` (UUID)
- GSI1: `status-createdAt-index` para queries por status com ordenacao
- On-demand capacity (pay-per-request)
- Point-in-time recovery habilitado
## Alternatives Considered
### PostgreSQL (RDS)
- **Pros**: Modelo relacional flexivel, SQL, joins
- **Cons**: Connection pooling necessario com Lambda, custo fixo (instancia),
gerenciamento de schema mais complexo
- **Descartada**: O padrao de acesso nao justifica complexidade relacional.
Lambda + RDS precisa de RDS Proxy ($), e o volume nao justifica instancia fixa.
### Aurora Serverless v2
- **Pros**: Serverless, SQL, auto-scaling
- **Cons**: Custo minimo maior que DynamoDB on-demand, cold start no scale-up,
connection pooling ainda necessario
- **Descartada**: Custo minimo desproporcional ao volume esperado.
## Consequences
### Positivas
- Zero management (fully managed)
- Custo proporcional ao uso (on-demand)
- Latencia single-digit ms para acesso por key
- Integracao nativa com Lambda (SDK, sem driver)
### Negativas
- Queries complexas limitadas (sem joins, sem aggregations)
- Modelagem de dados requer planejamento upfront (access patterns)
- GSIs adicionam custo e complexidade
### Riscos
- Se surgirem queries complexas nao previstas, pode ser necessario
adicionar mais GSIs ou considerar um servico de query separado (Athena/OpenSearch).
# ADR-0002: SQS + Lambda para processamento assincrono
**Status**: Accepted
**Date**: 2026-03-15
**Deciders**: Time de engenharia
## Context
Apos criacao de um pedido, e necessario:
1. Processar pagamento
2. Enviar notificacao
3. Atualizar metricas
Essas operacoes nao devem bloquear a resposta ao usuario.
Precisamos de processamento assincrono confiavel com retry e DLQ.
## Decision
SQS Standard Queue com Lambda trigger:
- BatchSize: 10
- ReportBatchItemFailures: habilitado (partial batch failure)
- DLQ com maxReceiveCount: 3
- VisibilityTimeout: 300s (5x Lambda timeout de 60s)
## Alternatives Considered
### EventBridge + Lambda
- **Pros**: Fan-out nativo, event routing por regras
- **Cons**: Sem batching nativo, retry mais limitado, sem FIFO
- **Descartada**: SQS oferece controle mais fino de retry e DLQ
para processamento transacional.
### Step Functions
- **Pros**: Orquestracao visual, retry por step, error handling granular
- **Cons**: Custo por transicao de estado, overhead para fluxo simples
- **Descartada**: Overengineering para 3 steps sem branching complexo.
## Consequences
### Positivas
- Desacoplamento total entre API e processamento
- Retry automatico com backoff
- DLQ para mensagens que falharam (investigacao e reprocessamento)
- Partial batch failure evita reprocessamento desnecessario
### Negativas
- At-least-once delivery — consumer DEVE ser idempotente
- Sem ordering garantido (Standard Queue)
- Latencia adicional (ms a segundos) entre producao e consumo
docs/architecture/adr/
├── 0001-dynamodb-for-orders.md
├── 0002-sqs-lambda-async-processing.md
├── 0003-report-batch-item-failures.md
├── 0004-floci-local-emulator.md
└── README.md # indice com status de cada ADR
# Architecture Decision Records
| ADR | Titulo | Status | Data |
|-----|--------|--------|------|
| 0001 | DynamoDB para pedidos | Accepted | 2026-03-15 |
| 0002 | SQS+Lambda async | Accepted | 2026-03-15 |
| 0003 | ReportBatchItemFailures | Accepted | 2026-03-20 |
| 0004 | Floci como emulador | Accepted | 2026-04-01 |
Superseded by ADR-XXXX