Data Collections

A reference map of the ~150 MongoDB (Mongoose) collections that back the Oktivo platform — grouped by domain, with why each exists, which UI section depends on it, and which code files read/write it.

How to read this doc. Every collection is a Mongoose model defined in backend/client_backend/src/models/*.ts (a few legacy ones live in backend/client_backend/src/legacy_models/*.ts). The Schema file column is the model file that declares the collection. The Touched by column lists the main route/controller/service/repository files that write it; follow the call chain routes → controllers → services → repositories → models (see the Developer Guide). The UI / feature column links to the dashboard doc that surfaces the data.

Jargon: a collection is MongoDB's equivalent of a SQL table; a Mongoose model is the TypeScript schema + query interface bound to one collection. Most collections are org/customer-scoped — rows carry a customerUID (and often organizationId) so one tenant never sees another's data.

Architecture Overview

How the dashboards map onto the domain groups below:

---

Identity & Org

Who the user is, which org/role they belong to, and the config that governs their tenant. These are read on almost every authenticated request. Primarily surfaced in the Org (Admin) Dashboard and Superadmin Dashboard; also underpin Customer → Account/Settings.

Collection	Why it exists	UI / feature	Touched by (main files)	Schema file
User	Every person who signs in (customer, admin, superadmin); holds role, org link, auth state	Account / Settings, all logins	auth.routes.ts, team.routes.ts, auth.service.ts	models/User.ts
Organization	The tenant that owns customers, numbers, credits and config	Org & Superadmin dashboards	admin.routes.ts, superadmin.routes.ts, organization.service.ts	models/Organization.ts
Role	Named permission sets consumed by requireRole/requirePermission	Team RBAC, Superadmin → Roles	role.routes.ts, RBAC middleware	models/Role.ts
SystemConfig	Global platform defaults (feature flags, provider toggles)	Superadmin → System Config	systemConfig.routes.ts	models/SystemConfig.ts
ConfigVersion	Versioned snapshots of config changes for audit/rollback	Admin → Config Management	config.routes.ts	models/ConfigVersion.ts
OrgConfigReplica	Per-org cached copy of config the agent server reads	Config management, agent runtime	config.service.ts	models/OrgConfigReplica.ts
OrgProviderEnablement	Which voice/LLM providers an org may use	Admin/Superadmin provider setup	admin-provisioning.routes.ts	models/OrgProviderEnablement.ts
ApiToken	Programmatic API keys for the public CRM API	Customer → Settings → API Docs	crm-api.routes.ts, apiToken.service.ts	models/ApiToken.ts
DeviceToken	Push-notification device registrations	Notifications	crmNotification.routes.ts	models/DeviceToken.ts
EmailToken	Short-lived tokens for email verify / password reset	Auth flows	auth.service.ts	models/EmailToken.ts
Kyc	KYC/onboarding verification records for an org	Onboarding / Admin	admin.service.ts	models/Kyc.ts

---

CRM Core

The heart of the Customer → CRM section: leads, contacts, companies, deals, tasks and the fields/segments around them.

Collection	Why it exists	UI / feature	Touched by (main files)	Schema file
CrmLead	The central person/lead record; most CRM data hangs off leadId	CRM → Leads / My Queue	crmLead.routes.ts, crmLead.service.ts, crmLead.repository.ts	models/CrmLead.ts
CrmLeadIdentity	Source-specific identifiers (metaLeadId, formId) deduped onto a lead	Lead import / attribution	crmLeadImport.service.ts	models/CrmLeadIdentity.ts
CrmLeadJourney	Timeline of a lead's stage/touch history	Lead detail timeline	crmLead.service.ts	models/CrmLeadJourney.ts
CrmLeadAttachment	Files attached to a lead	Lead detail	crmLead.controller.ts	models/CrmLeadAttachment.ts
CrmLeadImport	One CSV/API import batch + its status	CRM → Leads → Import	crmLeadImport.routes.ts	models/CrmLeadImport.ts, models/crmLeadImportShared.ts
Contact	Communication contact; joins to a lead via crmLeadId	CRM → Contacts	contact.routes.ts, contact.service.ts	models/Contact.ts
CrmCompany	B2B account a lead/deal belongs to	CRM → Companies	crmCompany.routes.ts	models/CrmCompany.ts
CrmOpportunity	A sales deal tied to a lead (and optionally a company)	CRM → Opportunities	crmOpportunity.routes.ts	models/CrmOpportunity.ts
CrmTask	To-do linked to a lead and/or deal	CRM → Tasks	crmTask.routes.ts	models/CrmTask.ts
CrmReminder	Scheduled reminder on a lead	CRM → Tasks / reminders	crmReminder.routes.ts	models/CrmReminder.ts
CrmSegment	Saved filter definition over leads	CRM → Segments	crmSegment.routes.ts	models/CrmSegment.ts
CrmSegmentMember	Materialised membership of a segment	Segment targeting	crmSegment.service.ts	models/CrmSegmentMember.ts
CrmCustomField	Per-org custom field definitions on leads	CRM settings	crmCustomField.service.ts	models/CrmCustomField.ts
CrmFieldMapping / LeadFieldMapping	Map external source fields → CRM fields	Import / integrations	crmLeadImport.service.ts	models/CrmFieldMapping.ts, models/LeadFieldMapping.ts
CrmColumnMerge / CrmColumnMigrationLedger	Column merge/migration bookkeeping	CRM admin ops	crmColumn.service.ts	models/CrmColumnMerge.ts, models/CrmColumnMigrationLedger.ts
CrmNotification	In-app CRM notifications	Monitor → Notifications	crmNotification.routes.ts	models/CrmNotification.ts
CrmOrgSettings	Per-org CRM behaviour settings	CRM settings	crmOrgSettings.service.ts	models/CrmOrgSettings.ts
CrmCommunicationLog	Log of calls/emails/messages against a lead	Lead activity	crmCommunicationLog.service.ts	models/CrmCommunicationLog.ts
LeadSyncHistory	Record of lead sync runs with external CRMs	Connecter sync	crmSyncLog.service.ts	models/LeadSyncHistory.ts
CrmVisitorIndex / CrmWebEvent / CrmWebSession	Website visitor tracking tied back to leads	Marketing / web attribution	crmWebEvent.service.ts	models/CrmVisitorIndex.ts, models/CrmWebEvent.ts, models/CrmWebSession.ts

CRM core relationships

---

Commerce

Backs Customer → Commerce: stores, inventory, orders and transactions synced from Shopify and friends.

Collection	Why it exists	UI / feature	Touched by (main files)	Schema file
CrmStore	A connected storefront (e.g. Shopify)	Commerce → Stores	crmStore.routes.ts	models/CrmStore.ts
CrmStoreStock	Per-store stock levels	Commerce → Inventory	crmStore.service.ts	models/CrmStoreStock.ts
CrmInventory	Product catalog / inventory items	Commerce → Inventory	crmInventory.routes.ts	models/CrmInventory.ts
CrmOrder	A commerce order linked to a lead/contact	Commerce → Orders	crmOrder.routes.ts	models/CrmOrder.ts
CrmTransaction	Payment/transaction records for orders	Commerce → Transactions	crmTransaction.routes.ts	models/CrmTransaction.ts
CrmAbandonedCheckout	Abandoned-cart events for follow-up calls	Commerce / campaigns	crmAbandonedCheckout.service.ts	models/CrmAbandonedCheckout.ts
CrmCommerceSettings	Per-org commerce behaviour config	Commerce settings	crmCommerceSettings.service.ts	models/CrmCommerceSettings.ts
CrmCommerceCustomField	Custom fields on commerce records	Commerce settings	crmCommerceCustomField.service.ts	models/CrmCommerceCustomField.ts
ShopifyConnectionConfig	Shopify store OAuth/connection details	Connecter → Commerce	crmStore.service.ts	models/ShopifyConnectionConfig.ts

---

Voice / Calling

Backs Customer → Call and Chatbot plus phone-number & provider provisioning on the Org and Superadmin dashboards.

Collection	Why it exists	UI / feature	Touched by (main files)	Schema file
Agent	A voice/chatbot agent config (prompt, voice, tools)	Call and Chatbot → Agents	agent.routes.ts, agent.service.ts	models/Agent.ts
AgentPromptVersion	Version history of an agent's prompt	Agent editor	agent.service.ts	models/AgentPromptVersion.ts
Campaign	A bulk outbound calling campaign	Bulk Calling	campaign.routes.ts, campaign.service.ts	models/Campaign.ts
CampaignReport	Per-campaign roll-up metrics	Campaign report	campaignAnalytics.service.ts	models/CampaignReport.ts
CampaignAnalysis	AI analysis results for a campaign	Campaign analysis	campaignAnalysis.service.ts	models/CampaignAnalysis.ts
CampaignWebhook	Per-campaign webhook config	Campaign settings	campaignWebhook.service.ts	models/CampaignWebhook.ts
HumanCall	Human-handled / transferred call records	Calls / Transfer to Human	humanCall.service.ts	models/HumanCall.ts
TestCall / TrustedTestNumber	Test-call records and allow-listed test numbers	Agent testing	testCall.service.ts	models/TestCall.ts, models/TrustedTestNumber.ts
Voice	Available TTS voices catalog	Agent voice picker	voice.service.ts	models/Voice.ts
PhoneNumber	A phone number owned/managed in the platform	Account → My Numbers	telephony.routes.ts	models/PhoneNumber.ts
PhoneNumberAssignment	Number→agent/org assignment	Number assignment	telephony.service.ts	models/PhoneNumberAssignment.ts
ProvisionedNumber	Numbers provisioned from a carrier	Admin/Superadmin provisioning	admin-provisioning.routes.ts	models/ProvisionedNumber.ts
SIPTrunk	SIP trunk definitions	Superadmin → SIP Trunks	sipTrunk.service.ts	models/SIPTrunk.ts
Provider	Voice/LLM/telephony provider records	Superadmin → Provider Registry	provider.service.ts	models/Provider.ts
ProviderCapacity	Per-provider capacity/limits	Superadmin → Provider Capacity	providerCapacity.routes.ts	models/ProviderCapacity.ts
ProviderModelRegistry	Catalog of provider models	Superadmin → Provider Registry	providerModelRegistry.routes.ts	models/ProviderModelRegistry.ts
ProviderSubUser	Sub-accounts under a provider	Provisioning	provisioning.service.ts	models/ProviderSubUser.ts
ProvisioningAuditLog / ProvisioningIdempotencyKey / ProvisioningRate	Provisioning audit, idempotency & rate records	Provisioning ops	admin-provisioning.routes.ts	models/ProvisioningAuditLog.ts, models/ProvisioningIdempotencyKey.ts, models/ProvisioningRate.ts
Conversations (legacy)	Raw call/chat conversation transcripts	Call history / analysis	legacy_models consumers	legacy_models/Conversations.ts

---

Analysis & Tools

Powers analysis schemas, benchmarks, dynamic tools and knowledge bases — surfaced under Call and Chatbot and Monitor → Analytics.

Collection	Why it exists	UI / feature	Touched by (main files)	Schema file
AnalysisSchema	Defines the fields extracted from a call by AI	Analysis Schemas	analysisSchema.routes.ts	models/AnalysisSchema.ts
Analysis (legacy)	Stored per-call analysis results	Call analysis	legacy_models consumers	legacy_models/Analysis.ts
Benchmark / BenchmarkRun	Model benchmark definitions and runs	Superadmin → Benchmarks	benchmark.routes.ts	models/Benchmark.ts, models/BenchmarkRun.ts
DynamicTool / DynamicToolLog	Agent-callable tools and their call logs	Connecter → Client Tools	dynamic-tool.routes.ts	models/DynamicTool.ts, models/DynamicToolLog.ts
SharedDynamicTool	Tools shared across orgs	Tool library	dynamicTool.service.ts	models/SharedDynamicTool.ts
ApiAction / ApiActionLog	Templated outbound API actions + logs	Automation / API Actions	apiAction.service.ts	models/ApiAction.ts, models/ApiActionLog.ts
McpIntegration / McpToolCallLog	MCP server integrations and tool-call logs	Connecter → MCP	mcp-integration.routes.ts	models/McpIntegration.ts, models/McpToolCallLog.ts
KnowledgeBase / KnowledgeBasePage	Agent knowledge base + crawled pages	Knowledge Base	knowledge-base.routes.ts	models/KnowledgeBase.ts, models/KnowledgeBasePage.ts
ContactObservability	Per-contact observability/trace data	Monitor / debugging	contactObservability.service.ts	models/ContactObservability.ts

---

Billing & Credits

Backs Customer → Account (Credits/BYOK) and the billing screens on the Org / Superadmin dashboards.

Collection	Why it exists	UI / feature	Touched by (main files)	Schema file
CreditTransaction	Ledger of credit debits/credits per org	Account → Credits, Credit Mgmt	credit.routes.ts, credit.service.ts	models/CreditTransaction.ts
Ledger (legacy)	Legacy credit/billing ledger	Billing history	legacy_models/billing.controller.ts	legacy_models/Ledger.ts
Purchase (legacy)	Legacy purchase records	Billing history	legacy_models/billing.routes.ts	legacy_models/Purchase.ts
BillingDetails	Org billing/invoice details	Billing settings	billingDetails.service.ts	models/BillingDetails.ts
PaymentConfig	Per-org payment gateway config	Admin → Payment Gateway	payment.routes.ts	models/PaymentConfig.ts
PaymentOrder	A payment/checkout order	Credits purchase	payment.service.ts	models/PaymentOrder.ts
ServicePricing	Platform service price list	Superadmin → Pricing	servicePricing.routes.ts	models/ServicePricing.ts
CustomerAddonPricing / CustomerFeePricing	Per-org add-on and fee overrides	Per-Org Rates	admin-provisioning.routes.ts	models/CustomerAddonPricing.ts, models/CustomerFeePricing.ts
CustomerProviderCredential	Org-scoped provider credentials (BYOK context)	BYOK	byok.service.ts	models/CustomerProviderCredential.ts
ByokKey / ByokAuditLog	Bring-Your-Own-Key secrets + audit	Account → BYOK	byok.routes.ts	models/ByokKey.ts, models/ByokAuditLog.ts

---

Chatbot / WhatsApp / Marketing Channels

Backs Customer → Marketing, Automation and the chat/WhatsApp parts of Connecter.

Collection	Why it exists	UI / feature	Touched by (main files)	Schema file
Chatbot / ChatbotConversation / ChatbotLead	AI chatbot config, chats, and captured leads	AI Chatbot	chatbot.routes.ts	models/Chatbot.ts, models/ChatbotConversation.ts, models/ChatbotLead.ts
WhatsAppConnection / WhatsAppOrgConfig	WhatsApp Business account connection + org config	Connecter → WhatsApp	whatsAppConnection.routes.ts	models/WhatsAppConnection.ts, models/WhatsAppOrgConfig.ts
WhatsAppTemplate / WhatsAppBroadcast	Message templates and broadcast sends	WhatsApp marketing	whatsApp.service.ts	models/WhatsAppTemplate.ts, models/WhatsAppBroadcast.ts
WhatsAppInboxMessage	Inbound/outbound WA inbox messages	WhatsApp inbox	whatsApp.service.ts	models/WhatsAppInboxMessage.ts
WaCampaign / WaCampaignRecipient	WhatsApp campaigns + recipients	WhatsApp campaigns	waCampaign.service.ts	models/WaCampaign.ts, models/WaCampaignRecipient.ts
WaAutomationDefinition / WaAutomationRun	WhatsApp automation flows + runs	WhatsApp Automation	waAutomation.routes.ts	models/WaAutomationDefinition.ts, models/WaAutomationRun.ts
WaFlowDefinition / WaFunnel / WaFunnelProgress	Flow/funnel definitions and per-lead progress	Automation funnels	waAutomation.service.ts	models/WaFlowDefinition.ts, models/WaFunnel.ts, models/WaFunnelProgress.ts
WaEngagementEvent / WaEngineState / WaOptOut	WA engagement events, engine state, opt-outs	Automation / compliance	waAutomation.service.ts	models/WaEngagementEvent.ts, models/WaEngineState.ts, models/WaOptOut.ts
MetaConnection / MetaPageSubscription	Meta (Facebook) account connection + page subs	Connecter → Facebook	metaConnection.routes.ts	models/MetaConnection.ts, models/MetaPageSubscription.ts
MetaAdCampaign / MetaCustomAudience / MetaAudienceMember / MetaAudiencePush	Meta ad campaigns and custom-audience sync	Marketing → Meta Ads	metaAds.service.ts	models/MetaAdCampaign.ts, models/MetaCustomAudience.ts, models/MetaAudienceMember.ts, models/MetaAudiencePush.ts
MetaCapiEventLog	Meta Conversions API event log	Attribution	metaCapi.service.ts	models/MetaCapiEventLog.ts
GoogleAdsConnection / GoogleAdsOrgConfig / GoogleAdsAdCampaign / GoogleAdsAudience / GoogleAdsWebhookConfig	Google Ads connection, config, campaigns & audiences	Connecter → Google Ads	googleAdsConnection.routes.ts	models/GoogleAds*.ts
Ga4Connection	Google Analytics 4 connection	Connecter → Analytics	ga4Connection.routes.ts	models/Ga4Connection.ts
GmailConnection / GmailOrgConfig	Gmail connection + org config	Connecter → Gmail	gmail.routes.ts	models/GmailConnection.ts, models/GmailOrgConfig.ts
GoogleSheetConfig	Google Sheets sync config	Connecter → Sheets	googleSheetsConfig.routes.ts	models/GoogleSheetConfig.ts
ApolloSavedSearchConfig	Apollo saved-search enrichment config	Connecter → Apollo	apollo.routes.ts	models/ApolloSavedSearchConfig.ts
LandingLead	Leads captured from landing pages	Marketing	landingLead.service.ts	models/LandingLead.ts

---

Tickets

Backs the Customer → Tickets section and the ticket views on the Org dashboard.

Collection	Why it exists	UI / feature	Touched by (main files)	Schema file
Ticket	A support ticket	Tickets → Overview	ticket.routes.ts, ticket.service.ts	models/Ticket.ts
TicketMessage	Messages/replies on a ticket	Ticket detail	ticket.service.ts	models/TicketMessage.ts
TicketEvent	Audit/activity events on a ticket	Ticket timeline	ticket.service.ts	models/TicketEvent.ts
TicketExternalLink	Links to external systems	Ticket integrations	ticket.service.ts	models/TicketExternalLink.ts
TicketMailbox	Email mailbox that feeds tickets	Tickets → Integrations	ticketMailbox.service.ts	models/TicketMailbox.ts
TicketProviderConfig	Per-provider ticket integration config	Tickets → Integrations	ticket.service.ts	models/TicketProviderConfig.ts
TicketRoutingRule	Rules that route tickets to agents/teams	Tickets → Routing	ticket.service.ts	models/TicketRoutingRule.ts
TicketSettings	Per-org ticket settings	Tickets → Settings	ticket.service.ts	models/TicketSettings.ts
TicketSlaPolicy	SLA policies applied to tickets	Tickets → SLA	ticket.service.ts	models/TicketSlaPolicy.ts

---

Integrations / CRM Connect

Backs Customer → Connecter: external CRM sync, OAuth apps, email templates, workflows and webhooks.

Collection	Why it exists	UI / feature	Touched by (main files)	Schema file
CrmConnection	A configured external CRM connection	Connecter	crmConnection.service.ts	models/CrmConnection.ts
CrmProviderApp / CrmProviderConnection	Provider app definitions and per-org connections	Connecter	crmProvider.service.ts	models/CrmProviderApp.ts, models/CrmProviderConnection.ts
CrmOAuthClient	OAuth client credentials for CRM connect	Superadmin → OAuth Clients	crmOAuth.service.ts	models/CrmOAuthClient.ts
CrmSyncLog / CrmSheetSyncRun / CrmBackfillState	Sync logs, sheet sync runs and backfill cursors	Connecter sync status	crmSync.service.ts	models/CrmSyncLog.ts, models/CrmSheetSyncRun.ts, models/CrmBackfillState.ts
CrmEmailTemplate / CrmEmailRead	Email templates and open/read tracking	CRM email	crmEmail.service.ts	models/CrmEmailTemplate.ts, models/CrmEmailRead.ts
CrmAgenticSettings	Config for agentic automation on leads	CRM → Agentic Automation	crmAgenticSettings.routes.ts	models/CrmAgenticSettings.ts
Workflow / WorkflowRun	Automation workflow definitions + executions	Automation → Auto Workflow	workflow.routes.ts	models/Workflow.ts, models/WorkflowRun.ts
WebhookEndpoint / WebhookDeliveryLog	Outbound webhook endpoints and delivery logs	Connecter → Webhooks	webhook.routes.ts	models/WebhookEndpoint.ts, models/WebhookDeliveryLog.ts

---

Ops / Misc

Cross-cutting operational collections not tied to one dashboard section.

Collection	Why it exists	UI / feature	Touched by (main files)	Schema file
Attendance / AttendanceConfig / AttendancePing	Agent attendance tracking + heartbeats	Monitor / agent perf	attendance.service.ts	models/Attendance.ts, models/AttendanceConfig.ts, models/AttendancePing.ts
DndContact	Do-Not-Disturb suppression list	Monitor → DND	dndContact.routes.ts	models/DndContact.ts
BugReport	In-app bug reports	Superadmin → Bug Reports	bug-report.routes.ts	models/BugReport.ts
EmailLog	Sent-email audit log	Notifications / ops	emailLog.service.ts	models/EmailLog.ts

---

How to Test

Collections are verified indirectly through the features that write them. To confirm a collection is live:

1. Perform the UI action in the linked dashboard section (e.g. create a lead in CRM → Leads).
2. In MongoDB, query the collection named in the Schema file model registration (e.g. db.CrmLead.find().sort({createdAt:-1}).limit(1)).
3. Confirm the new document carries the tenant scope fields (customerUID, and organizationId where applicable).

Troubleshooting

Symptom	Cause	Fix
Data saved but not visible to another user in the same org	Query not scoped to customerUID/organizationId, or user lacks role/permission	Check the resolver/permission middleware (see Auth System / Team RBAC)
Collection name in Mongo differs from the model name	A few models pass an explicit collection name (e.g. CrmReminder uses collection: "CrmReminder")	Open the model file and read the mongoose.model(name, schema, collection) call
Legacy collection not updating	Legacy models (Analysis, Conversations, Ledger, Purchase) live in legacy_models/ and are written by legacy controllers	Trace the legacy controller, not a services/ file
New field not persisted	Field missing from the Mongoose schema (strict mode drops unknown keys)	Add the field to the model in models/*.ts