Contrasync WhatsApp Bot - Documentação de Arquitetura

Bot do Contrasync no WhatsApp, hospedado como AWS Lambda + API Gateway HTTP, integrado ao Z-API e ao contrasync-nest-api.

---

Stack Tecnológico

Componente	Tecnologia	Versão	Finalidade
Runtime	AWS Lambda Node.js	20	ARM64, 256MB, timeout 30s
Roteador HTTP	API Gateway HTTP API	v2	Webhook do Z-API
IaC	AWS CDK	2.159.x	Provisionamento da stack
Bundler	esbuild	0.24.x	Empacotamento do Lambda
Linguagem	TypeScript	5.5.x	Type-safety
HTTP client	axios	1.7.x	Z-API + nest-api
Gateway WhatsApp	Z-API		Envio e recebimento
Tests	vitest	2.1.x	100% coverage threshold
Observability	CloudWatch Logs (JSON) + X-Ray		Logs estruturados e tracing
Backend	contrasync-nest-api		Persistência e regras de negócio (Postgres compartilhado)

---

Índice de Documentação

Documento	Descrição
Code Style	Padrões obrigatórios herdados do contrasync-nest-api
Project Structure	Organização de arquivos e pastas
Layers	Fluxo Handler → Service → Adapter → Domain
Routing	Rotas HTTP suportadas no Lambda
Connect Flow	Vinculação via OTP diagrama, estados e exemplos de chat
Z-API Integration	Webhook, envio, mapper
Meta Integration	WhatsApp Cloud API: verificação, payload, Graph API, roteamento por provedor
Contrasync API Integration	Endpoints /whatsapp/bot/* + auth
Testing	Convenções e exigência de 100% coverage
Deployment	CDK, env vars, dev server local
Resilience & Observability	Error boundary, logs JSON, alarms

---

Leitura Obrigatória

Antes de iniciar qualquer implementação:

1. Code Style
2. Layers
3. Connect Flow
4. Contrasync API Integration

---

Fluxo de alto nível

WhatsApp → Z-API → API Gateway → Lambda
                                    │
                                    ├──► Z-API (envio)
                                    └──► nest-api (/whatsapp/bot/*)

O Lambda é stateless. Todo estado (vínculo, OTP, idempotência) vive no Postgres compartilhado, acessado via API. O bot decide o que responder com base no que o GET /whatsapp/bot/account devolve.

Detalhes em layers.md e connect-flow.md.

---

Documento atualizado em Maio 2026