AI Brief: hbf-bot

Bot workflow execution engine for the Helvia Chatbricks platform. It receives inbound messages from multiple messaging channels, runs them through configurable component pipelines (NLP, conversation management, NLG, live chat), and dispatches outbound replies via direct channel clients.

What This Repo Does

hbf-bot is an Express-based Node.js service that acts as the core bot runtime. It accepts webhook events from Facebook, Instagram, WhatsApp, Viber, Slack, Microsoft Teams, Microsoft Web Chat, Live Chat Gateway, Zendesk, and a generic API channel. Each inbound event is processed through a per-tenant component flow (FlowBuilder assembles a linked list of ComponentBase instances), state is persisted to Redis (subscriber blackboard), and outbound messages are dispatched via channel-specific clients.

Tech Stack

• Language: TypeScript / Node.js
• Framework: Express 4
• DI container: tsyringe
• Key dependencies: @helvia/hbf-core-api, @helvia/hbf-dispatcher-client (^1.2.2), @helvia/liqe, bull (^4.12.9), ioredis, axios, kafkajs, @aws-sdk/client-s3, @google-cloud/translate, @google-cloud/vision, elastic-apm-node, pino, handlebars, nodemailer

Entry Points

• Main: index.ts (reads config, parses CLI args, constructs and starts HbfApp)
• App class: app/app.ts (HbfApp) -- initialises Express, tsyringe DI, and registers all channel backends

Key Directories

Directory	Purpose
app/app.ts	Express app bootstrap, DI wiring, backend registration
app/system/	Core runtime: FlowBuilder, Blackboard, ConversationStateManager, HBFTenant, lifecycle steps
app/system/blackboard/	ExpandedBlackboard (persistent / session / ephemeral data store per user)
app/system/lifecycle/	EventLifecycle pipeline steps (LoadState, SetLanguage, Powerup, ConversationFlow, etc.)
app/clients/	Channel adapters: BaseChannel, FacebookChannel, InstagramChannel, WhatsAppChannel, ViberChannel, SlackChannel, MicrosoftChannel, LiveChatGatewayChannel, UnityChannel, ApiChannel, PostChannel, MonitoringChannel, ZendeskChannel
app/clients/rag/	RagPipelinesClient -- calls helvia-rag-pipelines service
app/components/	Flow components (ConversationManager, NLG, NodeRunner, DataCollector, LiveChat, etc.)
app/system/groups/	Group resolution via hbf-core-api
app/system/handover/	Handover (live chat escalation) logic
app/system/archiver/	Survey archival client
app/system/analytics/	Elasticsearch interaction metadata logging
app/kafka/	KafkaEventPublisher -- optional Kafka event emission
app/core/	LambdaApi, TenantInitializationApi
app/auth/	OIDC authentication: AuthenticateUserAction (orchestrator), OidcService (token exchange, JWKS verification), strategies/ (OidcAuthStrategy for interactive flow, PreAuthTokenStrategy for pre-auth JWT validation)
app/system/variables/resolvers/AuthVariablesResolver.ts	Resolves Auth.* template variables from the dedicated auth store on Blackboard
app/web/rest/	REST routes: /api/tenants (tenant management), /api/status
app/interfaces/	TypeScript types and channel-specific message converters
app/stringaga/	Template string engine (Handlebars-based variable substitution)
locale/	Gettext .po files for bot i18n
test/	Jest unit tests

API Surface

Channel webhook endpoints (all POST, registered by HBFEndpointSystem):

• POST /api/fb-events -- Facebook Messenger inbound events
• POST /api/instagram-events -- Instagram inbound events
• POST /api/whatsapp-events -- WhatsApp inbound events
• POST /api/viber-events/ -- Viber inbound events
• POST /api/slack-events -- Slack inbound events
• POST /api/msteams-events -- Microsoft Teams inbound events
• POST /api/webchat-events -- Microsoft Web Chat inbound events
• POST /api/livechat-events/ -- Live Chat Gateway inbound events
• POST /api/unity-events -- Unity channel inbound events
• POST /api/events -- Generic API channel inbound events
• POST /api/monitoring-events -- Monitoring / debug events
• POST /api/post-events -- POST channel events
• POST /api/zendesk-events -- Zendesk inbound events

Management endpoints:

• GET /api/tenants -- list loaded tenants
• POST /api/tenants -- load/reload a tenant
• GET /api/status -- service health
• GET / -- homepage (status page, CORS-restricted)
• GET /auth/oidc/callback -- OIDC authorization code redirect callback (popup window response)

External Dependencies

• State Store: Redis (subscriber blackboard, tenant cache, via ioredis)
• Core API: @helvia/hbf-core-api (bot content, deployments, tenants, subscribers, groups)
• NLP: hbf-nlp service (configurable base URL)
• Live Chat Gateway: separate LCG service
• Event Publisher: hbf-event-publisher service (HTTP)
• Kafka: optional event stream (KafkaEventPublisher)
• File Upload: AWS S3 (@aws-sdk/client-s3)
• Vision / OCR: Google Cloud Vision (@google-cloud/vision)
• Translation: Google Cloud Translate (@google-cloud/translate)
• Email: SMTP via nodemailer
• APM: Elastic APM

Running Locally

npm run build
node dist/index.js --coreUrl <url> --coreToken <token> --nlpUrl <url>

Hot reload (watch mode):

npm run watch
# in another terminal:
npm start

Tests

npm test        # lint + tsc + jest
npm run onlytest  # jest only