Skip to main content

​
Modelo de Dados

O esquema tipado detalhado vive nas migrations do Supabase e em packages/database/types.ts. Esta página resume as partes do modelo que importam para o raciocínio de produto e operacional.

​
Regras de design

  • O Supabase Postgres é o sistema de registro.
  • Webhooks são armazenados como registros operacionais de primeira classe.
  • Conversas são derivadas de um histórico de mensagens durável.
  • Jobs de outbox são linhas explícitas, não detalhes internos ocultos de queue.
  • O escopo por workspace e o RLS são obrigatórios em toda tabela.

​
Grupos centrais de entidades

​
Workspace e acesso

  • workspaces
  • workspace_members
  • api_keys
Essas tabelas delimitam todos os dados de negócio e aplicam as permissões do operador. api_keys são delimitadas por workspace e usadas para autenticação da API REST pública v1. Todas as operações com chaves filtram pelo workspace_id resolvido do chamador — chaves de outros workspaces nunca são visíveis nem operáveis.

​
Plano de canal e contato

  • channels
  • contacts
  • tags
  • contact_tag_links
Essas tabelas definem o registro de números de WhatsApp, as identidades de contato normalizadas, o estado de assinante e as primitivas de segmentação.

​
Caixa de entrada e ledger de mensagens

  • conversations
  • messages
  • message_events
A plataforma trata o estado de mensagens como um ledger somente de inserção (append-only). As linhas de conversation são projeções de conveniência sobre esse ledger, não a única fonte de verdade.

​
Templates, campanhas e jornadas

  • templates
  • campaigns
  • campaign_recipients
  • journeys
Essas tabelas modelam programas de saída, o estado de template do provider e as definições de automação.

​
Camada de IA e Margaret

  • llm_provider_configs — configuração de provider de LLM por workspace (OpenAI, Anthropic, OpenRouter, Ollama, vLLM). Referencia segredos armazenados no Supabase Vault.
  • workspace_secret_bindings — mapeia um workspace para um segredo nomeado do Vault (por exemplo, uma chave de API de LLM ou um token de acesso da Meta). Segredos nunca aparecem em colunas em texto puro.
  • ai_agents — define a persona de um agente de IA, a seleção de modelo, as permissões de ferramentas e as configurações de pseudonimização de PII por workspace.
  • ai_threads — uma thread de contexto de conversa de IA associada a um par contato/conversa.
  • ai_thread_messages — mensagens individuais dentro de uma thread de IA (papéis de user, assistant, tool).
  • ai_agent_executions — log de auditoria das execuções de uso de ferramentas durante a execução do agente (BORD-140–143). Cada execução registra o agente, as ferramentas invocadas, entrada/saída e o resultado.

​
Plano de webhook e operacional

  • webhook_events
  • outbox_jobs
  • audit_logs
Este é o plano operacional central:
  • webhook_events armazena entregas de provider e de parceiros recebidas
  • outbox_jobs armazena trabalho assíncrono de acompanhamento, incluindo envios de mensagem
  • audit_logs armazena ações de operadores e do sistema (mudanças de membros, exclusões por LGPD/GDPR, rotações de segredo, operações de escrita que precisam de revisão)

​
Design orientado a webhook (webhook-first)

Os registros de webhook trazem:
  • origem e tópico
  • resultado da verificação
  • chaves de deduplicação
  • status de processamento
  • contagens de tentativas
  • resumos de payload
Isso dá à plataforma capacidade de replay, forense e recuperação de incidentes sem depender de consoles externos de provider.

​
Postura de realtime

O esquema habilita o Supabase Realtime em tabelas operacionais como:
  • conversations
  • messages
  • webhook_events
  • outbox_jobs
  • campaigns
O uso pretendido é o de atualizações privadas do operador, delimitadas por workspace, não de distribuição irrestrita (fan-out). Tópicos de broadcast são usados em vez de Postgres Changes para evitar gargalos de escalabilidade.

​
Nota sobre a implementação atual

O repositório preserva os contratos de rota e de UI com uma implementação tipada em memória em @repo/database quando WHATSAPP_PLATFORM_DATA_MODE=mock. Isso é uma escolha de entrega, não um esquema diferente. O esquema canônico vive nas migrations do Supabase e nos tipos gerados.

​
Leia a seguir