Skip to main content

Architecture: hbf-core

C4 Component Diagram​

Domain Model Summary​

From the README class diagram:

  • Organization (1) owns Tenant (1..), User (1..), AuditLog (0..), ApiToken (0..), NLUAgent (0..*).
  • Tenant owns Subscriber (0..), ChatSession (0..), Broadcast (0..), Group (0..), Survey (0..*).
  • Tenant has exactly one BotContent and one BotContentCompiled.
  • Tenant links to BotDeployment (1..*) for each channel (Facebook, WhatsApp, Webchat, etc.).
  • BotContent contains Activity (1..); BotContentCompiled contains ActivityCompiled (1..), each with ConversationNode (1..*).
  • Broadcast targets Group (1..); Group contains Subscriber (1..).

Key Flows​

JWT Authentication​

  1. Client sends POST /login with credentials; request is handled by AuthenticationResource which delegates to AuthenticationService.
  2. AuthenticationService validates credentials against UserRepository, issues a JWT signed with the configured HS256 secret.
  3. On every subsequent request, TokenAuthenticationFilter extracts the Bearer token, validates it via TokenManager, and populates SecurityContext with the user principal.
  4. Method-level @PreAuthorize annotations check roles (MODERATOR, ADMIN, etc.) via SecurityService.

Bot Content Compilation​

  1. User edits bot content (flows/FAQs/activities) via BotContentResource; changes persist raw to MongoDB via BotContentRepository.
  2. A save event triggers BotContentListener to mark the tenant as needing recompilation.
  3. TenantRecompilationService (scheduled, throttled at 10 tenants/min) picks up tenants flagged for recompilation.
  4. Compilation produces BotContentCompiled with expanded ActivityCompiled nodes; stored to BotContentCompiledRepository.
  5. Other services (hbf-bot) read BotContentCompiled to serve conversations.

NLU Training​

  1. TenantResource.trainNlu() or BotContentRecompilationResource triggers NLU training.
  2. NLPPipelineService creates/updates NLU agents on the configured provider (LUIS or Dialogflow).
  3. Service polls agent status (up to nlu.train.max_check_ready_attempts attempts, nlu.train.repeat_rate_millis delay via @Retryable).
  4. On completion, tenant nluSync flag is updated; Redis cache for NLU detections is invalidated.

Cascade Delete (Organization)​

  1. DELETE /organizations/{id} calls OrganizationService.delete().
  2. OrganizationService deletes all org tenants first (each triggers TenantCascadeListener).
  3. TenantCascadeListener deletes subscribers, chat sessions, broadcasts, groups, surveys, deployments, content for that tenant.
  4. OrganizationCascadeListener then removes org-level audit logs, API tokens, users from the org.