Skip to main content

AI Brief: hbf-core

Central REST API microservice for the Helvia Bot Framework (HBF). Manages the platform's primary data model: organizations, tenants (bots), users, bot content, deployments, NLU/NLP pipelines, chat sessions, and all related operational resources. All other services in the HBF ecosystem call hbf-core as their source of truth.

What This Repo Does​

hbf-core is a Spring Boot REST API that owns the platform's persistent state in MongoDB. It enforces multi-tenant authorization (organizations contain tenants, tenants contain subscribers/sessions/content), manages bot content lifecycle (authoring, compilation, recompilation), handles user authentication tokens, and orchestrates NLU training across multiple NLP providers. External services authenticate to hbf-core using JWT bearer tokens issued by hbf-auth.

Tech Stack​

  • Language: Java 21 + Kotlin 1.9 (mixed, controllers are Kotlin, some config is Java)
  • Framework: Spring Boot 3.3.2 (Web, Security, Data MongoDB, Actuator, Validation, AOP, Retry)
  • Database: MongoDB with replica set (Spring Data MongoDB + custom repositories)
  • Cache: Redis (Spring Cache, used for NLU detection results; TTL-controlled)
  • Schema migrations: Liquibase (custom MongoDB runner)
  • API docs: SpringDoc OpenAPI / Swagger UI
  • Auth: JWT (jjwt 0.9.1, HS256), stateless sessions
  • Audit: Javers 7.0.1 (diff tracking for domain changes)
  • Build: Maven 3, profiles: local/development/stage/production

Entry Points​

  • Main: src/main/java/gr/helvia/hbf/core/Application.java
  • Config: src/main/resources/application.properties
  • Security: src/main/java/gr/helvia/hbf/core/config/WebSecurityConfiguration.java
  • Route constants: src/main/java/gr/helvia/hbf/core/config/HBFNames.kt

Key Directories​

DirectoryPurpose
src/main/java/gr/helvia/hbf/core/resources/REST controllers, grouped by domain
src/main/java/gr/helvia/hbf/core/services/Business logic layer (interface + impl pattern)
src/main/java/gr/helvia/hbf/core/repositories/Spring Data MongoDB repositories + custom aggregations
src/main/java/gr/helvia/hbf/core/domain/Kotlin data model classes persisted to MongoDB
src/main/java/gr/helvia/hbf/core/dto/Request/response DTOs
src/main/java/gr/helvia/hbf/core/mappers/Domain-to-DTO mappers
src/main/java/gr/helvia/hbf/core/config/Spring configuration (security, MongoDB, web, i18n)
src/main/java/gr/helvia/hbf/core/listeners/MongoDB lifecycle listeners for cascade operations
src/main/java/gr/helvia/hbf/core/security/JWT filter and auth entry point
src/main/java/gr/helvia/hbf/core/database/Liquibase migration changesets
src/main/resources/liquibase/Liquibase changelog XML

API Surface (if applicable)​

Key route groups (all under optional app.rest.api.base prefix, default empty):

  • GET/POST/PATCH/DELETE /organizations — organization CRUD, tags, audit logs, monitors
  • GET/POST/PATCH/DELETE /tenants — tenant (bot) CRUD, clone, train NLU, stats, usage
  • GET/POST/PATCH/DELETE /organizations/{orgId}/tenants — org-scoped tenant management
  • GET/POST/PATCH/DELETE /organizations/{orgId}/tenants/{tenantId}/bot-content — bot content (flows/FAQs)
  • GET/POST /organizations/{orgId}/tenants/{tenantId}/bot-content-compiled — compiled content
  • GET/POST/PATCH/DELETE /organizations/{orgId}/tenants/{tenantId}/bot-deployments — deployment configs
  • GET/POST/PATCH/DELETE /organizations/{orgId}/tenants/{tenantId}/responses — response templates
  • GET/POST/DELETE /users, /organizations/{orgId}/users — user management
  • GET/POST /login, POST /logout — JWT authentication (via hbf-auth delegation)
  • GET/POST/DELETE /api-tokens, /organizations/{orgId}/api-tokens — long-lived API tokens
  • GET /analytics, /organizations/{orgId}/analytics — analytics queries
  • GET /audit-logs — audit log access
  • GET/POST/PATCH/DELETE /broadcasts, /organizations/{orgId}/broadcasts — broadcast messages
  • GET/POST/DELETE /groups, /organizations/{orgId}/groups — subscriber groups
  • GET /chat-sessions, /organizations/{orgId}/tenants/{tenantId}/chat-sessions — session data
  • GET/POST/DELETE /organizations/{orgId}/knowledge-bases — knowledge base management
  • GET/POST/PATCH/DELETE /nlp-pipelines — NLP pipeline configuration
  • GET /organizations/{orgId}/tenants/{tenantId}/missed-questions — missed question tracking
  • GET /public/... — unauthenticated endpoints (DirectLine token, bot deployment metadata, registration, email verification)

External Dependencies​

  • Database: MongoDB (replica set required for transactions)
  • Cache: Redis
  • NLU providers: LUIS (Azure Cognitive Services), Dialogflow (Google)
  • Email: SMTP (configurable host/credentials)
  • Azure AI: OpenAI/Azure language detection
  • Google: Translate API, OAuth
  • Microsoft: OAuth, MS Teams DirectLine
  • Uptime monitoring: UptimeRobot API
  • Helvia services: GPT pipeline, SDS (Semantic Doc Segmenter), Notification Service, Livechat (hbf-lcm), AutoBot

Running Locally​

Dev mode (recommended): Add hbf-core to DEV_SERVICES in .env.local, then start via aq-local-dev.sh. This bind-mounts src/ into the container with a file watcher that auto-recompiles on .kt/.java changes (~15s). Debug port 5005 is exposed. Requires generate-env.sh to create the dev Docker files first.

Prod mode (compiled JAR): Default when hbf-core is not in DEV_SERVICES. Builds the JAR inside Docker, no hot reload. Faster startup but requires a full rebuild for code changes.

Manual (without aq-local-dev.sh):

# Build (skip tests) -- host only, no Java in devcontainer
./mvnw clean install -U -DskipTests=true

# Run
java -jar target/hbf-core.jar -Xms512m -Xmx1024m

Server starts on port 8080. Swagger UI: http://localhost:8080/swagger-ui/index.html

Tests​

# Run all tests (requires MongoDB URI)
mvn test -Dspring_data_mongodb_uri=mongodb://localhost:27017/hbf?replicaSet=rs0

# Run specific test class
mvn test -Dspring_data_mongodb_uri=... -Dtest=MyTestClass