Skip to main content

Architecture: hbf-session-manager

C4 Component Diagram​

Key Flows​

Session Expiry and Completion (main scheduled flow)​

  1. SchedulerService fires checkConversations cron at every CHAT_SESSION_CHECK_INTERVAL_IN_MINS minutes.
  2. SessionsService.checkConversations() loads all enabled webhook integrations from MySQL.
  3. findInactiveChatSessions() is called: a. All tenants are loaded from hbf-core with includeSettings, includeSystemSettings, and includePlugins. b. Tenant usage is checked. If usage exceeds maxNumOfSessions or maxNumOfUserMessages, the tenant is set disabled: true in hbf-core. c. For each tenant, the per-tenant expireInactiveSessionAfter is read (fallback: BOT_EXPIRE_CONVERSATION_AFTER_DEFAULT_VALUE seconds). d. hbf-core is paginated to find ACTIVE sessions whose lastInteraction is older than the threshold. e. Only sessions where all associated live chats have status LIVECHAT_TERMINATED are selected. f. Selected session IDs are batch-set to COMPLETED via batchSetStatusCompleted. g. For each selected session: handleTriggerFlows() fires chat-session-completed and survey-completed events to hbf-event-publisher.
  4. For each enabled integration, each completed session is matched against integration.tenants[]. If the session's tenant matches, sendChatSession() POSTs the full ChatSessionDTO to integration.url with custom headers.
  5. On webhook failure: error is saved to SessionIntegrationError. If errorEmailRecipients is set, an HTML email is sent via nodemailer using the Handlebars template.
  6. After all session processing: handleChatSessionSummarization() is called. For tenants with LLM_SUMMARIZATION plugin and automaticallyRunOnSessionCompletion: true, hbf-nlp.summarizeChatSession() is called fire-and-forget (non-blocking) for sessions that contain user interactions.

NLP Pipeline Auto-Training​

  1. SchedulerService fires checkNLPPipelines cron. After each run, the next trigger is scheduled NLP_PIPELINE_CHECK_INTERVAL_IN_MINS minutes from completion (not from start — prevents overlap).
  2. NLPPipelinesService.checkForOutdatedPipelines() queries hbf-core for pipelines with tenantHasAutoTrain: true and a non-current status.
  3. For each outdated pipeline, hbfCoreService.trainOne(id, { waitUntilCompletion: true }) is called. Training completion is polled using RxJS interval + takeWhile until status transitions from TRAINING, with a configurable timeout.

Webhook Integration Management​

An org admin creates an integration specifying a URL, list of tenant IDs to scope, custom HTTP headers (stored separately in hbf_sessions_headers), whether it is enabled, and optional error email recipients. The session expiry flow only dispatches to integrations where enabled: true and where the session's tenant.id is in the integration's tenants[] array. Each organization can have at most one integration (enforced by a UNIQUE constraint on organization_id in hbf_sessions_integrations).