Domain Model
Field-level schemas for all core domain objects in the Helvia Platform platform. Source of truth: hbf-core (Java/Kotlin, MongoDB). Consumer types: hbf-core-api (TypeScript). Last updated: 2026-03-19
Object Map
Core Objects
Organization
Top-level container for all resources. Multi-tenant boundary.
| Field | Type | Required | Notes |
|---|---|---|---|
id | String | yes | PK |
displayName | String | yes | |
image | String | no | Logo URL |
timezone | String | no | Default: "UTC" |
dataRetentionPeriod | Int | no | Days |
auditLogsRetentionPeriod | Int | no | Days |
loginSettings | LoginSettings | no | SSO, branding, auto-creation |
Collection: organizations
Full schema: docs/domain-model/organization.md
TypeScript: hbf-core-api/src/datamodel/organization.ts
Tenant
A single chatbot instance within an Organization. Contains all bot content, settings, and deployment config.
| Field | Type | Required | Notes |
|---|---|---|---|
id | String | yes | PK |
displayName | String | no | |
organization | Organization | yes | @DBRef lazy |
content | BotContent | no | @DBRef lazy |
settings | TenantSettings | yes | User-editable settings |
systemSettings | TenantSystemSettings | yes | Moderator-level settings |
nlpMap | Map<String, String> | no | Language to NLPPipeline ID |
powerups | List<Powerup> | yes | Enabled features |
space | Space | yes | BOT_LAB, CX, EX |
Collection: tenants
Full schema: docs/domain-model/tenant.md
TypeScript: hbf-core-api/src/datamodel/tenant.ts
User
Platform user with roles across Organizations and Tenants.
| Field | Type | Required | Notes |
|---|---|---|---|
id | String | yes | PK |
email | String | yes | @Indexed |
password | String | yes | Hashed |
fullName | String | yes | |
isModerator | Boolean | yes | |
organizations | List<Organization> | yes | @DBRef lazy |
tenantRoles | Map<String, Map<String, Set<TenantRole>>> | yes | org -> tenant -> roles |
organizationRoles | Map<String, Set<OrganizationRole>> | yes | org -> roles |
Collection: users
Full schema: docs/domain-model/user.md
TypeScript: hbf-core-api/src/datamodel/user.ts
ChatSession
A single conversation session between a subscriber and a bot.
| Field | Type | Required | Notes |
|---|---|---|---|
id | String | yes | PK |
uuid | String | yes | @Indexed unique |
tenant | Tenant | no | @DBRef lazy |
status | ChatSessionStatus | yes | ACTIVE, COMPLETED |
messages | List<ChatSessionMessage> | yes | Embedded |
liveChats | List<LiveChatSession> | no | Embedded |
metadata | ChatSessionMetadata | no | Deployment info, subscriber info |
intents | Map<String, Int> | no | Intent name to count |
Collection: chat-sessions
Full schema: docs/domain-model/chat-session.md
TypeScript: hbf-core-api/src/datamodel/chat_session.ts
ChatSessionMessage
A single message within a ChatSession. Embedded in ChatSession.messages.
| Field | Type | Required | Notes |
|---|---|---|---|
id | String | no | Set by hbf-bot |
message | String | no | Message text |
type | ChatSessionMessageType | no | TEXT, POSTBACK, ATTACHMENT, TRIGGER |
category | ChatSessionMessageCategory | no | COMMON, FEEDBACK, FALLBACK, LIVE_CHAT, BACK |
isUserInteraction | Boolean | no | |
liveChatEventType | LiveChatEventType | no | For live chat messages |
date | Date | no | Timestamp |
Embedded in: ChatSession.messages
Full schema: docs/domain-model/chat-session-message.md
TypeScript: hbf-core-api/src/datamodel/chat_session.ts
BotContent
Container for all bot activities (flows). One per Tenant.
| Field | Type | Required | Notes |
|---|---|---|---|
id | String | yes | PK |
activities | List<Activity> | yes | Default empty |
mainActivity | String | no | Activity ID of entry point |
staticVariables | List<StaticVariable> | yes | Bot-level variables |
Collection: bot-contents
Full schema: docs/domain-model/bot-content.md
TypeScript: hbf-core-api/src/datamodel/botContent.ts
BotDeployment
A deployment of a bot to a specific messaging platform.
| Field | Type | Required | Notes |
|---|---|---|---|
id | String | yes | PK |
handle | String | yes | @Indexed unique, deployment identifier |
platform | MessagingPlatform | yes | |
displayName | String | no | |
tenant | Tenant | yes | @DBRef lazy |
messagingApp | MessagingApp | no | @DBRef lazy |
settings | BotDeploymentSettings | yes | Layout + integration config |
isPreview | Boolean | no |
Collection: bot-deployments
Full schema: docs/domain-model/bot-deployment.md
TypeScript: hbf-core-api/src/datamodel/botDeployment.ts
KnowledgeBase
A collection of knowledge articles, shared across Tenants within an Organization.
| Field | Type | Required | Notes |
|---|---|---|---|
id | String | yes | PK |
name | String | yes | |
organization | Organization | yes | @DBRef lazy |
type | KnowledgeBaseType | yes | INTERNAL, INTEGRATION, SHARED |
tenantAssociations | Set<TenantAssociation> | no | Tenants using this KB |
languages | Set<KnowledgeBaseLanguage> | no |
Collection: knowledge-bases
Full schema: docs/domain-model/knowledge-base.md
TypeScript: hbf-core-api/src/datamodel/knowledgeBase.ts
Integration
Polymorphic external service integration (OIDC, CRM, LLM, Livechat, Ticketing, Translation).
| Field | Type | Required | Notes |
|---|---|---|---|
id | String | yes | PK |
name | String | yes | |
type | IntegrationType | yes | Discriminator for polymorphism |
category | IntegrationCategory | yes | |
enabled | Boolean | no | |
organization | Organization | yes | @DBRef lazy |
Collection: integrations
Full schema: docs/domain-model/integration.md
TypeScript: hbf-core-api/src/datamodel/integration.ts
NLPPipeline
Polymorphic NLP/NLU engine configuration (LUIS, OpenAI, Dialogflow, Helvia).
| Field | Type | Required | Notes |
|---|---|---|---|
id | String | yes | PK |
name | String | yes | |
type | NLPType | yes | Discriminator for polymorphism |
language | String | yes | Primary language |
status | NLPStatus | no | CREATED, OUTDATED, TRAINING, FAILED, READY, INITIALIZING |
organization | Organization | yes | @DBRef lazy |
tenant | Tenant | yes | @DBRef lazy |
Collection: nlp-pipelines
Full schema: docs/domain-model/nlp-pipeline.md
TypeScript: hbf-core-api/src/datamodel/nlp.ts
Subscriber
An end-user of a bot, identified by a platform-specific handle.
| Field | Type | Required | Notes |
|---|---|---|---|
id | String | yes | PK |
handle | String | yes | @Indexed unique, platform user ID |
fullName | String | no | |
email | String | no | |
tenant | Tenant | yes | @DBRef lazy, @Indexed |
blackboard | BasicDBObject | no | Runtime state storage |
customData | BasicDBObject | no |
Collection: subscribers
Full schema: docs/domain-model/subscriber.md
TypeScript: hbf-core-api/src/datamodel/user.ts
Broadcast
A message broadcast to groups of subscribers.
| Field | Type | Required | Notes |
|---|---|---|---|
id | String | yes | PK |
label | String | yes | |
tenant | Tenant | yes | @DBRef lazy |
groups | List<Group> | yes | @DBRef lazy |
status | BroadcastStatus | yes | @Indexed |
type | BroadcastType | yes | |
method | BroadcastMethod | yes | |
platform | MessagingPlatform | yes |
Collection: broadcasts
Full schema: docs/domain-model/broadcast.md
TypeScript: hbf-core-api/src/datamodel/broadcast.ts
MessagingApp
Platform-specific messaging application configuration.
| Field | Type | Required | Notes |
|---|---|---|---|
id | String | yes | PK |
appId | String | yes | @Indexed unique |
appName | String | yes | @Indexed unique |
platform | MessagingPlatform | yes | |
config | MessagingAppConfigurations | yes | Platform-specific config |
Collection: messaging-apps
Full schema: docs/domain-model/messaging-app.md
TypeScript: hbf-core-api/src/datamodel/messaging_app.ts
Survey
Survey responses collected from a ChatSession.
| Field | Type | Required | Notes |
|---|---|---|---|
id | String | yes | PK |
tenantId | String | yes | |
chatSession | ChatSession | no | @DBRef lazy |
subscriber | String | yes | Subscriber ID |
questions | List<SurveyQuestion> | yes | |
type | SurveyType | no | INTERVIEW, LIVECHAT, USER_FEEDBACK |
Collection: surveys
Full schema: docs/domain-model/survey.md
TypeScript: hbf-core-api/src/datamodel/survey.ts
FlowGraphNode (hierarchy)
Polymorphic node within a bot flow graph. 36 subtypes.
| Field | Type | Required | Notes |
|---|---|---|---|
id | String | yes | |
type | FlowGraphNodeType | yes | Discriminator |
label | Localized<String> | yes | |
action | ConversationAction | no | |
position | FlowGraphPosition | no | x, y coordinates |
Embedded in: FlowGraphContent.nodes (within Activity)
Full schema: docs/domain-model/flow-graph-nodes.md
TypeScript: hbf-core-api/src/datamodel/botContent.ts (compiled form)
Other MongoDB Documents
BotContentCompiled
Pre-compiled version of BotContent for runtime execution. One per Tenant.
| Field | Type | Notes |
|---|---|---|
id | String | PK |
activities | List<ActivityCompiled> | |
customActivities | List<ActivityCompiled> | |
metadata | BotContentCompilationMetadata |
Collection: bot-contents-compiled
Group
A named group of subscribers, used for broadcasts.
| Field | Type | Notes |
|---|---|---|
id | String | PK |
tenant | Tenant | @DBRef lazy, @Indexed |
label | String | Group name |
handle | String | @Indexed |
subscribers | Set<String> | Subscriber IDs |
platform | MessagingPlatform | |
active | Boolean |
Collection: groups
KnowledgeBaseGroup
A named group of articles within a KnowledgeBase. Created automatically when files are synced from external sources (e.g., Azure Blob). One group per source file.
| Field | Type | Notes |
|---|---|---|
id | String | PK |
name | String | Group name (= file name for synced KBs) |
sourceId | String | Stable opaque identifier for the source item. Format for Azure Blob: azb_<sha256base64url> (hash of azure:<account>:<container>:<blobPath>) |
knowledgeBase | KnowledgeBase | @DBRef lazy |
organization | Organization | @DBRef lazy |
source | String | Provider type string, e.g. AZURE_BLOB |
Collection: knowledge-base-groups
Tag
Organization-scoped label applied to tenants or chat sessions.
| Field | Type | Notes |
|---|---|---|
id | String | PK |
label | String | Tag name |
scope | TagScope | TENANTS or CHAT_SESSIONS |
organization | Organization | @DBRef lazy |
Collection: tags
AuditLog
Record of a change to any domain object.
| Field | Type | Notes |
|---|---|---|
id | String | PK |
objectId | String | @Indexed, ID of modified object |
collection | String | MongoDB collection name |
payload | String | JSON serialization of modified object |
description | String | |
category | AuditCategory | ACCESS_CONTROL, CONTENT, BOT_SETTINGS, BOT_DEPLOYMENTS, ORG_SETTINGS, ORG_MANAGEMENT |
organization | Organization | @DBRef lazy |
Collection: audit-logs
ApiToken
API access token scoped to an Organization with role-based permissions.
| Field | Type | Notes |
|---|---|---|
id | String | PK |
token | String | Token value |
role | OrganizationRole | |
tenantRoles | Map<String, Set<TenantRole>> | |
organization | Organization | @DBRef lazy |
issuedBy | String | User who created it |
Collection: api-tokens
UserInvitation
Pending invitation for a user to join an Organization.
| Field | Type | Notes |
|---|---|---|
id | String | PK |
email | String | @Indexed |
status | UserInvitationStatus | ACCEPTED, PENDING, EXPIRED, REVOKED |
organization | Organization | @DBRef lazy |
tenantRoles | Map | Roles to grant on acceptance |
expirationDate | Date |
Collection: user-invitations
TestSet
A set of test cases for NLP validation.
| Field | Type | Notes |
|---|---|---|
id | String | PK |
name | String | |
tenant | Tenant | @DBRef lazy |
language | LanguageCode | |
cases | List<TestSetCase> | Input/expected intent pairs |
Collection: test-sets
TenantStats
Aggregated statistics for a Tenant.
| Field | Type | Notes |
|---|---|---|
id | String | PK |
tenant | Tenant | @DBRef lazy |
lastStatsUpdate | Date | |
data | BasicDBObject | Key-value stats |
Collection: tenant-stats
Key Enums
MessagingPlatform
MICROSOFT_TEAMS, MICROSOFT_WEB_CHAT, VIBER, FACEBOOK, LIVECHAT, SLACK, INSTAGRAM, UNITY, WHATSAPP, API, ZENDESK
TenantRole
HBF_TENANT_ADMIN, HBF_TENANT_EDITOR, HBF_TENANT_VIEWER, HBF_TENANT_LIVECHAT_ADMIN
OrganizationRole
HBF_ORG_ADMIN, HBF_ORG_EDITOR, HBF_ORG_VIEWER, HBF_ORG_LIVE_AGENT, HRWIZ_EMPLOYEE, HBF_ORG_LIVECHAT_ADMIN
Powerup (feature flags)
HRWIZ, FAQS, BROADCASTS, FLOWS, LIVECHAT, SURVEYS, INTERVIEWS, CHAT_SESSIONS, SENTIMENT_ANALYSIS, ANALYTICS, SETTINGS, BACKUPS, INTEGRATIONS, BILLING, MONITORING, NLU_CACHING, CONNECTORS
Space
BOT_LAB, CX, EX
LanguageCode (28 values)
EN, EL, ES, PT, PT_BR, IT, FR, DE, FI, BG, CS, NL, ET, HE, PL, RO, RU, SR, SL, SV, TR, UK, ZH, FIL, NO, HR, HU, DA
IntegrationType
OIDC_AUTHENTICATION, MICROSOFT_DYNAMICS_CRM, MICROSOFT_DYNAMICS_KB, AZURE_BLOB_STORAGE_KB, CISCO_LIVECHAT, HELVIA_LIVECHAT, ZENDESK_LIVECHAT, GENESYS_LIVECHAT, AZURE_AI_LLM, OPEN_AI_LLM, GEMINI_AI_LLM, ZENDESK_TICKETING, GOOGLE_TRANSLATION
IntegrationCategory
AUTHENTICATION, CRM, KB, LIVECHAT, LLM, TICKETING, TRANSLATION
NLPType
LUIS_NLP, OPENAI_NLP, HELVIA_NLP_SPECIFICATION, HELVIA_RAG_PIPELINE, DIALOGFLOW_NLP, HELVIA_GPT
NLPStatus
CREATED, OUTDATED, TRAINING, FAILED, READY, INITIALIZING
FlowGraphNodeType (36 values)
EMPTY, INTRO, SELECT, MESSAGE, MEDIA, OPTION, MULTI_OPTION, DYNAMIC_MULTI_OPTION, TEXT_INPUT, SWITCH_CASE, SWITCH_VARIABLE, SWITCH_QUERY, SEND_STORED_DATA, HTTP_REQUEST, MISSED_QUESTION, JUMP, LINK_OPTION, LIVECHAT (deprecated), LIVECHAT_REQUEST, ANALYTIC_TAGS, FILE_UPLOAD, USER_FEEDBACK_JUMP, USER_INFO, VARIABLE, EMAIL, ACTION, KNOWLEDGE_BASE_ARTICLE, CARD, CAROUSEL, RESET, INPUT_QUERY, LLM, CUSTOM_RESPONSE, CSAT, STICKY_NOTE, SEMANTIC_SEARCH, GENERATION
ChatSessionStatus
ACTIVE, COMPLETED
ChatSessionMessageType
TEXT, POSTBACK, ATTACHMENT, TRIGGER
ChatSessionMessageCategory
COMMON, FEEDBACK, FALLBACK, LIVE_CHAT, BACK
SurveyType
INTERVIEW, LIVECHAT, USER_FEEDBACK
BroadcastStatus
INACTIVE, PENDING, SENDING, WAITING, COMPLETE, ERROR
BroadcastType (TypeScript)
MESSAGE, POLL, QUIZ, ANALYTICS_REPORT
BroadcastMethod (TypeScript)
BATCHES, ONE_SHOT
ActivityType
DECISION_TREE, LIVECHAT_FLOW, AUTOMATED_ANSWERS, INTERVIEW, USER_FEEDBACK, KNOWLEDGE_BASE, LIVECHAT_SYSTEM_MESSAGE
ResponseType
TEXT, MEDIA, QUICKANSWERS, QUICKPOSTBACK, CAROUSEL, SHARE, HANDOVER, CARD, CUSTOM, DATE_PICKER, DROP_DOWN, CHECKBOX, ACTIONABLE, KNOWLEDGE_BASE, INPUT_QUERY, CSAT
Service-Owned Entities
NestJS microservices own their own TypeORM/PostgreSQL entities. These are not part of the core MongoDB domain model. For per-service data models, see:
packages/<service>/docs/data-model.md(generated by exploration scans)docs/architecture/for cross-service communication diagrams
hbf-data-manager (MySQL — hbf_data_manager database)
Stores per-interaction metadata events published by hbf-bot via Kafka. No dependency on hbf-core domain objects — references ChatSession by its uuid string only.
| Entity | Key fields | Notes |
|---|---|---|
InteractionMetadata | id (bigint PK, auto-inc), hbf_event_id (char 36), session_id (char 36), ts (timestamp), type (text), friendly_name (text nullable), payload (json), has_error (boolean nullable), duration_ms (int nullable), created_at (timestamp), updated_at (timestamp) | One row per bot-workflow step. session_id = ChatSession.uuid. Indexes: idx_session_ts (session_id, ts), idx_hbf_event_ts (hbf_event_id, ts) |
Full schema: packages/hbf-data-manager/docs/data-model.md
open-bot-framework (PostgreSQL — obf database) (planned, not yet in use)
Standalone DirectLine 3.0 gateway (planned, not yet in use). Intended as a future self-hosted replacement for Azure DirectLine. Currently hbf-webchat connects to hbf-bot via Azure DirectLine (Microsoft's botframework-directline). No dependency on hbf-core or hbf-core-api.
| Entity | Key fields | Notes |
|---|---|---|
OpenBot | id (uuid), handle (unique), endpoint, schemaVersion | Registered bot with HTTP endpoint |
OpenBotSecret | id (uuid), openBotId (FK), secretHash, plainReducted, expiresAt | bcrypt-hashed API secret for OAuth2 client credentials |
WebChatChannel | id (caller-supplied), openBotId (FK), name, secret1, secret2 | Webchat site with two rotating DirectLine secrets |
Full schema: packages/open-bot-framework/docs/data-model.md
hbf-knowledge-manager (no local database)
NestJS service with no local database or TypeORM entities. All persistent state lives in hbf-core (MongoDB). The service orchestrates file sync from external sources into hbf-core KB objects via the hbf-core-api HTTP client.
hbf-core objects consumed:
| hbf-core object | How used |
|---|---|
Integration (type AZURE_BLOB_STORAGE_KB) | Provides storage credentials (accountName, containerName, sasToken, pathPrefix, allowedContentTypes) and webhookKey for routing inbound Azure Event Grid events |
KnowledgeBase | Target KB that receives synced articles. Looked up by integrationId |
KnowledgeBaseGroup | Created/deleted per source file via fileToArticles / deleteBySourceId. sourceId = azb_<sha256base64url> |
KnowledgeBaseArticle | Created by hbf-core's fileToArticles pipeline (semantic-doc-segmenter) |
Key service-side types (no persistence):
| Type | Location | Purpose |
|---|---|---|
IntegrationConfig | src/common/interfaces/integration-config.interface.ts | Runtime config passed between source and sync engine |
AzureBlobConfig | src/sources/azure-blob/azure-blob.interface.ts | Typed config for Azure Blob Storage |
AzureEventGridEvent | src/sources/azure-blob/azure-blob.interface.ts | Incoming webhook payload from Azure Event Grid |
AzureSubscriptionValidationEvent | src/sources/azure-blob/azure-blob.interface.ts | Handshake payload for Event Grid subscription validation |
NormalisedSourceEvent | src/common/interfaces/webhook-handler.interface.ts | Provider-agnostic event after parsing |
SyncResult | src/common/interfaces/knowledge-source.interface.ts | Result of a full-sync operation |
ProviderType (enum) | src/common/enums/provider-type.enum.ts | AZURE_BLOB |
EventAction (enum) | src/common/enums/event-action.enum.ts | CREATED, DELETED |
sourceId format (Azure Blob): azb_<sha256base64url> where the hash input is azure:<accountName_lower>:<containerName_lower>:<normalised_blobPath>. Built by buildAzureBlobSourceId() in src/sources/azure-blob/azure-blob-source-id.ts.
webhookKey format (Azure Blob): <accountName_lower>/<containerName_lower>. Used by hbf-core to index Integration documents for fast lookup on incoming webhooks.
hbf-lcg (MySQL — lcm database)
NestJS live-chat gateway service. Owns its own TypeORM entities in MySQL. References hbf-core's ChatSession (and related objects) only by string IDs passed at runtime — no ORM foreign keys into MongoDB.
| Entity | Table | Key fields | Notes |
|---|---|---|---|
LiveChatSession | live_chat_session | id (int PK auto-inc), subscriberHandle (indexed), externalServiceSessionId (indexed), externalConversationId (nullable, indexed), organizationId, tenantId, integrationType, status (SubscriberStatus), setCookies (nullable), createdAt, acceptedAt (nullable), lastActivity, plugin (JSON nullable) | One row per live-chat handoff. status enum: NONE, ACTIVE, PENDING. plugin stores provider-specific config. |
CiscoEvent | cisco_event | id (int PK auto-inc), eventId (int), eventType (CiscoEventType, default TypingEvent), status (nullable), livechatSession (ManyToOne → LiveChatSession, CASCADE delete) | Deduplication by unique constraint (livechatSession, eventId). CiscoEventType default: TypingEvent. |
SubscriberStatus enum: NONE, ACTIVE, PENDING
CiscoEventType enum: includes at minimum TypingEvent (default)
Full schema: packages/hbf-lcg/docs/data-model.md