Skip to main content

Architecture: hbf-lcg

Component Diagram​

Key Patterns​

Resolver Pattern​

ResolverService dynamically routes requests to the correct upstream/downstream implementation based on the livechat integration type (alias). Each provider registers itself with the resolver at module initialization. This enables adding new providers without modifying gateway logic.

Upstream/Downstream Abstraction​

  • Upstream (Upstream<Plugin> interface): Services that forward requests FROM hbf-bot TO external platforms. Methods: createRequest, forwardMessage, terminateSession.
  • Downstream (Downstream abstract class): Services that transform events FROM external platforms back to hbf-bot. Each transforms provider-specific event formats into a unified ServiceEvent DTO.

Distributed Cluster Coordination​

Multiple hbf-lcg instances coordinate via Redis microservice transport:

  • Leader election: Heartbeat-based, leader runs periodic tasks (cleanup, Cisco/Genesys polling)
  • Round-robin: Genesys WebSocket connections distributed across instances
  • Correlated RPC: Cross-instance request forwarding when a session is anchored to a specific instance

Session Lifecycle​

  1. hbf-bot calls POST /requests with subscriber info and integration type
  2. Gateway resolves the provider, upstream service creates the request
  3. LiveChatSession created in DB (status: PENDING)
  4. External service sends events via webhook or polling adapter detects changes
  5. Downstream service transforms events, forwards to hbf-bot via POST /livechat-events
  6. Session transitions: PENDING -> ACTIVE -> NONE
  7. GatewayCleaner (leader-only cron) removes expired sessions