# akshay931/distri_notification_and_alert_system architecture

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

- Interactive diagram: https://gitdiagram.com/akshay931/distri_notification_and_alert_system
- Repository: https://github.com/akshay931/distri_notification_and_alert_system

## Overview

#### Purpose and Entry Point
A Node.js/Express distributed notification backend for ingesting, processing, scheduling, and delivering Email, SMS, and Push alerts. The application entry point is `src/server.js`, exposing `/notify` for notification submission and `/analytics` for delivery metrics.

#### Runtime and Deployment Boundary
The system uses Node.js with Express, Kafka for asynchronous service decoupling, MongoDB through Mongoose for persistent state, and `node-schedule` for deferred work. Container orchestration is defined by `Dockerfile` and `docker-compose.yml`; Kafka and MongoDB are material infrastructure dependencies.

#### Ingestion Stage
`services/notificationIngestion.js` receives and validates notification requests from the API layer before publishing accepted work to the Kafka `notifications` topic. This isolates synchronous client handling from downstream processing and delivery latency.

#### Processing and Scheduling Engine
`services/notificationProcessing.js` consumes notification work, classifies urgent/high-priority versus deferred messages, and applies delivery eligibility rules. Scheduled notifications are persisted and revisited through the scheduling runtime rather than delivered directly.

Core policy queries are separated from orchestration:
- `queries/throttling.js`
- `queries/quietHours.js`
- `queries/deduplication.js`
- `queries/aggregation.js`
- `queries/urgentAlerts.js`

These rules determine whether a notification is immediately delivered, suppressed, combined, or rescheduled.

#### Persistent Domain Model
MongoDB documents define the key state boundary:
- `models/notification.js` stores notification lifecycle data, scheduling, delivery status, retries, and likely audit information.
- `models/user.js` holds recipient preferences such as channel choices, quiet hours, and rate limits.

Processing reads user policy and notification history from this persistence layer to make rule-driven decisions.

#### Delivery and Reliability
`services/notificationDelivery.js` performs channel delivery through mock Email/SMS/Push integrations. It records delivery outcomes in MongoDB and retries failed attempts, separating transport-specific failure handling from policy evaluation in the processor.

The intended flow is: API request → Kafka publication → processing/rules → immediate or scheduled delivery → persisted status and retry updates.

#### Analytics Surface
`services/analytics.js` aggregates persisted notification and delivery records for the `/analytics` API. Analytics is a read-oriented boundary for delivery success, retries, and engagement/operational metrics, rather than part of the delivery critical path.

