Communication: hbf-data-manager

1-hop view of how this service communicates with its siblings. For the full system view, see docs/architecture/service-communication.md.

Calls Out To

Service	Protocol	Purpose	Key calls / queues
hbf-core	HTTP GET	Token validation for read API (HBFGuard)	GET /users/me with caller's Bearer token

Called By

Service	Protocol	How
hbf-bot	Kafka (producer)	Publishes InteractionMetadata events to topic hbf.interaction.metadata (env: KAFKA_TOPICS)
hbf-console	HTTP GET	Observatory view — reads interaction metadata and session variables
hbf-core	HTTP DELETE / POST	Session data cleanup — DataManagerClient calls delete and bulk-delete endpoints with a DM JWT

Contracts

Inbound — Kafka (from hbf-bot)

Topic: hbf.interaction.metadata (configurable via KAFKA_TOPICS) Consumer group: hbf-data-manager-consumer (configurable via KAFKA_GROUP_ID)

{
  "hbfEventId": "uuid",
  "sessionId": "uuid",
  "timestamp": "ISO-8601",
  "type": "VARIABLE | NODE | ...",
  "friendlyName": "optional string",
  "payload": {},
  "hasError": false,
  "duration": 123
}

Inbound — HTTP Read (from hbf-console, guarded by HBFGuard)

HBFGuard proxies the caller's Bearer token to hbf-core GET /users/me for validation. Callers must hold a valid hbf-core session token with org-level role for the requested orgId.

Method	Path	Purpose
GET	/orgs/:orgId/interactions	List all interaction metadata (desc by ts)
GET	/orgs/:orgId/events/:hbfEventId/interactions	Records for a specific HBF event
GET	/orgs/:orgId/events/:hbfEventId/session-variables	Latest VARIABLE-type records as of event

Inbound — HTTP Delete (from hbf-core, guarded by DMJwtGuard)

DMJwtGuard verifies a locally-issued HS256 JWT signed with DM_AUTH_JWT_SECRET. hbf-core supplies this token via helvia.data-manager.token config property.

Method	Path	Body
DELETE	/chat-sessions/:sessionId/interactions	—
POST	/chat-sessions/interactions/bulk-delete	{ "sessionIds": ["uuid", ...] }

Both endpoints return 202 Accepted immediately and delete asynchronously.

Outbound — hbf-core GET /users/me

Used only for read-request token validation (HBFGuard). Forwards the caller's Authorization header verbatim.

GET /users/me
Authorization: Bearer <caller-token>

Auth Summary

Guard	Applied to	Mechanism
HBFGuard	Read endpoints (/orgs/:orgId/...)	Proxy token to hbf-core /users/me; check org role
DMJwtGuard	Delete endpoints (/chat-sessions/...)	Local HS256 JWT (DM_AUTH_JWT_SECRET)

Confidence

• hbf-bot → Kafka topic: high (topic name from config/default.yml in hbf-bot; KAFKA_TOPICS env overrides the default string in hbf-data-manager)
• hbf-console → read API: high (direct RTK Query calls to all three read endpoints confirmed in source)
• hbf-core → delete API: high (typed DataManagerClient.kt with both delete methods confirmed in source)
• hbf-data-manager → hbf-core (token validation): high (HBFGuard calls CoreClientService.getUserMe on every read request)

Flows Involving This Service

• Analytics Ingestion — hbf-bot publishes interaction events; hbf-data-manager stores them; hbf-console Observatory reads them