Arquitetura do Sistema

Diagrama de alto nível

┌─────────────────────────────────────────────────────────────────┐
│                        USUÁRIO FINAL                            │
│  Navegador (crm.galdix.com.br)   WhatsApp (cliente)             │
└──────────────────┬──────────────────────┬───────────────────────┘
                   │                      │
                   ▼                      ▼
┌──────────────────────────┐   ┌──────────────────────────────────┐
│   FRONTEND               │   │   CHATWOOT                       │
│   Next.js 15 + React 19  │   │   (atendimento de agentes)       │
│   crm.galdix.com.br      │   │   Auto-hospedado                 │
│   Porta 3000             │   └──────────────┬───────────────────┘
└──────────┬───────────────┘                  │ webhooks
           │ REST API                         │ API
           ▼                                  ▼
┌─────────────────────────────────────────────────────────────────┐
│                   BACKEND (NestJS)                              │
│                   apicrm.galdix.com.br  Porta 3001              │
│                                                                 │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────────┐  │
│  │ WhatsApp │ │Campaigns │ │   CRM    │ │  ERP / Sync      │  │
│  │  Module  │ │  Module  │ │ Module   │ │  Module          │  │
│  └──────────┘ └──────────┘ └──────────┘ └──────────────────┘  │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────────┐  │
│  │ Config   │ │  Audit   │ │ Redirect │ │  Email Templates │  │
│  │  Module  │ │  Module  │ │  Module  │ │  Module          │  │
│  └──────────┘ └──────────┘ └──────────┘ └──────────────────┘  │
└──────┬──────────────┬──────────────┬──────────────┬────────────┘
       │              │              │              │
       ▼              ▼              ▼              ▼
┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────────┐
│PostgreSQL│  │  Redis   │  │  MinIO   │  │  BullMQ Queues   │
│(pgvector)│  │(cache +  │  │(arquivos │  │  whatsapp-send   │
│ Porta 5432│  │ queues)  │  │  + imgs) │  │  email-send      │
└──────────┘  └──────────┘  └──────────┘  │  campaign-trigger│
                                           │  post-sale-survey│
                                           └──────────────────┘

SERVIÇOS EXTERNOS:
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│  Clerk   │ │   Meta   │ │Evolution │ │   n8n    │ │Millennium│
│  (Auth)  │ │ WhatsApp │ │   API    │ │(automação│ │   ERP    │
│          │ │ Business │ │          │ │)         │ │          │
└──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘

INFRAESTRUTURA:
┌──────────────────────────────────────────────────────────┐
│  Traefik (reverse proxy + TLS)  ← Let's Encrypt          │
│  Docker Compose (3 arquivos obrigatórios)                 │
│  Azure Key Vault (secrets em produção)                    │
└──────────────────────────────────────────────────────────┘

Padrões arquiteturais

Multi-tenancy

Cada organização (empresa cliente) é um tenant isolado. Todos os dados têm organizationId. O TenantInterceptor define o contexto de organização em cada request via AsyncLocalStorage. Nenhuma query retorna dados de outra organização.

Filas assíncronas (BullMQ + Redis)

Operações lentas ou que podem falhar são executadas em filas:

• whatsapp-send: Envio de mensagens WhatsApp de campanha
• email-send: Envio de emails de campanha
• campaign-trigger: Disparo agendado de campanhas
• post-sale-survey: Envio de pesquisa pós-venda

Modo de operação WhatsApp

O sistema suporta dois modos que podem coexistir por loja:

Modo	Descrição	Quando usar
Evolution API	WhatsApp não-oficial via QR code por loja	Lojas físicas com número dedicado
WABA Oficial	Meta Cloud API com número compartilhado	E-commerce, fallback

Guards e segurança

Toda request autenticada passa por:

1. ClerkAuthGuard — valida JWT do Clerk
2. TenantInterceptor — define contexto de organização
3. PermissionsGuard — verifica permissões do papel (role)
4. ReadOnlyGuard — bloqueia mutações para papéis somente-leitura
5. AuditInterceptor — loga ações sensíveis na saída

Componentes externos críticos

Componente	Função	O que acontece se cair
Clerk	Autenticação de usuários	Ninguém consegue logar no frontend
Meta WhatsApp API	Envio de mensagens oficiais	Campanhas falham, webhooks param
Chatwoot	Interface de atendimento dos agentes	Agentes ficam sem ferramenta
Evolution API	WhatsApp por loja física	Lojas físicas ficam sem roteamento
n8n	Automações (respostas de agentes, conversões)	Replies e conversões não são registrados
Millennium ERP	Fonte de verdade de dados	Sync para, dados ficam defasados
MinIO	Armazenamento de imagens e arquivos	Upload de imagens de template falha
Azure Key Vault	Secrets em produção	Deploy falha (não consegue buscar keys)
Redis	Filas, cache, dedup, flags de negócio	Filas param, dedup falha, business hours quebram