Main entry points: [`services/notificationProcessing.js`](https://github.com/akshay931/distri_notification_and_alert_system/blob/main/services/notificationProcessing.js) (Notification processing), [`docker-compose.yml`](https://github.com/akshay931/distri_notification_and_alert_system/blob/main/docker-compose.yml) (Container deployment), [`models/notification.js`](https://github.com/akshay931/distri_notification_and_alert_system/blob/main/models/notification.js) (Notification records), [`services/notificationDelivery.js`](https://github.com/akshay931/distri_notification_and_alert_system/blob/main/services/notificationDelivery.js) (Notification delivery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API Surface"]
  node_server["Express server<br/>Node.js entry point<br/>[server.js]"]
  node_notify["/notify<br/>submission endpoint<br/>[server.js]"]
  node_analytics_endpoint["/analytics<br/>metrics endpoint<br/>[server.js]"]
end

subgraph group_services["Notification Services"]
  node_ingestion["Notification ingestion<br/>request validation"]
  node_processing["Notification processing<br/>policy orchestrator"]
  node_delivery["Notification delivery<br/>channel delivery"]
  node_analytics["Analytics service<br/>metrics aggregation<br/>[analytics.js]"]
end

subgraph group_policy["Policy Rules"]
  node_throttling["Throttling<br/>policy query<br/>[throttling.js]"]
  node_quiet_hours["Quiet hours<br/>policy query<br/>[quietHours.js]"]
  node_deduplication["Deduplication<br/>policy query<br/>[deduplication.js]"]
  node_aggregation["Aggregation<br/>policy query<br/>[aggregation.js]"]
  node_urgent_alerts["Urgent alerts<br/>policy query<br/>[urgentAlerts.js]"]
end

subgraph group_infra["Runtime Infrastructure"]
  node_kafka["Kafka notifications<br/>message topic"]
  node_scheduling["Scheduling runtime<br/>node-schedule"]
  node_channels["Email / SMS / Push<br/>mock integrations"]
  node_notification_model[("Notification records<br/>Mongoose model<br/>[notification.js]")]
  node_user_model[("User preferences<br/>Mongoose model<br/>[user.js]")]
  node_mongodb[("MongoDB<br/>persistent datastore")]
  node_containers{{"Container deployment<br/>Docker Compose<br/>[docker-compose.yml]"}}
  node_dockerfile["Application image<br/>Dockerfile"]
end

node_server -->|"routes"| node_notify
node_server -->|"routes"| node_analytics_endpoint
node_notify -->|"submits"| node_ingestion
node_ingestion -->|"publishes accepted work"| node_kafka
node_kafka -->|"consumes"| node_processing
node_processing -->|"evaluates"| node_throttling
node_processing -->|"evaluates"| node_quiet_hours
node_processing -->|"evaluates"| node_deduplication
node_processing -->|"evaluates"| node_aggregation
node_processing -->|"classifies"| node_urgent_alerts
node_processing -->|"reads preferences"| node_user_model
node_processing -->|"reads and updates state"| node_notification_model
node_processing -->|"immediate delivery"| node_delivery
node_processing -->|"defers eligible work"| node_scheduling
node_scheduling -.->|"revisits scheduled work"| node_processing
node_delivery -->|"sends via"| node_channels
node_delivery -->|"records outcomes and retries"| node_notification_model
node_notification_model -->|"persists"| node_mongodb
node_user_model -->|"persists"| node_mongodb
node_analytics_endpoint -->|"queries"| node_analytics
node_analytics -->|"aggregates records"| node_notification_model
node_dockerfile -->|"builds application image"| node_containers
node_containers -.->|"runs"| node_server
node_containers -.->|"orchestrates"| node_kafka
node_containers -.->|"orchestrates"| node_mongodb

click node_server "https://github.com/akshay931/distri_notification_and_alert_system/blob/main/src/server.js"
click node_notify "https://github.com/akshay931/distri_notification_and_alert_system/blob/main/src/server.js"
click node_analytics_endpoint "https://github.com/akshay931/distri_notification_and_alert_system/blob/main/src/server.js"
click node_ingestion "https://github.com/akshay931/distri_notification_and_alert_system/blob/main/services/notificationIngestion.js"
click node_processing "https://github.com/akshay931/distri_notification_and_alert_system/blob/main/services/notificationProcessing.js"
click node_delivery "https://github.com/akshay931/distri_notification_and_alert_system/blob/main/services/notificationDelivery.js"
click node_notification_model "https://github.com/akshay931/distri_notification_and_alert_system/blob/main/models/notification.js"
click node_user_model "https://github.com/akshay931/distri_notification_and_alert_system/blob/main/models/user.js"
click node_throttling "https://github.com/akshay931/distri_notification_and_alert_system/blob/main/queries/throttling.js"
click node_quiet_hours "https://github.com/akshay931/distri_notification_and_alert_system/blob/main/queries/quietHours.js"
click node_deduplication "https://github.com/akshay931/distri_notification_and_alert_system/blob/main/queries/deduplication.js"
click node_aggregation "https://github.com/akshay931/distri_notification_and_alert_system/blob/main/queries/aggregation.js"
click node_urgent_alerts "https://github.com/akshay931/distri_notification_and_alert_system/blob/main/queries/urgentAlerts.js"
click node_analytics "https://github.com/akshay931/distri_notification_and_alert_system/blob/main/services/analytics.js"
click node_containers "https://github.com/akshay931/distri_notification_and_alert_system/blob/main/docker-compose.yml"
click node_dockerfile "https://github.com/akshay931/distri_notification_and_alert_system/blob/main/Dockerfile"

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_server,node_notify,node_analytics_endpoint toneBlue
class node_ingestion,node_processing,node_delivery,node_analytics toneAmber
class node_throttling,node_quiet_hours,node_deduplication,node_aggregation,node_urgent_alerts toneMint
class node_kafka,node_scheduling,node_channels,node_notification_model,node_user_model,node_mongodb,node_containers,node_dockerfile toneRose
```

## Components

### API Surface

- [Express server](https://github.com/akshay931/distri_notification_and_alert_system/blob/main/src/server.js): Node.js entry point · Exposes notification submission and analytics endpoints. · `src/server.js`
- [/notify](https://github.com/akshay931/distri_notification_and_alert_system/blob/main/src/server.js): submission endpoint · `src/server.js`
- [/analytics](https://github.com/akshay931/distri_notification_and_alert_system/blob/main/src/server.js): metrics endpoint · `src/server.js`

### Notification Services

- [Notification ingestion](https://github.com/akshay931/distri_notification_and_alert_system/blob/main/services/notificationIngestion.js): request validation · Validates accepted notification requests before asynchronous publication. · `services/notificationIngestion.js`
- [Notification processing](https://github.com/akshay931/distri_notification_and_alert_system/blob/main/services/notificationProcessing.js): policy orchestrator · Classifies work and selects immediate, suppressed, combined, or deferred handling. · `services/notificationProcessing.js`
- [Notification delivery](https://github.com/akshay931/distri_notification_and_alert_system/blob/main/services/notificationDelivery.js): channel delivery · Delivers Email, SMS, and Push messages and handles failed-attempt retries. · `services/notificationDelivery.js`
- [Analytics service](https://github.com/akshay931/distri_notification_and_alert_system/blob/main/services/analytics.js): metrics aggregation · Reads delivery records for success, retry, and operational metrics. · `services/analytics.js`

### Policy Rules

- [Throttling](https://github.com/akshay931/distri_notification_and_alert_system/blob/main/queries/throttling.js): policy query · `queries/throttling.js`
- [Quiet hours](https://github.com/akshay931/distri_notification_and_alert_system/blob/main/queries/quietHours.js): policy query · `queries/quietHours.js`
- [Deduplication](https://github.com/akshay931/distri_notification_and_alert_system/blob/main/queries/deduplication.js): policy query · `queries/deduplication.js`
- [Aggregation](https://github.com/akshay931/distri_notification_and_alert_system/blob/main/queries/aggregation.js): policy query · `queries/aggregation.js`
- [Urgent alerts](https://github.com/akshay931/distri_notification_and_alert_system/blob/main/queries/urgentAlerts.js): policy query · `queries/urgentAlerts.js`

### Runtime Infrastructure

- **Kafka notifications**: message topic · The notifications topic decouples submission from processing.
- **Scheduling runtime**: node-schedule · Revisits persisted deferred notifications when eligible.
- **Email / SMS / Push**: mock integrations
- [Notification records](https://github.com/akshay931/distri_notification_and_alert_system/blob/main/models/notification.js): Mongoose model · Stores lifecycle, schedule, status, and retry state. · `models/notification.js`
- [User preferences](https://github.com/akshay931/distri_notification_and_alert_system/blob/main/models/user.js): Mongoose model · Stores channel preferences, quiet hours, and rate limits. · `models/user.js`
- **MongoDB**: persistent datastore
- [Container deployment](https://github.com/akshay931/distri_notification_and_alert_system/blob/main/docker-compose.yml): Docker Compose · Defines the application, Kafka, and MongoDB runtime boundary. · `docker-compose.yml`
- [Application image](https://github.com/akshay931/distri_notification_and_alert_system/blob/main/Dockerfile): Dockerfile · `Dockerfile`

## Connections

- Express server → /notify: routes
- Express server → /analytics: routes
- /notify → Notification ingestion: submits
- Notification ingestion → Kafka notifications: publishes accepted work
- Kafka notifications → Notification processing: consumes
- Notification processing → Throttling: evaluates
- Notification processing → Quiet hours: evaluates
- Notification processing → Deduplication: evaluates
- Notification processing → Aggregation: evaluates
- Notification processing → Urgent alerts: classifies
- Notification processing → User preferences: reads preferences
- Notification processing → Notification records: reads and updates state
- Notification processing → Notification delivery: immediate delivery
- Notification processing → Scheduling runtime: defers eligible work
- Scheduling runtime → Notification processing: revisits scheduled work
- Notification delivery → Email / SMS / Push: sends via
- Notification delivery → Notification records: records outcomes and retries
- Notification records → MongoDB: persists
- User preferences → MongoDB: persists
- /analytics → Analytics service: queries
- Analytics service → Notification records: aggregates records
- Application image → Container deployment: builds application image
- Container deployment → Express server: runs
- Container deployment → Kafka notifications: orchestrates
- Container deployment → MongoDB: orchestrates