AI Brief: hbf-data-retention

NestJS background worker that enforces GDPR data retention policies for the Helvia Chatbricks platform. It runs on a configurable interval and deletes expired conversation data, S3 attachments, and audit logs for organizations and tenants whose retention period has elapsed.

What This Repo Does

On each execution cycle, the service queries hbf-core for all organizations and tenants that have a dataRetentionPeriod set and for organizations with an auditLogsRetentionPeriod. For each matched entity it calls the relevant hbf-core deletion API. For tenants it also purges S3 attachment objects under the {orgId}/{tenantId}/attachments/ prefix that are older than the retention window. Failed deletions are retried up to a configurable threshold before being logged and skipped.

Tech Stack

• Language: TypeScript
• Framework: NestJS 8
• Key dependencies: @helvia/hbf-core-api, @aws-sdk/client-s3, nestjs-pino, @elastic/ecs-pino-format, joi, elastic-apm-node

Entry Points

• Main: src/main.ts
• App module: src/app.module.ts
• Orchestration loop: src/app.service.ts (AppService.run())

Key Directories

Directory	Purpose
src/app.service.ts	Main execution loop: fetch policies, call deletions, retry on failure, sleep
src/hbf-core/	hbf-core API client wrapper (org/tenant policy queries, data deletion, audit log deletion)
src/attachments/	S3 attachment cleaner (paginates ListObjectsV2, deletes objects older than retention window)

External Dependencies

• Storage: AWS S3 (ListObjectsV2 + DeleteObjects for tenant attachment cleanup; supports MinIO via MINIO_ENDPOINT and S3_FORCE_PATH_STYLE)
• Platform API: hbf-core via @helvia/hbf-core-api (org/tenant data deletion, audit log deletion)
• Auth: static service-to-service token (HBF_CORE_ACCESS_TOKEN) passed to HBFCoreApi constructor
• Observability: Elastic APM, Pino ECS-format structured logging

Running Locally

npm run start:dev

Tests

npm test          # unit tests
npm run test:e2e  # end-to-end tests
npm run test:cov  # with coverage