BE-024 — Implement Notification Delivery Service

[Marvelg256]

Summary

Implements the centralized Notification Delivery Service (BE-024) as the communication backbone for the TruthBounty ecosystem. All outbound user notifications now pass through this service instead of individual modules sending independently.

Closes #293

What was done

Core Architecture

• 4 TypeORM entities: Notification, NotificationDelivery, UserNotificationPreference, NotificationTemplate — covering delivery tracking, retries, user config, and versioned templates
• BullMQ queue (notifications-queue) with exponential backoff, configurable max retries, and delayed/scheduled delivery support
• 5 delivery channels via an abstract strategy pattern: In-App, Email, Webhook, Push, SMS
• Template engine with {{variable}} substitution, locale fallback, and multi-format rendering (plain text, HTML, markdown)

API Endpoints

Method	Path	Description
POST	/notifications	Create and dispatch a notification
GET	/notifications/:userId	List user notifications (paginated, filterable)
GET	/notifications/:userId/unread-count	Unread badge count
PATCH	/notifications/:notificationId/read	Mark single notification read
PATCH	/notifications/:userId/read-all	Mark all read
GET	/notifications/:notificationId/deliveries	Per-channel delivery history
POST	/notifications/schedule	Schedule delayed notification
PATCH	/notifications/:notificationId/cancel	Cancel pending notification
GET/PATCH	/notifications/preferences/:userId	Get/update user notification preferences
GET	/notifications/admin/metrics	Queue depth, delivered/failed counts
POST	/notifications/admin/seed-templates	Seed 9 default notification templates

User Preference Enforcement

• Channel opt-in/opt-out per user
• Quiet hours with time-range checks
• Category-level subscribe/unsubscribe
• Digest mode support
• Frequency settings (instant/digest)

Delivery Tracking & Retry

• Full delivery history recorded per channel with timestamps
• Exponential backoff retry with configurable max attempts (default: 5)
• Dead-letter after exhaustion
• Status lifecycle: PENDING → QUEUED → SENT → DELIVERED / FAILED

Monitoring

• Metrics endpoint exposing: notifications queued, delivered, failed, queue depth
• Prometheus integration compatible (extends existing metrics module)

Testing

• 41 unit/integration tests across 4 test suites — all passing
  • notification.service.spec.ts — 19 tests: creation, delivery, retry, preferences, scheduling, metrics
  • template.service.spec.ts — 9 tests: rendering, locale fallback, substitution
  • delivery-channels.spec.ts — 9 tests: all 5 channels, failure modes
  • notification.processor.spec.ts — 4 tests: job dispatch, unknown job, concurrency

Dependencies

• Depends on: BE-004 (Redis), BE-018 (Event Bus — future integration point)
• New config vars: SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS, SMTP_FROM, NOTIFICATION_QUEUE_DELAY, NOTIFICATION_MAX_RETRIES, NOTIFICATION_RETRY_DELAY

Files Changed

• .env.example — Added SMTP and notification queue configuration
• src/app.module.ts — Registered NotificationModule
• src/notifications/interfaces/notification-payload.interface.ts — Fixed incomplete DeliveryResult interface
• src/notifications/ — 27 new files (entities, DTOs, services, controller, processor, module, tests)

Verification

• TypeScript compilation: zero errors in notification module
• All 41 notification tests: ✅ PASS
• Pre-existing test failures unchanged (unrelated to this PR)

Blocks

• User Dashboard
• Moderator Console
• Governance Portal
• AI Assistant
• Mobile Applications
• Administration Console