Integration Points
Detailed integration configuration for external systems. For a summary, see
docs/AI_BRIEF.md.
Azure Speech
AzureSpeechIntegration (category SPEECH) -- org-level Azure Speech credentials (region + subscriptionKey). Used by webchat deployments when speechMode=custom. Token proxy endpoint: GET /public/azure-speech/token/new?botDeploymentId=<id>. Falls back to global env vars (AZURE_SPEECH_SECRET, AZURE_SPEECH_BASEURL) when mode is helvia or integration is missing.
Azure Blob Storage + Event Grid
hbf-knowledge-manager receives Microsoft.Storage.BlobCreated / Microsoft.Storage.BlobDeleted events from Azure Event Grid. Downloads blobs directly using SAS token from integration config. Webhook key routing: <accountName>:<containerName>. sourceId format: azure-blob:<accountName>:<containerName>:<blobPath> (stable, enables idempotent upsert/delete in hbf-core). No local DB -- all state in hbf-core.
SharePoint KB
SHAREPOINT_KB integration (category KB). Multi-tenant Azure AD auth: Helvia's app credentials in env vars (SHAREPOINT_CLIENT_ID, SHAREPOINT_CLIENT_SECRET), clients grant admin consent, then provide tenantId + siteUrl + driveNames (array of document library names). No per-integration clientId/clientSecret. KM resolves siteUrl/driveName to Graph IDs (siteId/driveId) on the fly via GraphClientService.resolveSharePointIds() (no cached siteId/driveId, avoiding staleness when siteUrl or driveName changes). Backend: hbf-knowledge-manager syncs SharePoint files into hbf-core KB articles via Microsoft Graph API. Full sync + incremental via Graph webhooks + delta queries. Subscription lifecycle: auto-create, 12-hour renewal timer, auto-delete, orphan cleanup for removed drives. Explicit subscription creation endpoint: POST /sync/sharepoint/integrations/:integrationId/subscriptions (AdminOrgRoleGuard). clientState encodes orgId:integrationId for webhook-to-integration lookup.
Subscription toggles on SharePointKbIntegration:
syncManagedMetadata(boolean, default true) -- gates taxonomy/managed-metadata extraction into article tags andArticleMetadata.managedMetadata.syncRbacPermissions(boolean, default true) -- gates per-item permission fetching intoArticleMetadata.permissions(sharing links + grants).
Both toggles are checked as !== false (opt-out), so existing integrations without these fields continue syncing everything. The toggles apply to both full-sync and delta (webhook) paths.
Env: SHAREPOINT_WEBHOOK_BASE_URL (must be publicly accessible), SHAREPOINT_CLIENT_ID, SHAREPOINT_CLIENT_SECRET. Console: registered in hbf-console integrations.js with SharePointIcon.
Kafka
Confluent Kafka (KRaft mode in local dev). hbf-bot publishes to interaction-metadata topic; hbf-data-manager consumes it. Supports local PLAINTEXT and SASL_SSL (Confluent Cloud).
Data Stores (Detailed)
| Store | Used By | Purpose | ORM/Driver |
|---|---|---|---|
| MongoDB | hbf-core | Primary DB: agents, orgs, users, sessions, bot content | Spring Data MongoDB |
| Redis | hbf-bot, hbf-lcg, hbf-lcm, hbf-core, hbf-session-manager, helvia-rag-pipelines | Session cache, pub/sub, SemCache, cluster coordination | ioredis / Spring Data Redis / redis-py |
| Elasticsearch | hbf-broadcast | Email campaign analytics, Kibana dashboards | @elastic/elasticsearch |
| Milvus | helvia-rag-pipelines | Primary vector DB for RAG embeddings | pymilvus |
| Qdrant | helvia-rag-pipelines | Secondary vector DB for RAG embeddings | qdrant-client |
| MySQL | hbf-lcg, hbf-nlp, hbf-lcm, hbf-session-manager, hbf-event-publisher, hbf-notifications, hbf-media-manager, hbf-reports, hbf-client-integrations, helvia-rag-pipelines, semantic-doc-segmenter, hbf-data-manager | Relational data | TypeORM (NestJS) / SQLAlchemy (Python). hbf-client-integrations uses multiple client-specific databases (SIXT, Novibet, AIA). All use mysql:8.0.34. |
| PostgreSQL | open-bot-framework | Bot registry, webchat channel secrets, activity watermarks | TypeORM (db: obf, synchronize:true) |