Data Model: hbf-data-manager

Domain objects used by this service. Full schemas: docs/domain-model.md

Objects This Service Uses

Object	How	Key fields accessed
ChatSession	referenced by UUID only (no direct DB join)	uuid stored as session_id in interaction_metadata

hbf-data-manager does not depend on hbf-core or hbf-core-api for data access. It receives ChatSession UUIDs embedded in Kafka event payloads published by hbf-bot, and stores them as opaque strings.

Local Entities

InteractionMetadata

Table: interaction_metadata Database: MySQL 8 — hbf_data_manager ORM: TypeORM 0.3 Source: src/interactions/interaction-metadata.entity.ts

Column	TypeORM type	MySQL DDL	Nullable	Notes
id	bigint PK	BIGINT AUTO_INCREMENT	no	Auto-generated surrogate key
hbf_event_id	char(36)	CHAR(36)	no	UUID of the HBF event (one event = one workflow execution)
session_id	char(36)	CHAR(36)	no	ChatSession.uuid from hbf-bot
ts	timestamp	TIMESTAMP(6)	no	When the interaction occurred
type	text	TEXT	no	Interaction type (e.g. VARIABLE, NODE, LLM_REQUEST)
friendly_name	text	TEXT	yes	Human-readable label for the node (added in migration 1769000000000)
payload	json	JSON	no	Event-specific data. For VARIABLE type: { key, newValue }
has_error	boolean	BOOLEAN	yes	True if the interaction step errored (added in migration 1727200000000)
duration_ms	int	INT	yes	Execution duration in ms for supported types (added in migration 1727200000000)
created_at	timestamp (CreateDateColumn)	TIMESTAMP(6) DEFAULT CURRENT_TIMESTAMP(6)	no	Row insertion time (added in migration 1726500000000)
updated_at	timestamp (UpdateDateColumn)	TIMESTAMP(6) DEFAULT CURRENT_TIMESTAMP(6) ON UPDATE CURRENT_TIMESTAMP(6)	no	Row last-modified time (added in migration 1726500000000)

Indexes:

• idx_session_ts on (session_id, ts) — primary access pattern for listing interactions per session
• idx_hbf_event_ts on (hbf_event_id, ts) — access pattern for fetching all steps within a single event

Migration history:

Migration	Timestamp	Change
CreateInteractionMetadata	1726400000000	Initial table: id, hbf_event_id, session_id, ts, type, payload; idx_session_ts
AddTimestampsToInteractionMetadata	1726500000000	Added created_at, updated_at
AddErrorDurationToInteractionMetadata	1727200000000	Added has_error, duration_ms
AddFriendlyNameToInteractionMetadata	1769000000000	Added friendly_name

Notes

• session_id maps to ChatSession.uuid (not ChatSession._id). hbf-bot publishes the uuid string; no FK constraint exists.
• payload schema varies by type. For VARIABLE interactions the payload contains { key: string, newValue: string | null }, used by the session-variables API endpoint to reconstruct variable state at a point in time.
• Delete operations are async (HTTP 202). The service accepts the request and runs the DELETE in the background.
• hbf-data-retention is the only internal caller of the delete API, authenticated via a locally-issued DM JWT (HS256, DM_AUTH_JWT_SECRET).