Skip to main content

​
Modello dei Dati

Lo schema tipizzato in dettaglio si trova nelle migrazioni Supabase e in packages/database/types.ts. Questa pagina riassume le parti del modello rilevanti per il ragionamento di prodotto e operativo.

​
Regole di progettazione

  • Supabase Postgres è il sistema di registrazione (system of record).
  • I webhook sono memorizzati come record operativi di prima classe.
  • Le conversazioni sono derivate dalla cronologia durevole dei messaggi.
  • Gli outbox job sono righe esplicite, non internals di coda nascosti.
  • Lo scoping per workspace e le RLS sono obbligatori su ogni tabella.

​
Gruppi di entità principali

​
Workspace e accesso

  • workspaces
  • workspace_members
  • api_keys
Queste tabelle ambitano tutti i dati di business e applicano i permessi dell’operatore. api_keys sono ambitate per workspace e utilizzate per l’autenticazione della API REST pubblica v1. Tutte le operazioni sulle chiavi filtrano in base al workspace_id risolto del chiamante — le chiavi di altri workspace non sono mai visibili né operabili.

​
Piano dei canali e dei contatti

  • channels
  • contacts
  • tags
  • contact_tag_links
Queste tabelle definiscono il registro dei numeri WhatsApp, le identità dei contatti normalizzate, lo stato degli iscritti e le primitive di segmentazione.

​
Inbox e ledger dei messaggi

  • conversations
  • messages
  • message_events
La piattaforma tratta lo stato dei messaggi come un ledger append-only. Le righe delle conversazioni sono proiezioni di convenienza su quel ledger, non l’unica fonte di verità.

​
Template, campagne e journey

  • templates
  • campaigns
  • campaign_recipients
  • journeys
Queste tabelle modellano i programmi in uscita, lo stato dei template del provider e le definizioni di automazione.

​
Livello AI e Margaret

  • llm_provider_configs — configurazione del provider LLM per workspace (OpenAI, Anthropic, OpenRouter, Ollama, vLLM). Fa riferimento a segreti memorizzati in Supabase Vault.
  • workspace_secret_bindings — associa un workspace a un segreto Vault denominato (ad es. una chiave API LLM o un token di accesso Meta). I segreti non appaiono mai in colonne in chiaro.
  • ai_agents — definisce una persona dell’agent AI, la selezione del modello, i permessi degli strumenti e le impostazioni di pseudonimizzazione PII per workspace.
  • ai_threads — un thread di contesto di conversazione AI associato a una coppia contatto/conversazione.
  • ai_thread_messages — singoli messaggi all’interno di un thread AI (ruoli user, assistant, tool).
  • ai_agent_executions — log di audit delle esecuzioni di tool-use durante l’esecuzione dell’agent (BORD-140–143). Ogni esecuzione registra l’agent, gli strumenti invocati, input/output e l’esito.

​
Piano dei webhook e operativo

  • webhook_events
  • outbox_jobs
  • audit_logs
Questo è il piano operativo core:
  • webhook_events memorizza le consegne in entrata dal provider e dai partner
  • outbox_jobs memorizza il lavoro asincrono di follow-up, inclusi gli invii di messaggi
  • audit_logs memorizza le azioni dell’operatore e del sistema (modifiche ai membri, cancellazioni GDPR, rotazioni dei segreti, operazioni di scrittura che richiedono revisione)

​
Progettazione webhook-first

I record dei webhook trasportano:
  • origine e topic
  • risultato della verifica
  • chiavi di deduplicazione
  • stato di elaborazione
  • conteggi dei tentativi
  • riepiloghi del payload
Ciò offre alla piattaforma replay, analisi forense e recupero da incidenti senza dipendere da console esterne del provider.

​
Postura Realtime

Lo schema abilita Supabase Realtime su tabelle operative come:
  • conversations
  • messages
  • webhook_events
  • outbox_jobs
  • campaigns
L’uso previsto è per aggiornamenti privati e ambitati per workspace verso l’operatore, non un fan-out illimitato. Vengono utilizzati topic Broadcast piuttosto che Postgres Changes per evitare colli di bottiglia di scalabilità.

​
Nota sull’implementazione attuale

Il repository preserva i contratti di route e UI con un’implementazione tipizzata in-memory in @repo/database quando WHATSAPP_PLATFORM_DATA_MODE=mock. Questa è una scelta di consegna, non uno schema diverso. Lo schema canonico si trova nelle migrazioni Supabase e nei tipi generati.

​
Leggi anche