AI Brief: hbf-lcg

What It Is

hbf-lcg (Live Chat Gateway) is a unified gateway for livechat integrations. It bridges communication between hbf-bot and multiple livechat platform providers (Helvia/hbf-lcm, Cisco WebEx, Genesys Cloud, Zendesk). The service handles bidirectional event transformation, session management, and distributed instance coordination via Redis.

Tech Stack

• Runtime: Node.js 22, NestJS
• Database: MySQL/MariaDB (TypeORM, lcm database)
• Cache: Redis (optional, falls back to in-memory)
• Cluster: Redis microservice transport for distributed coordination (leader election, RPC, heartbeat)
• Monitoring: Elastic APM (optional)
• Logging: Pino (ECS format)

Entry Points

• src/main.ts -- NestJS bootstrap, HTTP on SERVICE_PORT (default 1337), Redis microservice
• src/app.module.ts -- Root module, imports all feature modules

Key Directories

src/
  entities/           -- TypeORM entities (LiveChatSession, CiscoEvent)
  dtos/               -- Request/response DTOs
  filters/            -- Global exception filter
  guards/             -- JWT guard
  features/
    adapters/         -- Polling adapters (Cisco, Zendesk, Genesys)
    auth/             -- JWT verification
    clients/          -- Outbound HTTP clients (Core, Bot, Genesys, Cisco, Sunshine/Zendesk)
    distributed/      -- Redis-based cluster coordination (leader election, RPC)
    downstream/       -- Event transformers FROM external services TO hbf-bot
    gateway/          -- Main gateway logic, upstream/downstream controllers
    resolver/         -- Dynamic service resolution by alias/integration type
    upstream/         -- Request forwarders FROM hbf-bot TO external services
migrations/           -- TypeORM migrations (4 total)

API Endpoints

Upstream (hbf-bot -> external services) -- JWT protected

Method	Endpoint	Purpose
POST	/requests	Create livechat request
PATCH	/requests/subscribers/:subHandle	Update request by subscriber
DELETE	/sessions/tenants/:tenantId/subscribers/:subHandle	Terminate session
POST	/messages	Forward user message
HEAD	/organizations/:organizationId/requests?status=	Count requests (X-Total-Count)
HEAD	/organizations/:organizationId/tenants/:tenantId/metrics	Avg wait time (X-Average-Waiting-Time)
GET	/subscribers/:subHandle/livechat-state	Get subscriber status
GET	/tenants/:tenantId/availability	Get availability + business hours

Downstream (external services -> hbf-bot)

Method	Endpoint	Purpose
POST	/events/:alias	Receive callback events from external services
HEAD	/events/:alias	Health check

External Dependencies

Service	Purpose
hbf-core (HBF_CORE_URL)	Tenant config, organization data, plugin settings
hbf-lcm (HBF_LCM_URL)	Helvia internal livechat (upstream forwarding)
hbf-bot (HBF_BOT_EVENT_URL)	Deliver transformed events back to bot engine
Genesys Cloud API	OAuth2, messaging, WebSocket events
Cisco WebEx API	Contact center polling
Zendesk Sunshine API	Conversation polling, messaging

Supported Livechat Providers

Provider	Upstream	Downstream	Adapter
Helvia (hbf-lcm)	UpstreamHelviaService	DownstreamHelviaService (JWT verified)	None (webhook)
Cisco WebEx	UpstreamCiscoService	DownstreamCiscoService	CiscoPollingAdapterService (5s poll)
Genesys Cloud	UpstreamGenesysService	DownstreamGenesysService	GenesysSocketAdapterDistributedService (WebSocket) + GenesysPollingAdapterService (inactive monitor)
Zendesk	UpstreamZendeskService	DownstreamZendeskService	ZendeskPollingAdapterService

Data Model

Two entities:

• LiveChatSession: Tracks active sessions (subscriberHandle, externalServiceSessionId, organizationId, tenantId, integrationType, status, plugin JSON)
• CiscoEvent: Deduplicates Cisco polling events per session (eventId + session unique constraint)

Run Commands

• Dev: npm run start:dev
• Build: npm run build
• Production: npm run start:prod
• Migrations: npm run migration:run