Pular para o conteúdo principal

ADR 0001 - Visão de Arquitetura do Serviço

Introdução ao documento​

Este ADR registra as decisões arquiteturais principais observáveis no código atual do serviço de onboarding via WhatsApp. Evidência: src/server.ts:102 Evidência: src/flows/business.ts:132

Versionamento​

  • Versão do documento: 2.0.0.
  • Última atualização: 2026-03-18.
  • Status da decisão: Aceito. Evidência: codex-promts.md:16

Referencial teórico​

  • Architecture Decision Records (ADR).
  • C4 Model para documentação complementar. Evidência: docs/architecture/c4-component.md:1

Contexto​

O serviço precisa:

  • processar payloads criptografados do WhatsApp Flows;
  • orquestrar regras de negócio de onboarding pessoal/empresarial;
  • integrar múltiplas APIs externas;
  • manter envio assíncrono de link de grupo com retry. Evidência: src/server.ts:142 Evidência: src/flows/personal.ts:52 Evidência: src/flows/business.ts:132 Evidência: src/workers/groupLinkDispatchWorker.ts:136

Decisão​

  1. Manter arquitetura monolítica em Node.js/Express com módulos por responsabilidade (routes, flows, features/api, workers).
  2. Persistir localmente em SQLite via Sequelize.
  3. Implementar fila assíncrona com tabela própria e worker em polling no mesmo processo da API.
  4. Expor healthchecks HTTP para integração com probes Kubernetes. Evidência: src/server.ts:36 Evidência: src/server.ts:162 Evidência: src/config/database.ts:8 Evidência: src/models/groupLinkDispatchQueue.ts:122 Evidência: src/server.ts:82 Evidência: src/server.ts:168

Consequências​

Positivas​

  • Simplicidade de deploy e operação inicial (um serviço principal com recursos internos).
  • Menor acoplamento com infraestrutura externa de fila/cache. Evidência: Dockerfile:50 Evidência: src/workers/groupLinkDispatchWorker.ts:182

Negativas​

  • Worker e API compartilham processo, aumentando impacto de falhas e competição por recursos.
  • Dependência de db.sync() para criação de tabelas sem migration completa para fila. Evidência: src/server.ts:82 Evidência: src/server.ts:79 Evidência: src/models/groupLinkDispatchQueue.ts:122

Alternativas consideradas​

  • Separar worker em processo/serviço dedicado.
  • Introduzir broker de mensagens externo (ex.: Redis/queue dedicada).
  • Formalizar migrations completas para todas as entidades. Evidência: ecosystem.config.cjs:16 Evidência: helm/templates/secret.yaml:31 Evidência: src/migrations/20240807154411-create-otp.mjs:5

Pendências​

  • Confirmar roadmap de desacoplamento API/worker.
  • Confirmar estratégia de migração para GroupLinkDispatchQueue. Evidência: ecosystem.config.cjs:16 Evidência: src/models/groupLinkDispatchQueue.ts:122