Skip to main content

Architecture: hbf-bot

C4 Component Diagram​

Key Flows​

Inbound Message Processing Flow​

  1. An external platform (e.g. Facebook) sends a webhook POST to /api/fb-events.
  2. HBFEndpointSystem routes the request to the registered FacebookChannel.
  3. BaseChannel.process() calls convert(rawEvent) to produce one or more HBFEvent objects.
  4. For each HBFEvent, an ExpandedBlackboard is created and the subscriber is fetched from Redis.
  5. The deployment handle is resolved (from the event or the subscriber record) and HBFTenantsRepository returns the matching HBFTenant, loading from hbf-core-api if not cached.
  6. HBFTenant.processEvent(blackboard) runs EventLifecycle:
    • LoadStateStep -- rehydrates the blackboard from the Redis subscriber document (contexts, language, persistent data, session).
    • SetLanguageStep -- detects or inherits language.
    • PowerupStep -- applies tenant powerups.
    • UserInputSanitizerStep -- sanitises input.
    • ConversationFlowStep -- executes the ComponentFlow (FlowBuilder-assembled pipeline):
      • if_itc -- routes ITC (inter-tenant communication) messages to a separate path.
      • public_info -- fetches public bot info.
      • convmanager_lite -- NLU intent detection.
      • survey_session_mover -- survey session transitions.
      • node_runner -- executes conversation node actions from hbf-core-api.
      • lcm_end_user -- live chat end-user logic.
      • nlg -- Natural Language Generation (selects and renders response).
      • data_collector -- collects structured data.
    • CheckFowardedStep -- handles forwarded messages.
    • SessionTrackerStep -- tracks session lifecycle.
    • ValidateStateStep -- validates blackboard before save.
  7. ConversationStateManager.saveState() persists the updated blackboard to Redis.
  8. Outbound reply messages are sent directly via the appropriate channel client.

Tenant Loading Flow​

  1. HBFTenantsRepository.getTenant(handle) checks the LRU in-memory cache.
  2. On cache miss, it calls hbf-core-api to fetch the Tenant, BotDeployment, BotContentCompiled, TenantSettings, and TenantSystemSettings.
  3. A new HBFTenant is constructed, FlowBuilder.build() assembles the ComponentFlow, and the tenant is stored in the cache with a configurable TTL.

Outbound Dispatch Flow​

  • For synchronous channels (Web Chat, API): reply is returned directly in the HTTP response via the channel client.
  • For Live Chat Gateway: replies are sent via LiveChatGatewayClient HTTP calls.