Data Model

Overview

ConversionIQ uses four core entities: Workspace, KnowledgeBase, Agent, and ChannelConnection. Workspaces are the primary isolation boundary; KBs, agents, and channel connections are workspace-scoped and must not cross workspace boundaries. Agents are bound to one KB, while channel connections are either directly linked to a KB (social/review families) or indirectly linked through an assigned agent (Chatti Live families).

Entity Relationship Diagram

erDiagram
  Workspace ||--o{ KnowledgeBase : owns
  Workspace ||--o{ Agent : contains
  Workspace ||--o{ ChannelConnection : contains

  KnowledgeBase ||--o{ Agent : assigned_to
  KnowledgeBase ||--o{ ChannelConnection : directly_links

  Agent ||--o{ ChannelConnection : manages_max_4

Entities

Workspace

• Definition: Primary tenant/isolation boundary for operations, automation settings, connected channels, and app configuration.
• Isolation rules: Workspace-scoped data must not be visible across workspaces without explicit authorization.
• Workspace record fields (src/types/workspaces.ts):
  • id, name, description, groupId, ownerId
  • image?, defaultKbId?
  • numberOfKnowledgeBases, numberOfUsers
  • connectedApps, appsActivated
• Ownership: A workspace owns its KBs, agents, and channel connections.

Knowledge Base (KB)

• Definition: Workspace-scoped source of truth for approved facts, voice/tone rules, and compliance constraints used by AI behavior.
• Relationship to Workspace: Each KB belongs to exactly one workspace (workspaceId). New workspaces auto-create one default blank KB (status: "incomplete").
• Relationship to Agents: Agent -> KB is N:1 (knowledgeBaseId required); multiple agents may share one KB.
• Delete rules:
  • KB deletion is blocked when agents are assigned to that KB.
  • A workspace cannot have zero KBs; when a workspace has only one KB, that KB cannot be deleted.

Agent

• Definition: Workspace-scoped live AI runtime entity used by Chatti Live channels.
• Types: The live Agent model applies to Chatti Live. Comment Responder operates independently and does not use this agent model.
• Lifecycle states: draft, inactive, active.
• Core relationships:
  • Belongs to one workspace (workspaceId).
  • Must reference exactly one KB (knowledgeBaseId).
  • Links to channel connection ids via channelIds.
• Connection limit: Domain and route docs define a maximum of 4 linked channel connections per agent.
• Delete rules: Active agents cannot be deleted; they must be deactivated first.

Channel / Channel Connection

• Definition: A channel is a family/type (social comments, review platforms, FB Messenger, web chat, WhatsApp, SMS). A ChannelConnection is a concrete connected profile/number/widget/account instance.
• Two-tier ownership model:
  • Direct KB channels: social comments and review platforms store KB directly on the connection (knowledgeBaseId).
  • Agent-managed channels: FB Messenger, web chat, WhatsApp, SMS derive effective KB from assigned agent (connection -> agent -> knowledgeBaseId).
• Relationship to Workspace: Connections are workspace-scoped (resolved from KB workspace for direct-KB channels; from assigned agent workspace for agent-managed channels).
• Relationship to Agent and KB:
  • Direct-KB channels: connection -> KB.
  • Agent-managed channels: connection -> Agent; KB is agent-derived and read-only at connection level in UI.
• Connection-level fields currently used in the app model:
  • Shared: id, channelType, platform, label, active
  • Social comments: commentType
  • FB Messenger: listening, messengerWelcomeMessage, messengerIceBreakers
  • Web chat: autoVisibility, visibilityDelay
  • SMS: smsCompliance

SMS compliance payload

SMS connections can store a structured 10DLC compliance object on ChannelConnection.smsCompliance.

• Brand registration fields: entity, vertical, displayName, companyName, registrationNumber, brandType, contactPhone, contactEmail, website, address, country, state, city, zipCode
• Campaign registration fields: campaignDescription, messageFlow, privacyPolicyUrl, useCaseType, messageSamples, optInKeywords, optInMessage, optOutKeywords, optOutMessage, helpKeywords, helpMessage, numberPooling, directLending, embeddedLink, embeddedPhone, ageGatedContent, termsAndConditions

State Ownership

Entity	Context	Persistence key	Notes
Workspace	WorkspacesContext	save-workspaces	Stored with groups, KBs, and KB groups in /api/user-data.
KB	WorkspacesContext	save-workspaces	Same persistence envelope as workspaces; workspaceId is canonical scope key.
Agent	AgentsContext	save-agents	Dual-source behavior: remote /live-agents is preferred; local /api/user-data mirror is fallback/persistence cache.
Channel Connection	ChannelsContext	save-connections	Mutations flow through /api/setup-status; resulting connection list is mirrored to /api/user-data.

Cross-Entity Rules

• KB delete is blocked when one or more agents depend on it.
• Workspace delete removes the workspace and its contained KBs; deleting a group does not delete workspaces, it reassigns them to the default group.
• Each agent is scoped to one workspace and one KB; cross-workspace KB assignment is forbidden.
• Agent activation requires a complete KB and at least one connected channel.
• Active agents cannot be deleted.
• Agent-managed channel families derive KB from the assigned agent; direct-KB families store KB on the connection.
• A connection id can belong to only one agent at a time (enforced in agent assignment logic).