docs: ARCHITECTURE + stubs alinhados ADR-001 (#3)

API.md

@@ -1,5 +1,10 @@
-# API Specification
+# API
 
-## Endpoints
-- POST /solicitar-exclusao-cliente
-- ...
+Especificação viva está no [README](README.md) (rotas, Cognito, curl de lab).
+
+Endpoints:
+
+- `POST /solicitar-exclusao-cliente` (JWT)
+- `GET /status-exclusao/{cliente_id}` (JWT)
+- `POST /confirmar-pagamento` (JWT)
+- `GET /health` (público)

ARCHITECTURE.md

@@ -1,15 +1,44 @@
-# Arquitetura Detalhada
+# Arquitetura — exclusão Pix (canônico)
 
-## Visão Geral
-Ver README.md para diagrama simplificado.
+**Fonte da verdade:** [ADR-001](docs/adr/ADR-001-unificar-exclusao-pix.md) (Accepted) + [README](README.md).
+Este arquivo **não** substitui o ADR; só resume o desenho atual pra agents/humanos.
 
-## Componentes
-- API Gateway
-- Lambda
-- DynamoDB
-- Futuro: Step Functions + SNS/SQS para processamento assíncrono
+## Bounded context
 
-## Decisões de Arquitetura
-- Serverless first
-- Idempotência no nível da aplicação
-- Separação entre código e infraestrutura (dois repositórios)
+Um repo, um stack deployável: `patote85/aws-lambda-api-gateway-python`.
+
+| Pasta | Papel |
+|-------|--------|
+| `lambda/` | Handler Powertools (HTTP API) |
+| `cdk/` | Cognito + DynamoDB + Lambda + HttpApi (JWT) |
+| `tests/` | pytest + moto (sem AWS) |
+| `docs/adr/` | Decisões versionadas |
+
+`aws-api-gateway-cdk` está **arquivado** (banner no README dele) — não usar pra deploy.
+
+## Componentes (hoje)
+
+- **HTTP API** — throttle 100 rps / burst 200; CORS lab localhost (sem `*`)
+- **Lambda** Python 3.12 — `app.lambda_handler`
+- **DynamoDB** — PK `cliente_id` / SK `request_id`, pointer `LATEST`
+- **Cognito User Pool** — JWT nas rotas mutáveis/status; `GET /health` público
+
+## Access pattern Dynamo (obrigatório)
+
+1. Histórico: `SK = <uuid>`
+2. Ponteiro: `SK = LATEST` (espelho do estado corrente)
+3. Status/dedup leem só `LATEST`
+4. Confirmação de pagamento atualiza uuid **e** `LATEST`
+
+## Verificação agent-friendly
+
+```bash
+make check   # ruff + mypy(tests) + pytest + cdk synth
+```
+
+## Não-objetivos (ainda)
+
+- Step Functions / SNS/SQS (event-driven) — ADR futuro
+- WAF / ACM / domínio custom
+- Pix real (stub de lab)
+- Unificar com `aws-crud-api-lambda-dynamodb` (outro BC)

CHANGELOG.md

@@ -1,6 +1,8 @@
 # Changelog
 
-## [Unreleased]
-- Adição de arquivos de documentação completa.
+Histórico útil: merges na `main` + ADRs em `docs/adr/`.
 
-Gerado por Grok Capitão.
+## Unreleased
+
+- Agent-friendly: `make check`, CI `lint`/`test`/`synth` (ruff + mypy + pytest + cdk synth)
+- ADR-001 Accepted — canônico unificado; Cognito JWT; pointer LATEST

DEPLOYMENT.md

@@ -1,6 +1,10 @@
 # Deployment
 
-1. Deploy Lambda
-2. Deploy CDK
+Passos e comandos vivem no [README](README.md) (seção CDK / Deploy + Cognito lab).
 
-Ver README principal.
+Resumo:
+
+1. `make check` (lint + types + pytest + `cdk synth`) — sem AWS
+2. `npx aws-cdk@2 deploy` **só** com CAB aprovado / conta lab
+
+Não há deploy em dois repos: o canônico é este (ADR-001).