Pular para o conteúdo principal

C4 - Componentes (L3)

Introdução ao documento​

Este documento descreve os componentes internos do serviço dhedalos-api-onboarding-express com foco em impacto operacional e pontos de quebra. Evidência: src/server.ts:1 Evidência: src/server.ts:162

Versionamento​

  • Versão do documento: 2.0.0.
  • Última atualização: 2026-03-18. Evidência: codex-promts.md:163

Referencial teórico​

  • C4 Model (nível de componente).
  • Mermaid para representação dos fluxos. Evidência: /home/hilton/Documentos/weef/docs-hub/docs/standard/micro-repo.md:12

Responsabilidade do serviço/app​

  • Expor endpoint de callback para WhatsApp Flows (POST /) com decrypt/encrypt.
  • Expor endpoints de OTP e envio de templates protegidos por token de serviço.
  • Expor webhook Meta para recebimento de eventos e resposta automatizada.
  • Gerenciar fila assíncrona para envio de link de grupo. Evidência: src/server.ts:102 Evidência: src/server.ts:162 Evidência: src/routes/webhook.ts:10 Evidência: src/workers/groupLinkDispatchWorker.ts:171

Dependências (DB, cache, fila, storage, externos)​

  • DB/Storage: SQLite (database.sqlite) via Sequelize.
  • Cache: não identificado cache dedicado no runtime atual.
  • Fila: tabela GroupLinkDispatchQueue + worker com polling in-process.
  • Externos: WhatsApp Cloud API, WordPress API, Sebrae API e ViaCEP. Evidência: src/config/database.ts:5 Evidência: src/config/database.ts:8 Evidência: src/models/groupLinkDispatchQueue.ts:122 Evidência: src/workers/groupLinkDispatchWorker.ts:182 Evidência: src/features/api/whatsapp/sendFlowTemplate.ts:10 Evidência: src/features/api/wp/getCourseDetails.ts:13 Evidência: src/features/api/sebrae/getPersonCompanies.ts:12 Evidência: src/features/api/viacep/getAdressByCep.ts:11

Componentes internos agrupados por camada​

Camada de entrada HTTP​

  • src/server.ts: bootstrap do Express, middlewares globais, healthchecks, montagem de rotas.
  • src/routes/*: handlers de recursos (otp, sendTemplate, sendGroupLink, webhook). Evidência: src/server.ts:36 Evidência: src/server.ts:167 Evidência: src/routes/otp.ts:1

Camada de orquestração de fluxo​

  • src/flows/personal.ts: fluxo de onboarding pessoa física.
  • src/flows/business.ts: fluxo de onboarding empresarial com integrações condicionais.
  • src/utils/flowSession.ts: parsing de flow_token. Evidência: src/server.ts:14 Evidência: src/server.ts:15 Evidência: src/utils/flowSession.ts:6

Camada de integração externa​

  • src/features/api/whatsapp/*: envio de templates OTP/flow/link.
  • src/features/api/wp/*: dados de curso, matrícula e perfil.
  • src/features/api/sebrae/* e src/features/api/viacep/*: enriquecimento de dados. Evidência: src/features/api/whatsapp/index.ts:1 Evidência: src/features/api/wp/index.ts:1 Evidência: src/features/api/sebrae/config.ts:3 Evidência: src/features/api/viacep/getAdressByCep.ts:11

Camada de dados e processamento assíncrono​

  • src/models/otp.ts e src/models/groupLinkDispatchQueue.ts: modelos persistentes.
  • src/services/groupLinkDispatchQueue.ts: enfileiramento.
  • src/workers/groupLinkDispatchWorker.ts: consumo e retry. Evidência: src/models/otp.ts:18 Evidência: src/models/groupLinkDispatchQueue.ts:60 Evidência: src/services/groupLinkDispatchQueue.ts:24 Evidência: src/workers/groupLinkDispatchWorker.ts:99

Fluxos críticos (3 a 5)​

  1. Callback criptografado do WhatsApp Flow
  • POST / valida corpo e assinatura, decripta payload, decide fluxo (personal/business) e retorna resposta criptografada. Evidência: src/server.ts:114 Evidência: src/server.ts:128 Evidência: src/server.ts:331 Evidência: src/server.ts:159
  1. Geração e validação de OTP
  • POST /otp gera código e validade de 15 min, persiste e dispara template WhatsApp; POST /otp/confirmation valida existência/expiração. Evidência: src/routes/otp.ts:11 Evidência: src/routes/otp.ts:17 Evidência: src/routes/otp.ts:27 Evidência: src/routes/otp.ts:37
  1. Onboarding e matrícula (fluxos personal/business)
  • Fluxos consultam status de matrícula, atualizam perfil WP, verificam disponibilidade de turma, matriculam e retornam telas. Evidência: src/flows/personal.ts:85 Evidência: src/flows/personal.ts:134 Evidência: src/flows/personal.ts:192 Evidência: src/flows/business.ts:169 Evidência: src/flows/business.ts:602
  1. Envio assíncrono de link de grupo
  • Após matrícula, o serviço enfileira envio e o worker processa com tentativas e reprogramação em falhas. Evidência: src/flows/personal.ts:207 Evidência: src/flows/business.ts:639 Evidência: src/workers/groupLinkDispatchWorker.ts:121 Evidência: src/workers/groupLinkDispatchWorker.ts:136
  1. Webhook Meta inbound/outbound
  • POST /webhook recebe mensagem, responde texto e marca como lida via Graph API. Evidência: src/routes/webhook.ts:16 Evidência: src/routes/webhook.ts:29 Evidência: src/routes/webhook.ts:54

Diagrama Mermaid (C4-like)​

Evidência: src/server.ts:12 Evidência: src/services/groupLinkDispatchQueue.ts:36 Evidência: src/workers/groupLinkDispatchWorker.ts:101 Evidência: src/features/api/wp/getCourseDetails.ts:13

Pendências​

  • Confirmar se a separação entre tabela Otp (model) e Otps (migration) é intencional.
  • Confirmar necessidade de worker dedicado separado de server.ts para isolamento de falhas em produção. Evidência: src/models/otp.ts:33 Evidência: src/migrations/20240807154411-create-otp.mjs:5 Evidência: src/server.ts:82