Skip to main content

AI Brief: hbf-media-manager

NestJS microservice that handles media file upload, storage, and retrieval for the Helvia Chatbricks platform. Files are stored in AWS S3 and metadata is persisted in MySQL via TypeORM.

What This Repo Does​

Provides a REST API for organizations to upload, list, and delete media files (images, audio, video). Files are stored under a per-organization S3 prefix ({orgId}/{filename}). Metadata (file name, MIME type, size, uploader, public/private flag) is stored in MySQL. All write operations emit an audit log to hbf-core.

Tech Stack​

  • Language: TypeScript
  • Framework: NestJS 11
  • Key dependencies: @aws-sdk/client-s3, @nestjs/typeorm, mysql, @helvia/hbf-core-api, nestjs-pino, elastic-apm-node, multer (via @nestjs/platform-express), class-validator

Entry Points​

  • Main: src/main.ts
  • App module: src/app.module.ts
  • Config validation: src/env.validation.ts

Key Directories​

DirectoryPurpose
src/controllers/HTTP route handlers (MediaController, HealthController)
src/services/media/Business logic for list/create/delete operations
src/clients/aws-s3/S3 multipart upload and delete adapter
src/clients/hbf-core/hbf-core API client (org lookup, audit log creation)
src/clients/http-client/Low-level HTTP client and token-validation guard support
src/entities/TypeORM entity: Media
src/guards/HBFGuard (token validation against hbf-core), AdminOrgRoleGuard, MemberOrgRoleGuard
src/pipes/FileSizeValidationPipe, EnumValidationPipe
src/dtos/Request/response DTOs
src/errors/Custom exceptions (SaveToS3Exception, DeleteFromS3Exception, CreateAuditLogException)

External Dependencies​

  • Storage: AWS S3 (multipart upload, path style {orgId}/{filename}, public URL via AWS_S3_URL)
  • Database: MySQL via TypeORM (entity: media table, synchronize: false)
  • Auth: JWT bearer token validated against hbf-core /users/me endpoint
  • 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