Skip to main content

AI Brief: hbf-notifications

A NestJS service that manages in-app notifications for the Helvia console. It persists notifications to MySQL, tracks per-user read status, and delivers real-time notification events to connected clients via Server-Sent Events (SSE).

What This Repo Does​

hbf-notifications receives notification creation requests from internal microservices (JWT-authenticated), stores them scoped to an organization and optionally to a specific user, and pushes them in real time to any connected SSE subscriber. Console users can list, filter, and mark notifications as read individually or in bulk. The service exposes Swagger docs at /api.

Tech Stack​

  • Language: TypeScript
  • Framework: NestJS v10 (Express platform)
  • Key dependencies: @nestjs/typeorm, typeorm, mysql2, @nestjs/swagger, @nestjs/jwt, got, nestjs-pino, moment (unused -- not imported in src/), moment-timezone (unused -- not imported in src/)
  • Note: @nestjs/websockets, socket.io, and @nestjs/platform-socket.io are listed in package.json but not imported or used anywhere in src/. The service uses SSE exclusively via the @Sse decorator.

Entry Points​

  • Main: src/main.ts
  • Root module: src/app.module.ts
  • Swagger UI: GET /api
  • Config: .env / .env.local (loaded via DatabaseModule using @nestjs/config)

Key Directories​

DirectoryPurpose
src/notification/Core module: controller, service, SSE handler, entities, DTOs, filters.
src/notification/entities/Notification and NotificationReadDetails TypeORM entities.
src/notification/dto/CreateNotificationDto, NotificationWithReadStatus.
src/database/DatabaseModule — async TypeORM MySQL setup.
src/auth/JWT verification service and guards.
src/guards/HBFGuard, JWTGuard, MemberOrgRoleGuard.
src/clients/HTTP client to hbf-core for user/org resolution.
src/utils/enums/NotificationType and ValidRoles enums.
migrations/TypeORM database migrations.

API Surface​

All notification routes are scoped under /organizations/:orgId/notifications/.

  • POST /organizations/:orgId/notifications/ — create notification (JWT-authenticated, microservices/admins)
  • GET /organizations/:orgId/notifications/?userId=&page=&pageSize=&showUnreadOnly= — paginated list with unread count (HBF token)
  • GET /organizations/:orgId/notifications/unread-count?userId= — unread count (HBF token)
  • PATCH /organizations/:orgId/notifications/read/:id — mark single notification as read (HBF token)
  • PATCH /organizations/:orgId/notifications/readAll — mark all as read for a user (HBF token)
  • DELETE /organizations/:orgId/notifications/:id — delete notification
  • GET /organizations/:orgId/notifications/events?userId= — SSE stream for real-time delivery (HBF token)

Notification Types (enum NotificationType)​

INFORM, DOWNLOAD, WARNING, SUCCESS, ERROR

External Dependencies​

  • MySQL: TypeORM + MySQL2 — stores notification and notification_read_details tables
  • hbf-core: HBF token validation via HBFGuard and user/org context resolution
  • SSE: NestJS @Sse decorator with RxJS Subject per orgId#userId key (in-memory, single-instance only)
  • APM: elastic-apm-node (optional)

Running Locally​

npm install
cp .env.sample .env
# fill in TYPEORM_HOST, TYPEORM_USERNAME, TYPEORM_PASSWORD, JWT_SECRET, CORE_URL
npm run start:dev

Tests​

npm test          # unit tests (jest, coverage collected by default)
npm run test:e2e  # e2e tests
npm run test:cov  # HTML + LCOV coverage report in coverage/