Backend — Visão Geral

O backend do Galdix CRM é uma API REST construída com NestJS, rodando em Node.js, responsável por toda a lógica de negócio, integração com serviços externos e processamento assíncrono de filas.

Localização

/home/crm/app/backend/
├── src/
│   ├── app.module.ts          # Módulo raiz + registro global de guards/interceptors
│   ├── main.ts                # Bootstrap da aplicação
│   ├── common/                # Camada transversal (guards, interceptors, utils)
│   └── modules/               # Módulos de negócio
│       ├── admin/             # Painel de administração
│       ├── audit/             # Trilha de auditoria
│       ├── config/            # Configurações, usuários, roles, lojas
│       ├── crm/               # Inteligência, segmentos, RFM, pós-venda
│       ├── email-templates/   # Templates de email (MJML)
│       ├── erp/               # Sync com Millennium, clientes, vendas
│       ├── integrations/      # WhatsApp (Meta + Evolution), n8n
│       ├── marketing/         # Campanhas, email tracking, segmentação
│       └── redirect/          # Redirecionamento e rastreamento de cliques

Stack

Componente	Tecnologia	Versão
Framework	NestJS	10.x
Runtime	Node.js	20.x (Alpine)
ORM	Prisma	5.x
Banco	PostgreSQL	13
Cache/Filas	Redis + BullMQ	5.x
HTTP externo	Axios (HttpModule)	1.x
Agendamento	@nestjs/schedule (node-cron)	—
Auth	Clerk SDK	5.x
Criptografia	AES-256-GCM (Node crypto)	—
Upload	MinIO SDK (S3-compatible)	—
Email	Nodemailer	—

Porta e endereço

• Porta interna: 3001
• Health check: GET http://localhost:3001/health
• Base URL produção: https://apicrm.galdix.com.br

Módulos de negócio

Módulo	Responsabilidade
admin	Health checks, métricas de sistema, gestão de filas e containers
audit	Log de acesso e ações (acessLog)
config/settings	SMTP, WhatsApp, configurações de campanha, lojas
config/users	Usuários, convites Clerk, roles
config/roles	RBAC — criação e hierarquia de perfis
crm/intelligence	Segmentos dinâmicos, preview de audiência, snapshots diários
crm/post-sale-survey	Pesquisa pós-venda (CSAT/NPS)
email-templates	CRUD de templates MJML, upload de thumbnails
erp/customers	API de clientes, filtros, opt-outs
erp/erp-sync	Sync de vendas (faturamentos) do Millennium ERP
erp/customer-sync	Sync de clientes (cadastros) do Millennium ERP
erp/sales	Recebimento e processamento de vendas
integrations/whatsapp	Templates, mensagens, webhooks Meta, Evolution API
marketing/campaigns	CRUD de campanhas, envio WhatsApp e email, agendamento
marketing/email-tracking	Pixel de abertura, rastreamento de cliques, unsubscribe
redirect	Resolução de token de redirect, opt-out WhatsApp

Padrões arquiteturais

Multi-tenancy via AsyncLocalStorage

Todo request autenticado popula um contexto de tenant via TenantInterceptor usando AsyncLocalStorage. Todos os serviços downstream acessam tenantContext.getStore() para obter organizationId sem precisar passá-lo explicitamente.

Criptografia em repouso

Senhas SMTP, tokens de acesso WhatsApp e outras credenciais são armazenadas cifradas com AES-256-GCM (via EncryptionService). A chave mestre vem de MASTER_ENCRYPTION_KEY no ambiente.

Filas BullMQ

Operações de longa duração (envio de campanhas, sync do ERP) são processadas por workers BullMQ em Redis. Ver Filas BullMQ para topologia completa.

Idempotência

Operações críticas usam jobId fixo no BullMQ para prevenir duplicatas, e a tabela SyncEvent serve como registro de idempotência para webhooks.

Diagrama de camadas

Cliente HTTP
     │
     ▼
[Express + Helmet + CORS + rawBody]
     │
     ▼
[Middleware: CorrelationId → HttpLogger]
     │
     ▼
[Guards: Throttler → ClerkAuth → Roles → Permissions → ReadOnly]
     │
     ▼
[Interceptors: TenantInterceptor → AuditInterceptor]
     │
     ▼
[Controller] → [Service] → [Repository/Prisma] → [PostgreSQL]
                    │
                    ├─→ [BullMQ Queue] → [Processor Worker]
                    ├─→ [MetaGraphService] → [Meta API]
                    ├─→ [ChatwootApiService] → [Chatwoot]
                    ├─→ [EvolutionApiService] → [Evolution]
                    └─→ [MailService] → [SMTP]

Links rápidos

• Ciclo de Requisição — fluxo completo de um request
• Guards & Interceptors — segurança e contexto
• Filas BullMQ — topologia de jobs assíncronos
• Serviços Comuns — encryption, mail, minio, chatwoot-db
• Módulo WhatsApp — classes e métodos do WhatsApp
• Módulo Campanhas — classes e métodos de campanhas