# puneetchhabra22/scalable-notification-system architecture

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

- Interactive diagram: https://gitdiagram.com/puneetchhabra22/scalable-notification-system
- Repository: https://github.com/puneetchhabra22/scalable-notification-system

## Overview

This is a multi-service notification platform: clients submit channel-specific requests, the API validates and enriches them, then priority queues distribute work to processing services and channel consumers. Processing personalizes templates, applies user preferences, prevents duplicates, records notification state, and dispatches email, SMS, or push work. The README documents caching, preference controls, quiet hours, and rate limiting; excerpts confirm template-priority lookup, priority Kafka routing, and delivery-state updates. Several API-to-worker and consumer wiring details are not shown, so those links are marked unverified.

Main entry points: [`notificationservice/src/main/java/com/puneetchhabra/notificationservice/service/NotificationProcessingService.java`](https://github.com/puneetchhabra22/scalable-notification-system/blob/main/notificationservice/src/main/java/com/puneetchhabra/notificationservice/service/NotificationProcessingService.java) (Request Validation), [`EmailConsumer/src/main/java/com/puneetchhabra/EmailConsumer/service/EmailProcessingService.java`](https://github.com/puneetchhabra22/scalable-notification-system/blob/main/EmailConsumer/src/main/java/com/puneetchhabra/EmailConsumer/service/EmailProcessingService.java) (Email Consumer), [`SMSConsumer/src/main/java/com/puneetchhabra/SMSConsumer/service/SmsProcessingService.java`](https://github.com/puneetchhabra22/scalable-notification-system/blob/main/SMSConsumer/src/main/java/com/puneetchhabra/SMSConsumer/service/SmsProcessingService.java) (SMS Consumer), [`PushNConsumer/src/main/java/com/puneetchhabra/PushNConsumer/service/PushNProcessingService.java`](https://github.com/puneetchhabra22/scalable-notification-system/blob/main/PushNConsumer/src/main/java/com/puneetchhabra/PushNConsumer/service/PushNProcessingService.java) (Push Consumer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and Enrichment"]
  node_api["Notification API"]
  node_api_processing["Request Validation"]
  node_priority_router["Priority Kafka Router<br/>[KafkaService.java]"]
end

subgraph group_priority["Priority Processing"]
  node_p1["Priority One Worker"]
  node_p2["Priority Two Worker"]
  node_p3["Priority Three Worker"]
  node_p1_send["Notification Dispatch"]
  node_p2_send["Notification Dispatch"]
  node_p3_send["Notification Dispatch"]
end

subgraph group_delivery["Channel Delivery"]
  node_email_consumer["Email Consumer"]
  node_sms_consumer["SMS Consumer"]
  node_push_consumer["Push Consumer"]
end

subgraph group_state["State and Cache"]
  node_redis[("Redis Cache<br/>[RedisService.java]")]
  node_template_store[("Template Store")]
  node_delivery_logs[("Delivery Logs")]
  node_notifications[("Notifications")]
end

node_client(("Client"))
node_kafka["Kafka"]
node_mysql[("MySQL")]
node_sendgrid["SendGrid"]
node_twilio["Twilio"]
node_push_provider["Push Provider"]

node_client -.->|"submits request"| node_api
node_api -.->|"validates request"| node_api_processing
node_api_processing -->|"reads priority"| node_redis
node_api_processing -->|"loads template"| node_template_store
node_api_processing -.->|"forwards request"| node_priority_router
node_priority_router -->|"routes by priority"| node_kafka
node_kafka -.->|"delivers priority one"| node_p1
node_kafka -.->|"delivers priority two"| node_p2
node_kafka -.->|"delivers priority three"| node_p3
node_p1 -->|"dispatches channels"| node_p1_send
node_p2 -->|"dispatches channels"| node_p2_send
node_p3 -->|"dispatches channels"| node_p3_send
node_p1_send -->|"queues channel work"| node_kafka
node_p2_send -->|"queues channel work"| node_kafka
node_p3_send -->|"queues channel work"| node_kafka
node_kafka -.->|"delivers email work"| node_email_consumer
node_kafka -.->|"delivers SMS work"| node_sms_consumer
node_kafka -.->|"delivers push work"| node_push_consumer
node_email_consumer -.->|"sends email"| node_sendgrid
node_sms_consumer -.->|"sends SMS"| node_twilio
node_push_consumer -.->|"sends push"| node_push_provider
node_email_consumer -->|"updates status"| node_notifications
node_email_consumer -->|"writes delivery result"| node_delivery_logs
node_sms_consumer -->|"updates status"| node_notifications
node_sms_consumer -->|"writes delivery result"| node_delivery_logs
node_push_consumer -->|"updates status"| node_notifications
node_push_consumer -->|"writes delivery result"| node_delivery_logs
node_p1_send -.->|"persists request state"| node_mysql
node_p2_send -.->|"persists request state"| node_mysql
node_p3_send -.->|"persists request state"| node_mysql

click node_api "https://github.com/puneetchhabra22/scalable-notification-system/blob/main/notificationservice/src/main/java/com/puneetchhabra/notificationservice/controllers/NotificationsController.java"
click node_api_processing "https://github.com/puneetchhabra22/scalable-notification-system/blob/main/notificationservice/src/main/java/com/puneetchhabra/notificationservice/service/NotificationProcessingService.java"
click node_priority_router "https://github.com/puneetchhabra22/scalable-notification-system/blob/main/notificationservice/src/main/java/com/puneetchhabra/notificationservice/service/KafkaService.java"
click node_redis "https://github.com/puneetchhabra22/scalable-notification-system/blob/main/notificationservice/src/main/java/com/puneetchhabra/notificationservice/service/RedisService.java"
click node_template_store "https://github.com/puneetchhabra22/scalable-notification-system/blob/main/notificationservice/src/main/java/com/puneetchhabra/notificationservice/repo/TemplateRepository.java"
click node_p1 "https://github.com/puneetchhabra22/scalable-notification-system/blob/main/NotificationProcessorPriority1/src/main/java/com/puneetchhabra/NotificationProcessorPriority1/service/NotificationProcessingService.java"
click node_p2 "https://github.com/puneetchhabra22/scalable-notification-system/blob/main/NotificationProcessorPriority2/src/main/java/com/puneetchhabra/NotificationProcessorPriority2/service/NotificationProcessingService.java"
click node_p3 "https://github.com/puneetchhabra22/scalable-notification-system/blob/main/NotificationProcessorPriority3/src/main/java/com/puneetchhabra/NotificationProcessorPriority3/service/NotificationProcessingService.java"
click node_p1_send "https://github.com/puneetchhabra22/scalable-notification-system/blob/main/NotificationProcessorPriority1/src/main/java/com/puneetchhabra/NotificationProcessorPriority1/service/SendNotificationService.java"
click node_p2_send "https://github.com/puneetchhabra22/scalable-notification-system/blob/main/NotificationProcessorPriority2/src/main/java/com/puneetchhabra/NotificationProcessorPriority2/service/SendNotificationService.java"
click node_p3_send "https://github.com/puneetchhabra22/scalable-notification-system/blob/main/NotificationProcessorPriority3/src/main/java/com/puneetchhabra/NotificationProcessorPriority3/service/SendNotificationService.java"
click node_email_consumer "https://github.com/puneetchhabra22/scalable-notification-system/blob/main/EmailConsumer/src/main/java/com/puneetchhabra/EmailConsumer/service/EmailProcessingService.java"
click node_sms_consumer "https://github.com/puneetchhabra22/scalable-notification-system/blob/main/SMSConsumer/src/main/java/com/puneetchhabra/SMSConsumer/service/SmsProcessingService.java"
click node_push_consumer "https://github.com/puneetchhabra22/scalable-notification-system/blob/main/PushNConsumer/src/main/java/com/puneetchhabra/PushNConsumer/service/PushNProcessingService.java"
click node_delivery_logs "https://github.com/puneetchhabra22/scalable-notification-system/blob/main/NotificationProcessorPriority1/src/main/java/com/puneetchhabra/NotificationProcessorPriority1/repo/DeliveryLogRepository.java"
click node_notifications "https://github.com/puneetchhabra22/scalable-notification-system/blob/main/NotificationProcessorPriority1/src/main/java/com/puneetchhabra/NotificationProcessorPriority1/repo/NotificationRepository.java"

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_api,node_api_processing,node_priority_router,node_client toneBlue
class node_p1,node_p2,node_p3,node_p1_send,node_p2_send,node_p3_send,node_mysql toneAmber
class node_email_consumer,node_sms_consumer,node_push_consumer toneMint
class node_redis,node_template_store,node_delivery_logs,node_notifications toneRose
class node_kafka,node_sendgrid,node_twilio,node_push_provider toneIndigo
```

## Components

### API and Enrichment

- [Notification API](https://github.com/puneetchhabra22/scalable-notification-system/blob/main/notificationservice/src/main/java/com/puneetchhabra/notificationservice/controllers/NotificationsController.java): `notificationservice/src/main/java/com/puneetchhabra/notificationservice/controllers/NotificationsController.java`
- [Request Validation](https://github.com/puneetchhabra22/scalable-notification-system/blob/main/notificationservice/src/main/java/com/puneetchhabra/notificationservice/service/NotificationProcessingService.java): `notificationservice/src/main/java/com/puneetchhabra/notificationservice/service/NotificationProcessingService.java`
- [Priority Kafka Router](https://github.com/puneetchhabra22/scalable-notification-system/blob/main/notificationservice/src/main/java/com/puneetchhabra/notificationservice/service/KafkaService.java): `notificationservice/src/main/java/com/puneetchhabra/notificationservice/service/KafkaService.java`

### Priority Processing

- [Priority One Worker](https://github.com/puneetchhabra22/scalable-notification-system/blob/main/NotificationProcessorPriority1/src/main/java/com/puneetchhabra/NotificationProcessorPriority1/service/NotificationProcessingService.java): `NotificationProcessorPriority1/src/main/java/com/puneetchhabra/NotificationProcessorPriority1/service/NotificationProcessingService.java`
- [Priority Two Worker](https://github.com/puneetchhabra22/scalable-notification-system/blob/main/NotificationProcessorPriority2/src/main/java/com/puneetchhabra/NotificationProcessorPriority2/service/NotificationProcessingService.java): `NotificationProcessorPriority2/src/main/java/com/puneetchhabra/NotificationProcessorPriority2/service/NotificationProcessingService.java`
- [Priority Three Worker](https://github.com/puneetchhabra22/scalable-notification-system/blob/main/NotificationProcessorPriority3/src/main/java/com/puneetchhabra/NotificationProcessorPriority3/service/NotificationProcessingService.java): `NotificationProcessorPriority3/src/main/java/com/puneetchhabra/NotificationProcessorPriority3/service/NotificationProcessingService.java`
- [Notification Dispatch](https://github.com/puneetchhabra22/scalable-notification-system/blob/main/NotificationProcessorPriority1/src/main/java/com/puneetchhabra/NotificationProcessorPriority1/service/SendNotificationService.java): `NotificationProcessorPriority1/src/main/java/com/puneetchhabra/NotificationProcessorPriority1/service/SendNotificationService.java`
- [Notification Dispatch](https://github.com/puneetchhabra22/scalable-notification-system/blob/main/NotificationProcessorPriority2/src/main/java/com/puneetchhabra/NotificationProcessorPriority2/service/SendNotificationService.java): `NotificationProcessorPriority2/src/main/java/com/puneetchhabra/NotificationProcessorPriority2/service/SendNotificationService.java`
- [Notification Dispatch](https://github.com/puneetchhabra22/scalable-notification-system/blob/main/NotificationProcessorPriority3/src/main/java/com/puneetchhabra/NotificationProcessorPriority3/service/SendNotificationService.java): `NotificationProcessorPriority3/src/main/java/com/puneetchhabra/NotificationProcessorPriority3/service/SendNotificationService.java`

### Channel Delivery

- [Email Consumer](https://github.com/puneetchhabra22/scalable-notification-system/blob/main/EmailConsumer/src/main/java/com/puneetchhabra/EmailConsumer/service/EmailProcessingService.java): `EmailConsumer/src/main/java/com/puneetchhabra/EmailConsumer/service/EmailProcessingService.java`
- [SMS Consumer](https://github.com/puneetchhabra22/scalable-notification-system/blob/main/SMSConsumer/src/main/java/com/puneetchhabra/SMSConsumer/service/SmsProcessingService.java): `SMSConsumer/src/main/java/com/puneetchhabra/SMSConsumer/service/SmsProcessingService.java`
- [Push Consumer](https://github.com/puneetchhabra22/scalable-notification-system/blob/main/PushNConsumer/src/main/java/com/puneetchhabra/PushNConsumer/service/PushNProcessingService.java): `PushNConsumer/src/main/java/com/puneetchhabra/PushNConsumer/service/PushNProcessingService.java`

### State and Cache

- [Redis Cache](https://github.com/puneetchhabra22/scalable-notification-system/blob/main/notificationservice/src/main/java/com/puneetchhabra/notificationservice/service/RedisService.java): `notificationservice/src/main/java/com/puneetchhabra/notificationservice/service/RedisService.java`
- [Template Store](https://github.com/puneetchhabra22/scalable-notification-system/blob/main/notificationservice/src/main/java/com/puneetchhabra/notificationservice/repo/TemplateRepository.java): `notificationservice/src/main/java/com/puneetchhabra/notificationservice/repo/TemplateRepository.java`
- [Delivery Logs](https://github.com/puneetchhabra22/scalable-notification-system/blob/main/NotificationProcessorPriority1/src/main/java/com/puneetchhabra/NotificationProcessorPriority1/repo/DeliveryLogRepository.java): `NotificationProcessorPriority1/src/main/java/com/puneetchhabra/NotificationProcessorPriority1/repo/DeliveryLogRepository.java`
- [Notifications](https://github.com/puneetchhabra22/scalable-notification-system/blob/main/NotificationProcessorPriority1/src/main/java/com/puneetchhabra/NotificationProcessorPriority1/repo/NotificationRepository.java): `NotificationProcessorPriority1/src/main/java/com/puneetchhabra/NotificationProcessorPriority1/repo/NotificationRepository.java`

### Other components

- **Client**
- **Kafka**
- **MySQL**
- **SendGrid**
- **Twilio**
- **Push Provider**

## Connections

- Client → Notification API: submits request
- Notification API → Request Validation: validates request (evidence: `notificationservice/src/main/java/com/puneetchhabra/notificationservice/controllers/NotificationsController.java`)
- Request Validation → Redis Cache: reads priority (evidence: `notificationservice/src/main/java/com/puneetchhabra/notificationservice/service/NotificationProcessingService.java`)
- Request Validation → Template Store: loads template (evidence: `notificationservice/src/main/java/com/puneetchhabra/notificationservice/service/NotificationProcessingService.java`)
- Request Validation → Priority Kafka Router: forwards request
- Priority Kafka Router → Kafka: routes by priority (evidence: `notificationservice/src/main/java/com/puneetchhabra/notificationservice/service/KafkaService.java`)
- Kafka → Priority One Worker: delivers priority one
- Kafka → Priority Two Worker: delivers priority two
- Kafka → Priority Three Worker: delivers priority three
- Priority One Worker → Notification Dispatch: dispatches channels (evidence: `NotificationProcessorPriority1/src/main/java/com/puneetchhabra/NotificationProcessorPriority1/service/NotificationProcessingService.java`)
- Priority Two Worker → Notification Dispatch: dispatches channels (evidence: `NotificationProcessorPriority2/src/main/java/com/puneetchhabra/NotificationProcessorPriority2/service/NotificationProcessingService.java`)
- Priority Three Worker → Notification Dispatch: dispatches channels (evidence: `NotificationProcessorPriority3/src/main/java/com/puneetchhabra/NotificationProcessorPriority3/service/NotificationProcessingService.java`)
- Notification Dispatch → Kafka: queues channel work (evidence: `NotificationProcessorPriority1/src/main/java/com/puneetchhabra/NotificationProcessorPriority1/service/SendNotificationService.java`)
- Notification Dispatch → Kafka: queues channel work (evidence: `NotificationProcessorPriority2/src/main/java/com/puneetchhabra/NotificationProcessorPriority2/service/SendNotificationService.java`)
- Notification Dispatch → Kafka: queues channel work (evidence: `NotificationProcessorPriority3/src/main/java/com/puneetchhabra/NotificationProcessorPriority3/service/SendNotificationService.java`)
- Kafka → Email Consumer: delivers email work
- Kafka → SMS Consumer: delivers SMS work
- Kafka → Push Consumer: delivers push work
- Email Consumer → SendGrid: sends email
- SMS Consumer → Twilio: sends SMS
- Push Consumer → Push Provider: sends push
- Email Consumer → Notifications: updates status (evidence: `EmailConsumer/src/main/java/com/puneetchhabra/EmailConsumer/service/EmailProcessingService.java`)
- Email Consumer → Delivery Logs: writes delivery result (evidence: `EmailConsumer/src/main/java/com/puneetchhabra/EmailConsumer/service/EmailProcessingService.java`)
- SMS Consumer → Notifications: updates status (evidence: `SMSConsumer/src/main/java/com/puneetchhabra/SMSConsumer/service/SmsProcessingService.java`)
- SMS Consumer → Delivery Logs: writes delivery result (evidence: `SMSConsumer/src/main/java/com/puneetchhabra/SMSConsumer/service/SmsProcessingService.java`)
- Push Consumer → Notifications: updates status (evidence: `PushNConsumer/src/main/java/com/puneetchhabra/PushNConsumer/service/PushNProcessingService.java`)
- Push Consumer → Delivery Logs: writes delivery result (evidence: `PushNConsumer/src/main/java/com/puneetchhabra/PushNConsumer/service/PushNProcessingService.java`)
- Notification Dispatch → MySQL: persists request state
- Notification Dispatch → MySQL: persists request state
- Notification Dispatch → MySQL: persists request state
