NestJS notification orchestration service
A tested NestJS reliability laboratory for notification policy, quiet-time scheduling, bounded retry, channel fallback, idempotency, and tamper-evident lifecycle records.
Project definition
Problem statement
Applications often duplicate notification logic, bind business events to one provider, and confuse queue completion with recipient delivery.
The service must preserve one notification intent while applying channel preferences, quiet-time rules, bounded retries, permanent-failure fallback, duplicate controls, and inspectable lifecycle evidence.
Project objectives
- Accept and validate typed notification requests with synthetic recipients.
- Select permitted channels and calculate quiet-time scheduling from explicit policy.
- Retry only eligible failures and move to a permitted fallback when required.
- Prevent request-key aliasing and repeated terminal processing.
- Retain testable attempt, outcome, metric, and hash-chain evidence.
Project structure
Project components
Notification API
Validates bounded intent, templates, variables, synthetic recipient keys, channels, priority, profiles, and semantic idempotency.
Policy engine
Intersects requested and enabled channels, preserves fallback order, applies priority, and calculates same-day or overnight quiet-time delay.
BullMQ worker
Schedules deterministic jobs, classifies controlled provider outcomes, applies three-attempt retry, and starts permitted fallback work.
Controlled adapters
Reproduce success, timeout, permanent failure, one-time rate limit, and total failure without sending any message.
Lifecycle ledger
Stores attempts and hash-linked accepted, scheduled, processing, delivered, failed, suppressed, and cancelled evidence in PostgreSQL.
Methodology
Project workflow
- 01Accept intent
The API validates a synthetic request and binds its idempotency key to a canonical request fingerprint.
- 02Resolve policy
The pure policy engine selects the ordered channel plan and calculates immediate or scheduled execution.
- 03Queue work
PostgreSQL retains lifecycle state and BullMQ stores the first deterministic channel job.
- 04Classify attempts
The worker records each controlled adapter result and chooses delivery, retry, fallback, or final failure.
- 05Verify evidence
API results, attempts, metrics, scenario files, and the canonical ledger verifier explain the complete lifecycle.
Demonstration scenario
A synthetic status notice prefers email and permits webhook fallback. The controlled email adapter returns a permanent failure, the worker records the attempt, schedules the webhook path, closes the notification as delivered, and verifies the complete hash-linked ledger.
Engineering
Tools and method
- NestJS application
- Typed controllers, DTO validation, an API-key guard, throttling, dependency injection, and framework-independent domain functions.
- Queue system
- BullMQ and Redis for delayed jobs, bounded concurrency, exponential retry, deterministic job identity, and worker recovery.
- Persistence
- PostgreSQL entities for notifications, preferences, templates, attempts, and canonical hash-linked ledger events.
- Observability and tests
- OpenTelemetry initialization, bounded local metrics, 53 Jest tests, 25 labelled scenarios, and Docker Compose integration.
Testing
Evaluation
Evaluation measures
- 25 of 25 labelled scenarios match exactly
- 25 of 25 scenarios remain deterministic across 100 repeats
- 2,525 total scenario evaluations
- 53 passing tests with 99.24 percent line coverage
- Duplicate return and changed-body collision rejection
- PostgreSQL, Redis, retry, fallback, final failure, authorization, and ledger verification in containers
Project boundaries
- All recipient keys and provider outcomes are synthetic.
- The project sends no real email, SMS, or webhook traffic.
- Queue completion is not claimed as proof of recipient delivery.
- Production identity, consent governance, provider credentials, exactly-once effects, and capacity certification are outside scope.
Included
- 01Notification API, policy engine, BullMQ worker, controlled provider adapters, lifecycle ledger, and experiment suite
- 02Prepared sample data and demonstration scenarios
- 03Automated tests and measured results
- 04Complete source code in a private GitHub repository
- 05Complete project documentation in PDF and editable Word formats with synopsis, abstract, methodology, architecture diagrams, test results, screenshots, and conclusion
- 06Setup and usage guide
Project record
No information is collected on this page.
- Permanent project ID
- GP-CS-1MYQLD1
- Catalogued
- 21 Aug 2026
- Completed
- 25 Aug 2026
- Verified
- 25 Aug 2026
- Demonstration
- Included in repository
Handover
After purchase
- 01Payment is confirmed
The project is marked unavailable and cannot be purchased again.
- 02Repository access is granted
The buyer's submitted GitHub account receives access to the private repository.
- 03The purchase record is delivered
The certification sheet is prepared from the reviewed buyer details and sent privately by email.