# yhoney-72/notifyhub architecture

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

- Interactive diagram: https://gitdiagram.com/yhoney-72/notifyhub
- Repository: https://github.com/yhoney-72/notifyhub

## Overview

NotifyHub is a REST notification service: authenticated clients submit raw or templated email/SMS requests, receive acceptance, then Kafka-driven workers deliver them and update status for later history queries. Separate branches manage shared templates and JWT/refresh-token authentication. The README documents retry topics, DLT, Redis/PostgreSQL idempotency, and monitoring; sampled source confirms key service, persistence, and delivery calls. Some unsampled subsystem links are based on README descriptions rather than inspected implementations.

Main entry points: [`src/main/java/com/notifyhub/notification/service/NotificationServiceImpl.java`](https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/notification/service/NotificationServiceImpl.java) (Request and History Service), [`src/main/java/com/notifyhub/engine/NotificationEngine.java`](https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/engine/NotificationEngine.java) (Notification Engine), [`src/main/java/com/notifyhub/security/OAuth/GoogleOAuth2SuccessHandler.java`](https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/security/OAuth/GoogleOAuth2SuccessHandler.java) (Google OAuth Handler), [`src/main/java/com/notifyhub/security/service/RefreshTokenService.java`](https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/security/service/RefreshTokenService.java) (Refresh Token Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Notification API"]
  node_notify_api["Notification Endpoints"]
  node_notify_service["Request and History Service"]
end

subgraph group_delivery["Async Delivery"]
  node_kafka_producer["Event Producer"]
  node_event_consumer["Event Consumer"]
  node_engine["Notification Engine"]
  node_email_sender["Email Sender"]
  node_email_provider["Email Provider<br/>[EmailProvider.java]"]
  node_sms_sender["SMS Sender"]
  node_sms_provider["SMS Provider<br/>[SmsProvider.java]"]
end

subgraph group_templates["Template Management"]
  node_template_api["Template Endpoints"]
  node_template_service["Template Service"]
  node_template_db[("Templates")]
  node_template_renderer["Template Renderer"]
end

subgraph group_security["Authentication"]
  node_auth_api["Authentication Endpoints"]
  node_refresh_service["Refresh Token Service"]
  node_refresh_repo["Refresh Token Repository"]
  node_users["User Repository"]
  node_google_oauth["Google OAuth Handler"]
end

subgraph group_state["Persistence and Idempotency"]
  node_notification_db[("Notifications<br/>[Notification.java]")]
  node_notification_repo["Notification Repository"]
  node_idempotency["Redis Idempotency"]
  node_user_db[("Users and Tokens<br/>[AppUser.java]")]
end

node_client(("Backend Client"))
node_redis[("Redis")]
node_postgres[("PostgreSQL")]
node_kafka["Kafka Topics"]
node_smtp["SMTP Service"]
node_twilio["Twilio"]
node_google["Google OAuth"]

node_client -->|"submits requests"| node_notify_api
node_notify_api -->|"delegates"| node_notify_service
node_notify_service -->|"saves and queries"| node_notification_repo
node_notification_repo -->|"reads and writes"| node_notification_db
node_notify_service -->|"checks duplicates"| node_idempotency
node_idempotency -->|"checks keys"| node_redis
node_notification_db -->|"persists"| node_postgres
node_notify_service -->|"publishes after commit"| node_kafka_producer
node_kafka_producer -->|"publishes event"| node_kafka
node_kafka -->|"dispatches event"| node_event_consumer
node_event_consumer -->|"hands off event"| node_engine
node_engine -->|"loads and updates"| node_notification_repo
node_engine -->|"selects by channel"| node_email_sender
node_engine -->|"selects by channel"| node_sms_sender
node_email_sender -.->|"uses provider"| node_email_provider
node_email_provider -.->|"sends mail"| node_smtp
node_sms_sender -.->|"uses provider"| node_sms_provider
node_sms_provider -.->|"sends SMS"| node_twilio
node_template_api -->|"delegates"| node_template_service
node_template_service -->|"manages templates"| node_template_db
node_notify_service -.->|"renders content"| node_template_renderer
node_template_renderer -.->|"uses active template"| node_template_db
node_auth_api -->|"loads and saves users"| node_users
node_auth_api -->|"creates and rotates"| node_refresh_service
node_refresh_service -->|"reads and revokes"| node_refresh_repo
node_refresh_repo -->|"persists token records"| node_user_db
node_users -->|"persists accounts"| node_user_db
node_google -.->|"authenticates"| node_google_oauth
node_google_oauth -->|"creates refresh token"| node_refresh_service
node_google_oauth -->|"loads or saves user"| node_users

click node_notify_api "https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/notification/controller/NotificationController.java"
click node_notify_service "https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/notification/service/NotificationServiceImpl.java"
click node_notification_db "https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/notification/entity/Notification.java"
click node_notification_repo "https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/notification/repository/NotificationRepository.java"
click node_idempotency "https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/notification/idempotency/RedisIdempotencyService.java"
click node_template_api "https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/template/controller/TemplateController.java"
click node_template_service "https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/template/service/TemplateServiceImpl.java"
click node_template_db "https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/template/entity/NotificationTemplate.java"
click node_template_renderer "https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/template/renderer/TemplateRendererImpl.java"
click node_kafka_producer "https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/messaging/producer/NotificationEventProducer.java"
click node_event_consumer "https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/messaging/consumer/NotificationEventConsumer.java"
click node_engine "https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/engine/NotificationEngine.java"
click node_email_sender "https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/notification/email/EmailNotificationSender.java"
click node_email_provider "https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/notification/email/EmailProvider.java"
click node_sms_sender "https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/notification/sms/SmsNotificationSender.java"
click node_sms_provider "https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/notification/sms/SmsProvider.java"
click node_auth_api "https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/security/controller/AuthController.java"
click node_refresh_service "https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/security/service/RefreshTokenService.java"
click node_refresh_repo "https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/security/repository/RefreshTokenRepository.java"
click node_users "https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/security/repository/UserRepository.java"
click node_user_db "https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/security/entity/AppUser.java"
click node_google_oauth "https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/security/OAuth/GoogleOAuth2SuccessHandler.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_notify_api,node_notify_service,node_client toneBlue
class node_kafka_producer,node_event_consumer,node_engine,node_email_sender,node_email_provider,node_sms_sender,node_sms_provider,node_redis,node_postgres toneAmber
class node_template_api,node_template_service,node_template_db,node_template_renderer toneMint
class node_auth_api,node_refresh_service,node_refresh_repo,node_users,node_google_oauth toneRose
class node_notification_db,node_notification_repo,node_idempotency,node_user_db,node_kafka,node_smtp,node_twilio,node_google toneIndigo
```

## Components

### Notification API

- [Notification Endpoints](https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/notification/controller/NotificationController.java): `src/main/java/com/notifyhub/notification/controller/NotificationController.java`
- [Request and History Service](https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/notification/service/NotificationServiceImpl.java): `src/main/java/com/notifyhub/notification/service/NotificationServiceImpl.java`

### Async Delivery

- [Event Producer](https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/messaging/producer/NotificationEventProducer.java): `src/main/java/com/notifyhub/messaging/producer/NotificationEventProducer.java`
- [Event Consumer](https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/messaging/consumer/NotificationEventConsumer.java): `src/main/java/com/notifyhub/messaging/consumer/NotificationEventConsumer.java`
- [Notification Engine](https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/engine/NotificationEngine.java): `src/main/java/com/notifyhub/engine/NotificationEngine.java`
- [Email Sender](https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/notification/email/EmailNotificationSender.java): `src/main/java/com/notifyhub/notification/email/EmailNotificationSender.java`
- [Email Provider](https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/notification/email/EmailProvider.java): `src/main/java/com/notifyhub/notification/email/EmailProvider.java`
- [SMS Sender](https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/notification/sms/SmsNotificationSender.java): `src/main/java/com/notifyhub/notification/sms/SmsNotificationSender.java`
- [SMS Provider](https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/notification/sms/SmsProvider.java): `src/main/java/com/notifyhub/notification/sms/SmsProvider.java`

### Template Management

- [Template Endpoints](https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/template/controller/TemplateController.java): `src/main/java/com/notifyhub/template/controller/TemplateController.java`
- [Template Service](https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/template/service/TemplateServiceImpl.java): `src/main/java/com/notifyhub/template/service/TemplateServiceImpl.java`
- [Templates](https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/template/entity/NotificationTemplate.java): `src/main/java/com/notifyhub/template/entity/NotificationTemplate.java`
- [Template Renderer](https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/template/renderer/TemplateRendererImpl.java): `src/main/java/com/notifyhub/template/renderer/TemplateRendererImpl.java`

### Authentication

- [Authentication Endpoints](https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/security/controller/AuthController.java): `src/main/java/com/notifyhub/security/controller/AuthController.java`
- [Refresh Token Service](https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/security/service/RefreshTokenService.java): `src/main/java/com/notifyhub/security/service/RefreshTokenService.java`
- [Refresh Token Repository](https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/security/repository/RefreshTokenRepository.java): `src/main/java/com/notifyhub/security/repository/RefreshTokenRepository.java`
- [User Repository](https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/security/repository/UserRepository.java): `src/main/java/com/notifyhub/security/repository/UserRepository.java`
- [Google OAuth Handler](https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/security/OAuth/GoogleOAuth2SuccessHandler.java): `src/main/java/com/notifyhub/security/OAuth/GoogleOAuth2SuccessHandler.java`

### Persistence and Idempotency

- [Notifications](https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/notification/entity/Notification.java): `src/main/java/com/notifyhub/notification/entity/Notification.java`
- [Notification Repository](https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/notification/repository/NotificationRepository.java): `src/main/java/com/notifyhub/notification/repository/NotificationRepository.java`
- [Redis Idempotency](https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/notification/idempotency/RedisIdempotencyService.java): `src/main/java/com/notifyhub/notification/idempotency/RedisIdempotencyService.java`
- [Users and Tokens](https://github.com/yhoney-72/notifyhub/blob/main/src/main/java/com/notifyhub/security/entity/AppUser.java): `src/main/java/com/notifyhub/security/entity/AppUser.java`

### Other components

- **Backend Client**
- **Redis**
- **PostgreSQL**
- **Kafka Topics**
- **SMTP Service**
- **Twilio**
- **Google OAuth**

## Connections

- Backend Client → Notification Endpoints: submits requests
- Notification Endpoints → Request and History Service: delegates (evidence: `src/main/java/com/notifyhub/notification/controller/NotificationController.java`)
- Request and History Service → Notification Repository: saves and queries (evidence: `src/main/java/com/notifyhub/notification/service/NotificationServiceImpl.java`)
- Notification Repository → Notifications: reads and writes (evidence: `src/main/java/com/notifyhub/notification/repository/NotificationRepository.java`)
- Request and History Service → Redis Idempotency: checks duplicates (evidence: `src/main/java/com/notifyhub/notification/service/NotificationServiceImpl.java`)
- Redis Idempotency → Redis: checks keys
- Notifications → PostgreSQL: persists
- Request and History Service → Event Producer: publishes after commit (evidence: `src/main/java/com/notifyhub/notification/service/NotificationServiceImpl.java`)
- Event Producer → Kafka Topics: publishes event
- Kafka Topics → Event Consumer: dispatches event
- Event Consumer → Notification Engine: hands off event (evidence: `src/main/java/com/notifyhub/messaging/consumer/NotificationEventConsumer.java`)
- Notification Engine → Notification Repository: loads and updates (evidence: `src/main/java/com/notifyhub/engine/NotificationEngine.java`)
- Notification Engine → Email Sender: selects by channel (evidence: `src/main/java/com/notifyhub/engine/NotificationEngine.java`)
- Notification Engine → SMS Sender: selects by channel (evidence: `src/main/java/com/notifyhub/engine/NotificationEngine.java`)
- Email Sender → Email Provider: uses provider (evidence: `src/main/java/com/notifyhub/notification/email/EmailNotificationSender.java`)
- Email Provider → SMTP Service: sends mail
- SMS Sender → SMS Provider: uses provider
- SMS Provider → Twilio: sends SMS
- Template Endpoints → Template Service: delegates (evidence: `src/main/java/com/notifyhub/template/controller/TemplateController.java`)
- Template Service → Templates: manages templates (evidence: `src/main/java/com/notifyhub/template/service/TemplateServiceImpl.java`)
- Request and History Service → Template Renderer: renders content
- Template Renderer → Templates: uses active template
- Authentication Endpoints → User Repository: loads and saves users (evidence: `src/main/java/com/notifyhub/security/controller/AuthController.java`)
- Authentication Endpoints → Refresh Token Service: creates and rotates (evidence: `src/main/java/com/notifyhub/security/controller/AuthController.java`)
- Refresh Token Service → Refresh Token Repository: reads and revokes (evidence: `src/main/java/com/notifyhub/security/service/RefreshTokenService.java`)
- Refresh Token Repository → Users and Tokens: persists token records (evidence: `src/main/java/com/notifyhub/security/repository/RefreshTokenRepository.java`)
- User Repository → Users and Tokens: persists accounts (evidence: `src/main/java/com/notifyhub/security/repository/UserRepository.java`)
- Google OAuth → Google OAuth Handler: authenticates
- Google OAuth Handler → Refresh Token Service: creates refresh token (evidence: `src/main/java/com/notifyhub/security/OAuth/GoogleOAuth2SuccessHandler.java`)
- Google OAuth Handler → User Repository: loads or saves user (evidence: `src/main/java/com/notifyhub/security/OAuth/GoogleOAuth2SuccessHandler.java`)
