# devtron-labs/notifier architecture

> Architecture diagram of the GitHub repository devtron-labs/notifier, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/devtron-labs/notifier
- Repository: https://github.com/devtron-labs/notifier

## Overview

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: [`src/notification/service/notificationService.ts`](https://github.com/devtron-labs/notifier/blob/main/src/notification/service/notificationService.ts) (Notifier), [`src/services/serviceInitializer.ts`](https://github.com/devtron-labs/notifier/blob/main/src/services/serviceInitializer.ts) (Initializer), [`src/app.ts`](https://github.com/devtron-labs/notifier/blob/main/src/app.ts) (App), [`src/routes/index.ts`](https://github.com/devtron-labs/notifier/blob/main/src/routes/index.ts) (Routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_runtime["Runtime/API"]
  node_n_server["Server<br/>entrypoint<br/>[server.ts]"]
  node_n_app["App<br/>composition<br/>[app.ts]"]
  node_n_routes["Routes<br/>http-router<br/>[index.ts]"]
  node_n_notification_routes["Notifications<br/>http-routes"]
end

subgraph group_grp_core["Notification Core"]
  node_n_initializer["Initializer<br/>composition-root"]
  node_n_service["Notifier<br/>domain-service"]
  node_n_event_builder["Event Builder<br/>event-normalizer<br/>[eventLogBuilder.ts]"]
  node_n_git_triggers["Git Triggers<br/>parser"]
  node_n_template_loader["Template Loader<br/>templating<br/>[templateLoader.ts]"]
  node_n_mustache["Mustache<br/>templating-helper<br/>[mustacheHelper.ts]"]
end

subgraph group_grp_data["Persistence"]
  node_n_db[("Database<br/>postgres-orm<br/>[database.ts]")]
  node_n_entities["Entities<br/>domain-models<br/>[events.ts]"]
  node_n_repos["Repositories<br/>data-access"]
end

subgraph group_grp_integrations["External Integrations"]
  node_n_pubsub["Pub/Sub<br/>broker-abstraction<br/>[pubSub.ts]"]
  node_n_nats["NATS<br/>broker<br/>[nats.ts]"]
  node_n_slack["Slack<br/>delivery-adapter<br/>[slackHandler.ts]"]
  node_n_ses["SES<br/>delivery-adapter<br/>[sesHandler.ts]"]
  node_n_smtp["SMTP<br/>delivery-adapter<br/>[smtpHandler.ts]"]
  node_n_webhook["Webhook<br/>delivery-adapter<br/>[webhookHandler.ts]"]
end

subgraph group_grp_ops["Operations"]
  node_n_health_routes["Health<br/>http-routes<br/>[healthRoutes.ts]"]
  node_n_metrics_routes["Metrics API<br/>http-routes<br/>[metricsRoutes.ts]"]
  node_n_metrics_mw["Metrics MW<br/>middleware<br/>[metrics.ts]"]
end

node_n_server -->|"starts"| node_n_app
node_n_app -->|"mounts"| node_n_routes
node_n_app -->|"uses"| node_n_metrics_mw
node_n_routes -->|"includes"| node_n_notification_routes
node_n_routes -->|"includes"| node_n_health_routes
node_n_routes -->|"includes"| node_n_metrics_routes
node_n_app -->|"delegates"| node_n_initializer
node_n_initializer -->|"configures"| node_n_db
node_n_initializer -->|"configures"| node_n_pubsub
node_n_initializer -->|"creates"| node_n_repos
node_n_initializer -->|"creates"| node_n_service
node_n_service -->|"normalizes"| node_n_event_builder
node_n_event_builder -->|"parses"| node_n_git_triggers
node_n_service -->|"renders"| node_n_template_loader
node_n_template_loader -->|"uses"| node_n_mustache
node_n_service -->|"reads/writes"| node_n_repos
node_n_repos -->|"maps"| node_n_entities
node_n_db -->|"persists"| node_n_entities
node_n_pubsub -->|"connects"| node_n_nats
node_n_service -->|"dispatches"| node_n_slack
node_n_service -->|"dispatches"| node_n_ses
node_n_service -->|"dispatches"| node_n_smtp
node_n_service -->|"dispatches"| node_n_webhook
node_n_service -->|"consumes/publishes"| node_n_pubsub

click node_n_server "https://github.com/devtron-labs/notifier/blob/main/src/server.ts"
click node_n_app "https://github.com/devtron-labs/notifier/blob/main/src/app.ts"
click node_n_routes "https://github.com/devtron-labs/notifier/blob/main/src/routes/index.ts"
click node_n_notification_routes "https://github.com/devtron-labs/notifier/blob/main/src/routes/notificationRoutes.ts"
click node_n_health_routes "https://github.com/devtron-labs/notifier/blob/main/src/routes/healthRoutes.ts"
click node_n_metrics_routes "https://github.com/devtron-labs/notifier/blob/main/src/routes/metricsRoutes.ts"
click node_n_metrics_mw "https://github.com/devtron-labs/notifier/blob/main/src/middleware/metrics.ts"
click node_n_initializer "https://github.com/devtron-labs/notifier/blob/main/src/services/serviceInitializer.ts"
click node_n_service "https://github.com/devtron-labs/notifier/blob/main/src/notification/service/notificationService.ts"
click node_n_event_builder "https://github.com/devtron-labs/notifier/blob/main/src/common/eventLogBuilder.ts"
click node_n_git_triggers "https://github.com/devtron-labs/notifier/blob/main/src/common/getCommitsFromGitTriggers.ts"
click node_n_template_loader "https://github.com/devtron-labs/notifier/blob/main/src/templates/templateLoader.ts"
click node_n_mustache "https://github.com/devtron-labs/notifier/blob/main/src/common/mustacheHelper.ts"
click node_n_pubsub "https://github.com/devtron-labs/notifier/blob/main/src/pubSub/pubSub.ts"
click node_n_db "https://github.com/devtron-labs/notifier/blob/main/src/config/database.ts"
click node_n_entities "https://github.com/devtron-labs/notifier/blob/main/src/entities/events.ts"
click node_n_repos "https://github.com/devtron-labs/notifier/blob/main/src/repository/eventsRepository.ts"
click node_n_nats "https://github.com/devtron-labs/notifier/blob/main/src/config/nats.ts"
click node_n_slack "https://github.com/devtron-labs/notifier/blob/main/src/destination/destinationHandlers/slackHandler.ts"
click node_n_ses "https://github.com/devtron-labs/notifier/blob/main/src/destination/destinationHandlers/sesHandler.ts"
click node_n_smtp "https://github.com/devtron-labs/notifier/blob/main/src/destination/destinationHandlers/smtpHandler.ts"
click node_n_webhook "https://github.com/devtron-labs/notifier/blob/main/src/destination/destinationHandlers/webhookHandler.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_server,node_n_app,node_n_routes,node_n_notification_routes toneBlue
class node_n_initializer,node_n_service,node_n_event_builder,node_n_git_triggers,node_n_template_loader,node_n_mustache toneAmber
class node_n_db,node_n_entities,node_n_repos toneMint
class node_n_pubsub,node_n_nats,node_n_slack,node_n_ses,node_n_smtp,node_n_webhook toneRose
class node_n_health_routes,node_n_metrics_routes,node_n_metrics_mw toneIndigo
```

## Components

### Runtime/API

HTTP entrypoints, routes, and bootstrapping

- [Server](https://github.com/devtron-labs/notifier/blob/main/src/server.ts): entrypoint · Process bootstrap and HTTP startup · `src/server.ts`
- [App](https://github.com/devtron-labs/notifier/blob/main/src/app.ts): composition · Application wiring and middleware setup · `src/app.ts`
- [Routes](https://github.com/devtron-labs/notifier/blob/main/src/routes/index.ts): http-router · Route registration and surface assembly · `src/routes/index.ts`
- [Notifications](https://github.com/devtron-labs/notifier/blob/main/src/routes/notificationRoutes.ts): http-routes · Notification action endpoints · `src/routes/notificationRoutes.ts`

### Notification Core

Event normalization, templating, and orchestration

- [Initializer](https://github.com/devtron-labs/notifier/blob/main/src/services/serviceInitializer.ts): composition-root · Wires logger, database, pub/sub, repositories, and services · `src/services/serviceInitializer.ts`
- [Notifier](https://github.com/devtron-labs/notifier/blob/main/src/notification/service/notificationService.ts): domain-service · Central notification orchestration service · `src/notification/service/notificationService.ts`
- [Event Builder](https://github.com/devtron-labs/notifier/blob/main/src/common/eventLogBuilder.ts): event-normalizer · Builds normalized notification events · `src/common/eventLogBuilder.ts`
- [Git Triggers](https://github.com/devtron-labs/notifier/blob/main/src/common/getCommitsFromGitTriggers.ts): parser · Extracts commit and trigger context · `src/common/getCommitsFromGitTriggers.ts`
- [Template Loader](https://github.com/devtron-labs/notifier/blob/main/src/templates/templateLoader.ts): templating · Loads channel and event templates · `src/templates/templateLoader.ts`
- [Mustache](https://github.com/devtron-labs/notifier/blob/main/src/common/mustacheHelper.ts): templating-helper · Content rendering helpers · `src/common/mustacheHelper.ts`

### Persistence

Database models and repositories

- [Database](https://github.com/devtron-labs/notifier/blob/main/src/config/database.ts): postgres-orm · TypeORM/PostgreSQL configuration · `src/config/database.ts`
- [Entities](https://github.com/devtron-labs/notifier/blob/main/src/entities/events.ts): domain-models · Persistent notification and channel models · `src/entities/events.ts`
- [Repositories](https://github.com/devtron-labs/notifier/blob/main/src/repository/eventsRepository.ts): data-access · Database access isolation layer · `src/repository/eventsRepository.ts`

### External Integrations

Message broker and delivery adapters

- [Pub/Sub](https://github.com/devtron-labs/notifier/blob/main/src/pubSub/pubSub.ts): broker-abstraction · NATS-based publish/consume utilities · `src/pubSub/pubSub.ts`
- [NATS](https://github.com/devtron-labs/notifier/blob/main/src/config/nats.ts): broker · Message broker connectivity · `src/config/nats.ts`
- [Slack](https://github.com/devtron-labs/notifier/blob/main/src/destination/destinationHandlers/slackHandler.ts): delivery-adapter · Slack notification handler · `src/destination/destinationHandlers/slackHandler.ts`
- [SES](https://github.com/devtron-labs/notifier/blob/main/src/destination/destinationHandlers/sesHandler.ts): delivery-adapter · AWS SES notification handler · `src/destination/destinationHandlers/sesHandler.ts`
- [SMTP](https://github.com/devtron-labs/notifier/blob/main/src/destination/destinationHandlers/smtpHandler.ts): delivery-adapter · SMTP notification handler · `src/destination/destinationHandlers/smtpHandler.ts`
- [Webhook](https://github.com/devtron-labs/notifier/blob/main/src/destination/destinationHandlers/webhookHandler.ts): delivery-adapter · Webhook notification handler · `src/destination/destinationHandlers/webhookHandler.ts`

### Operations

Health and metrics surfaces

- [Health](https://github.com/devtron-labs/notifier/blob/main/src/routes/healthRoutes.ts): http-routes · Liveness and readiness endpoints · `src/routes/healthRoutes.ts`
- [Metrics API](https://github.com/devtron-labs/notifier/blob/main/src/routes/metricsRoutes.ts): http-routes · Operational metrics endpoint surface · `src/routes/metricsRoutes.ts`
- [Metrics MW](https://github.com/devtron-labs/notifier/blob/main/src/middleware/metrics.ts): middleware · Request/business metrics collection · `src/middleware/metrics.ts`

## Connections

- 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
