Documentação Técnica

Como o Dominai CRM funciona?

Um guia completo sobre a arquitetura, segurança e fluxos operacionais da plataforma.

1. Filosofia do Projeto

O Dominai CRM foi concebido como uma camada de abstração robusta sobre a **WhatsApp Business Platform (Cloud API)** da Meta. Ao contrário de integrações informais, ele utiliza protocolos oficiais para garantir estabilidade, escala e segurança jurídica.

Regra de Ouro

O sistema segue a separação estrita de responsabilidades: Controllers não contêm lógica de negócio, Repositories não tomam decisões e toda regra reside em Services ou Orchestrators.

2. Arquitetura de Software

O projeto utiliza um padrão de namespaces moderno (PSR-4) dentro do WordPress:

  • WAS\Core: Responsável pelo boot do plugin, migrações de banco de dados (`dbDelta`) e registro de rotas.
  • WAS\Auth: Gerencia o contexto multi-empresa e as permissões (RBAC).
  • WAS\Meta: O motor de comunicação com a Graph API.
  • WAS\WhatsApp: Lógica específica de mensagens, telefones e contas WABA.
  • WAS\REST: Camada de interface API para o frontend React/Vue ou integrações externas.

3. Multi-Tenancy (Multi-Empresa)

O isolamento de dados é a prioridade. Cada registro nas tabelas operacionais possui um `tenant_id`.

// Exemplo de aplicação do TenantContext
$tenant_id = TenantContext::get_current_tenant_id();
$messages = $messageRepository->find_by_tenant($tenant_id);

O `TenantGuard` intercepta todas as requisições para garantir que um usuário nunca acesse dados de outra empresa, mesmo que tente manipular IDs no frontend.

4. Meta API Client

Não existem URLs da Meta "hardcoded" no sistema. Tudo é centralizado no `MetaEndpointRegistry`, que resolve operações amigáveis para endpoints reais:

// Registro de Endpoints
'messages.send' => '/{phone_number_id}/messages',
'waba.subscribe' => '/{waba_id}/subscribed_apps'

O `MetaApiClient` gerencia automaticamente os headers de autenticação, o logging de requisições e a sanitização de payloads.

5. Segurança & Token Vault

Credenciais da Meta (App Secret e Access Tokens) nunca são salvas em texto puro no banco de dados. Elas passam pelo `TokenVault`, que utiliza criptografia simétrica baseada em uma chave mestre definida no servidor.

Além disso, implementamos o **Security Reveal Pattern**: no painel administrativo, tokens são mascarados e só podem ser revelados após a re-autenticação com a senha do WordPress.

6. O Ciclo do Webhook

Para garantir que nenhuma mensagem seja perdida, seguimos o padrão de **Gravação Imediata**:

  1. O endpoint público recebe o JSON da Meta.
  2. O payload bruto é salvo instantaneamente na tabela `was_webhook_events`.
  3. O sistema responde `200 OK` para a Meta em milissegundos.
  4. Um processo em background (ou trigger pós-save) aciona o `WebhookProcessor`.
  5. O processador identifica o tipo de evento (Mensagem Inbound, Status de Entrega, etc.) e atualiza o CRM.

7. Fluxo de Mensagens

Toda mensagem enviada passa pelo `MessageDispatchService`. Ele valida:

  • Se a janela de 24 horas está aberta (para mensagens de texto livre).
  • Se o número remetente está registrado e ativo.
  • Se o destinatário deu opt-in (quando aplicável).

8. Compliance Meta

Para aprovação no App Review, o sistema inclui nativamente:

  • Privacy Policy & TOS: Gerados dinamicamente com dados do licenciante.
  • Data Deletion Callback: Endpoint obrigatório para que usuários solicitem a exclusão de seus dados via Facebook App Dashboard.
  • Audit Logs: Registro inalterável de quem enviou o quê e quando.