C4 Container Diagram: Helvia Platform Platform

Container Diagram

Container Descriptions

User-Facing

Container	Tech	Role
hbf-webchat	React	Embeddable chat widget served to end users' browsers. Connects to hbf-bot via Azure DirectLine (Microsoft botframework-directline, bundled in botframework-webchat).
hbf-console	React SPA (JavaScript/JSX)	Admin console for building agents, managing knowledge, handling live chat, viewing analytics
open-bot-framework	Node.js (NestJS 11)	Self-hosted DirectLine 3.0 gateway (planned, not yet in use). Intended to replace Azure's hosted DirectLine. Will receive activities from hbf-webchat, forward to hbf-bot over HTTP, and stream replies back via WebSocket. HTTP :1986, WebSocket :1992.

Core Services (Inner Layer)

Container	Tech	Role
hbf-core	Java/Kotlin (Spring Boot 3.3)	Central API: manages organizations, users, agents, deployments, NLU pipelines, permissions. All other services depend on it.
hbf-core-api	TypeScript	Shared API client library and TypeScript types for communicating with hbf-core
hbf-bot	Node.js	Bot execution engine: processes inbound messages through agent workflows, calls NLU, executes actions

AI / NLP Layer

Container	Tech	Role
hbf-nlp	Node.js	NLP service: intent classification, entity extraction, LLM orchestration for generation
helvia-rag-pipelines	Python/FastAPI	RAG pipeline service: document ingestion, chunking, embedding, vector search via Milvus (primary) and Qdrant (secondary); Redis for SemCache
semantic-doc-segmenter	Python/FastAPI	Document segmentation service: converts uploaded files (PDF, DOCX, PPTX, HTML, TXT, MD) to semantically segmented, LLM-tagged, language-detected chunks. Job-based async processing with callback notifications

Live Chat / Sessions

Container	Tech	Role
hbf-lcg	Node.js (NestJS)	Live Chat Gateway: unified gateway bridging hbf-bot to external livechat providers (Helvia/hbf-lcm, Cisco WebEx, Genesys Cloud, Zendesk). Bidirectional event transformation, distributed cluster coordination via Redis. HTTP :1337.
hbf-lcm	Node.js	Live Chat Manager: routes conversations to human agents, manages business hours, callbacks
hbf-session-manager	Node.js	Manages conversation sessions: state tracking, context persistence

Messaging / Communication

Container	Tech	Role
hbf-broadcast	Node.js/Restify daemon (scan loop)	Scheduled mass messaging campaigns to subscribers
hbf-event-publisher	Node.js	Power Automate connectors + Firebase FCM push notifications
hbf-notifications	Node.js/SSE	Sends email, push, and in-app notifications; uses MySQL; real-time delivery via SSE
hbf-client-integrations	Node.js	Client-specific integration hub: 13 enterprise distributor modules (Dynamics 365, Zendesk, Genesys, Infobip, SITA AMS SOAP, Wheelsys SOAP)

Analytics / Scheduling

Container	Tech	Role
hbf-stats	Node.js daemon (infinite loop)	Aggregates session data and writes stats back to hbf-core via hbf-core-api
hbf-reports	Node.js	Generates scheduled and on-demand analytics reports
hbf-scheduler	Node.js (NestJS 10)	Scheduled flow execution: polls MySQL for due schedules via Bull/Redis queues (30s interval), triggers bot flows via hbf-bot, records execution history, sends failure alerts via hbf-notifications. Port 4223.

Data Management

Container	Tech	Role
hbf-media-manager	Node.js	File upload, storage, and retrieval for media assets
hbf-data-retention	Node.js daemon (while(true) polling loop)	GDPR-compliant data cleanup and retention policy enforcement; supports S3 and MinIO storage backends
hbf-data-manager	Node.js (NestJS 11)	Interaction metadata store: consumes interaction-metadata Kafka topic published by hbf-bot, persists records to MySQL, exposes read API (HBFGuard) and internal delete API (DMJwtGuard)
hbf-knowledge-manager	Node.js (NestJS 11)	Syncs Azure Blob Storage into HBF Knowledge Bases. Receives Azure Event Grid webhook events (BlobCreated/BlobDeleted), downloads blobs directly via SAS token, and calls hbf-core to convert files to KB articles or delete KB groups. Also exposes a guarded full-sync endpoint. No local database.

Testing

Container	Tech	Role
automated-bot-tester-service	Python (FastAPI)	Automated bot stress-testing service (AutoBoTS): generates LLM-powered synthetic users that converse with deployed Helvia bots via the Bot Events API, then evaluates each conversation against user-defined criteria. Supports adversarial/red-team testing via Cialdini persuasion techniques. All state in Redis with TTL auto-expiry. Port 4224.

Developer Tooling

Container	Tech	Role
hbf-developer-docs	Docusaurus v3, React, D3	Engineering docs site: aggregates docs from all service repos into a searchable site with a service topology graph. Port 3333.
hbf-release-framework	Bash, GitHub Actions	Central release orchestration repo: workflow_dispatch workflows (merge, backport, release notes), CLI scripts (detect-changes, setup-semantic-release, onboard-service), per-repo config templates, and services.json registry listing all 25 in-scope repos.

Data Stores

Store	Purpose
MongoDB	Primary database for agents, organizations, users, sessions, bot content
Redis	Message queue, session cache, pub/sub, SemCache for RAG pipelines, hbf-lcg cluster coordination, automated-bot-tester-service test/profile state, hbf-scheduler Bull job queues
Elasticsearch	Search index; used by hbf-broadcast for email campaign analytics
Milvus	Primary vector database for RAG document embeddings (helvia-rag-pipelines)
Qdrant	Secondary vector database for RAG document embeddings (helvia-rag-pipelines)
PostgreSQL	Relational data; used by open-bot-framework (bot registry, webchat channels) (planned, not yet in use)
MySQL	Relational data; used by hbf-lcg, hbf-lcm, hbf-session-manager, hbf-notifications, hbf-media-manager, hbf-reports, semantic-doc-segmenter, hbf-data-manager, hbf-scheduler

Message Flow (Simplified)

Current path (Azure DirectLine):
Subscriber
  -> hbf-webchat (browser widget, botframework-webchat)
    -> Azure DirectLine service
      -> hbf-bot (workflow execution)
        -> hbf-core (agent config, NLU pipelines)
        -> hbf-nlp (intent/entity/LLM)
        -> helvia-rag-pipelines (knowledge retrieval)
        -> hbf-lcg (if live chat handover) -> hbf-lcm
      <- bot reply via Azure DirectLine
    <- WebSocket stream to widget
  <- displayed to user

Planned path (OBF, not yet in use):
Subscriber
  -> hbf-webchat
    -> open-bot-framework (self-hosted DirectLine gateway)
      -> hbf-bot (HTTP activity POST)
      <- bot reply POSTed back to OBF
    <- WebSocket stream to widget
  <- displayed to user