How devtron-labs/notifier works
1. What this service is
- This is a TypeScript/Node.js notification orchestrator. It exposes an HTTP API, persists notification-related state in PostgreSQL, and sends notifications through multiple delivery channels.
2. Top-level runtime shape
- The entrypoints are src/server.ts and src/app.ts.
- The app is containerized with Docker and configured through environment variables plus environment-specific JSON config files under config/.
3. API boundary
- HTTP routes are organized in src/routes/.
- The visible surface includes:
- healthRoutes.ts for liveness/readiness style checks
- metricsRoutes.ts for operational metrics
- notificationRoutes.ts for notification-related actions
- specs/api-spec.yaml suggests the API contract is documented separately.
4. Initialization and wiring
- src/services/serviceInitializer.ts is the composition root that likely wires logger, database, pub/sub, repositories, and notification service together.
- Cross-cutting config is centralized in src/config/:
- database.ts for PostgreSQL/TypeORM setup
- logger.ts for structured logging
- nats.ts for message broker connectivity
5. Persistence layer
- Domain data is modeled with TypeORM entities in src/entities/.
- The main stored concepts are:
- users
- events
- notification settings
- notification templates
- notification event logs
- channel-specific configs for SES, Slack, SMTP, and webhook
- Repository classes in src/repository/ isolate database access from services.
6. Notification processing core
- src/notification/service/notificationService.ts is the central business service.
- It likely orchestrates:
- reading event context
- selecting templates and destination settings
- rendering message content
- dispatching to one or more delivery handlers
- recording delivery or processing logs
7. Template and content generation
- Notification content is template-driven using Mustache.
- Templates are stored in src/templates/ and partitioned by channel and event type, notably CI and CD.
- src/templates/templateLoader.ts and helpers in src/common/mustacheHelper.ts handle loading and rendering.
- This makes message formatting a distinct subsystem from transport delivery.
8. Delivery adapters
- Delivery is separated into channel-specific handlers under src/destination/destinationHandlers/:
- sesHandler.ts
- slackHandler.ts
- smtpHandler.ts
- webhookHandler.ts
- This is a clear adapter boundary: the core service prepares message intent, and handlers translate it to external APIs/protocols.
9. Event ingestion and pub/sub
- src/pubSub/ contains broker utilities and a pub/sub abstraction built around NATS.
- src/common/getCommitsFromGitTriggers.ts and src/common/eventLogBuilder.ts suggest the service consumes CI/CD trigger data, extracts commit metadata, and turns it into normalized notification events.
- The flow is likely: external trigger or API request → event normalization → publish/consume via NATS → notification processing.
10. Operational concerns
- Metrics are implemented both as middleware (src/middleware/metrics.ts) and as routes, indicating request and/or business metrics are first-class.
- Health endpoints are isolated from business logic so deployment platforms can probe the service independently.
- src/common/metrics.ts centralizes metric definitions.
11. Domain-specific behavior
- The template structure and test fixtures indicate the service is focused on CI/CD notifications, with different content for success/failure/trigger states.
- src/tests/approvalActionStates.test.ts and template tests suggest the system has stateful notification/approval behavior beyond simple message forwarding.
12. Test and contract surface
- Unit tests cover event parsing, template rendering, notification service behavior, and Slack delivery logic.
- This is useful for architecture diagrams because it shows the core seams: parsing, templating, service orchestration, and destination adapters.
13. External dependencies and infrastructure
- PostgreSQL is the primary data store.
- NATS is the message broker.
- Notification egress goes to Slack, SMTP servers, AWS SES, and arbitrary webhooks.
- Environment variables in the README point to a PostgreSQL-backed deployment with configurable host, port, user, password, and database name.
14. How to draw the main data flow
- External caller or broker event enters the API or pub/sub layer.
- The service normalizes event data, looks up settings/templates in PostgreSQL, renders Mustache content, and dispatches through the appropriate destination handler.
- Delivery outcomes are logged back to the database and exposed via metrics/health endpoints for operations.
Main entry points: notificationService.ts Notifier · serviceInitializer.ts Initializer · app.ts App · index.ts Routes
Components 22
Runtime/API
HTTP entrypoints, routes, and bootstrapping
- Server · Process bootstrap and HTTP startup
src/server.ts - App · Application wiring and middleware setup
src/app.ts - Routes · Route registration and surface assembly
src/routes/index.ts - Notifications · Notification action endpoints
src/routes/notificationRoutes.ts
Notification Core
Event normalization, templating, and orchestration
- Initializer · Wires logger, database, pub/sub, repositories, and services
src/services/serviceInitializer.ts - Notifier · Central notification orchestration service
src/notification/service/notificationService.ts - Event Builder · Builds normalized notification events
src/common/eventLogBuilder.ts - Git Triggers · Extracts commit and trigger context
src/common/getCommitsFromGitTriggers.ts - Template Loader · Loads channel and event templates
src/templates/templateLoader.ts - Mustache · Content rendering helpers
src/common/mustacheHelper.ts
Persistence
Database models and repositories
- Database · TypeORM/PostgreSQL configuration
src/config/database.ts - Entities · Persistent notification and channel models
src/entities/events.ts - Repositories · Database access isolation layer
src/repository/eventsRepository.ts
External Integrations
Message broker and delivery adapters
- Pub/Sub · NATS-based publish/consume utilities
src/pubSub/pubSub.ts - NATS · Message broker connectivity
src/config/nats.ts - Slack · Slack notification handler
src/destination/destinationHandlers/slackHandler.ts - SES · AWS SES notification handler
src/destination/destinationHandlers/sesHandler.ts - SMTP · SMTP notification handler
src/destination/destinationHandlers/smtpHandler.ts - Webhook · Webhook notification handler
src/destination/destinationHandlers/webhookHandler.ts
Operations
Health and metrics surfaces
- Health · Liveness and readiness endpoints
src/routes/healthRoutes.ts - Metrics API · Operational metrics endpoint surface
src/routes/metricsRoutes.ts - Metrics MW · Request/business metrics collection
src/middleware/metrics.ts
Connections 24
- Server → App: starts · Bootstraps the application
- App → Routes: mounts · Registers HTTP route groups
- App → Metrics MW: uses · Attaches metrics middleware
- Routes → Notifications: includes · Notification API surface
- Routes → Health: includes · Health probes
- Routes → Metrics API: includes · Metrics endpoints
- App → Initializer: delegates · Composes runtime dependencies
- Initializer → Database: configures · Initializes persistence layer
- Initializer → Pub/Sub: configures · Initializes broker layer
- Initializer → Repositories: creates · Wires repositories
- Initializer → Notifier: creates · Builds notification service
- Notifier → Event Builder: normalizes · Transforms trigger data into events
- Event Builder → Git Triggers: parses · Extracts commit metadata
- Notifier → Template Loader: renders · Loads channel/event templates
- Template Loader → Mustache: uses · Applies Mustache rendering
- Notifier → Repositories: reads/writes · Fetches settings and logs outcomes
- Repositories → Entities: maps · Repository-backed domain models
- Database → Entities: persists · ORM entity registration
- Pub/Sub → NATS: connects · Broker transport
- Notifier → Slack: dispatches · Slack delivery path
- Notifier → SES: dispatches · SES delivery path
- Notifier → SMTP: dispatches · SMTP delivery path
- Notifier → Webhook: dispatches · Webhook delivery path
- Notifier → Pub/Sub: consumes/publishes · Event-driven processing over NATS