# tiwarikrishna14/notifyhub architecture

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

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

## Overview

NotifyHub is a multi-tenant notification API: tenants obtain API keys, register recipient devices, and submit idempotent notification requests. The request is durably recorded with an outbox event, then processed asynchronously into per-channel delivery work and sent through providers. PostgreSQL is the durable store; Kafka carries work and Redis supports rate limiting and cross-instance WebSocket presence. The README documents publisher, listener, retry, and realtime behavior that the sampled source does not fully expose, so those relationships are cited to the README.

Main entry points: [`src/main/java/com/notifyhub/delivery/NotificationOrchestrator.java`](https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/delivery/NotificationOrchestrator.java) (Delivery orchestration), [`src/main/java/com/notifyhub/notification/NotificationService.java`](https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/notification/NotificationService.java) (Notification intake and status), [`src/main/java/com/notifyhub/outbox/OutboxRepository.java`](https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/outbox/OutboxRepository.java) (Outbox records), [`src/main/java/com/notifyhub/tenant/TenantAdminController.java`](https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/tenant/TenantAdminController.java) (Tenant administration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_tenant_access["Tenant access"]
  node_tenant_admin["Tenant administration"]
  node_tenant_store[("Tenant records")]
  node_api_key_service["API key service<br/>[ApiKeyService.java]"]
  node_api_key_store[("API key records")]
  node_auth_filter["API key authentication"]
  node_rate_limit["Tenant rate limiting"]
end

subgraph group_request_state["Request and state"]
  node_device_api["Device API"]
  node_device_service["Device management<br/>[DeviceService.java]"]
  node_device_store[("Device records")]
  node_notification_api["Notification API"]
  node_notification_service["Notification intake and status"]
  node_notification_store[("Notification records")]
  node_delivery_store[("Delivery records")]
  node_outbox_store[("Outbox records")]
  node_postgres[("PostgreSQL")]
end

subgraph group_async_delivery["Async delivery"]
  node_outbox_publisher["Outbox publisher"]
  node_kafka["Kafka"]
  node_listeners["Notification listeners"]
  node_orchestrator["Delivery orchestration"]
  node_processed_store[("Processed event records")]
  node_processor["Delivery processing and retries"]
end

subgraph group_provider_realtime["Providers and realtime"]
  node_registry["Provider registry"]
  node_push_provider["Push provider"]
  node_realtime_provider["WebSocket provider"]
  node_realtime_broker["Realtime broker"]
  node_ws_handler["WebSocket sessions"]
  node_connection_registry["Connection and presence registry"]
end

subgraph group_platform_services["Platform services"]
  node_redis[("Redis")]
end

node_client(("API client"))
node_admin(("Tenant administrator"))

node_admin -->|"creates tenant"| node_tenant_admin
node_tenant_admin -->|"stores tenant"| node_tenant_store
node_tenant_admin -->|"creates key"| node_api_key_service
node_api_key_service -->|"stores and verifies"| node_api_key_store
node_client -->|"presents API key"| node_auth_filter
node_auth_filter -->|"authenticates"| node_api_key_service
node_auth_filter -.->|"passes tenant identity"| node_rate_limit
node_client -->|"registers device"| node_device_api
node_device_api -->|"manages devices"| node_device_service
node_device_service -->|"reads and writes"| node_device_store
node_client -->|"submits request"| node_notification_api
node_notification_api -->|"accepts and queries"| node_notification_service
node_notification_service -->|"checks and saves"| node_notification_store
node_notification_service -->|"records request event"| node_outbox_store
node_notification_service -->|"loads delivery status"| node_delivery_store
node_notification_store -->|"persists"| node_postgres
node_delivery_store -->|"persists"| node_postgres
node_outbox_store -->|"persists"| node_postgres
node_outbox_publisher -->|"claims pending events"| node_outbox_store
node_outbox_publisher -->|"publishes after acknowledgement"| node_kafka
node_kafka -->|"dispatches work"| node_listeners
node_listeners -->|"delegates request"| node_orchestrator
node_orchestrator -->|"deduplicates events"| node_processed_store
node_orchestrator -->|"locks notification"| node_notification_store
node_orchestrator -->|"finds active devices"| node_device_service
node_orchestrator -->|"creates work items"| node_delivery_store
node_orchestrator -->|"records delivery events"| node_outbox_store
node_kafka -.->|"dispatches delivery work"| node_processor
node_processor -.->|"selects provider"| node_registry
node_registry -.->|"routes push"| node_push_provider
node_registry -.->|"routes realtime"| node_realtime_provider
node_realtime_provider -->|"sends realtime"| node_realtime_broker
node_realtime_broker -->|"routes to session"| node_connection_registry
node_ws_handler -->|"registers sessions"| node_connection_registry
node_connection_registry -->|"tracks distributed presence"| node_redis
node_realtime_broker -->|"broadcasts pub/sub"| node_redis
node_rate_limit -->|"counts tenant requests"| node_redis

click node_tenant_admin "https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/tenant/TenantAdminController.java"
click node_tenant_store "https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/tenant/TenantRepository.java"
click node_api_key_service "https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/auth/ApiKeyService.java"
click node_api_key_store "https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/auth/ApiKeyRepository.java"
click node_auth_filter "https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/security/ApiKeyAuthenticationFilter.java"
click node_rate_limit "https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/security/TenantRateLimitFilter.java"
click node_device_api "https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/device/DeviceController.java"
click node_device_service "https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/device/DeviceService.java"
click node_device_store "https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/device/DeviceRepository.java"
click node_notification_api "https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/notification/NotificationController.java"
click node_notification_service "https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/notification/NotificationService.java"
click node_notification_store "https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/notification/NotificationRepository.java"
click node_delivery_store "https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/delivery/DeliveryRepository.java"
click node_outbox_store "https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/outbox/OutboxRepository.java"
click node_outbox_publisher "https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/outbox/OutboxPublisher.java"
click node_listeners "https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/messaging/NotificationListeners.java"
click node_orchestrator "https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/delivery/NotificationOrchestrator.java"
click node_processed_store "https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/messaging/ProcessedEventRepository.java"
click node_processor "https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/delivery/DeliveryProcessor.java"
click node_registry "https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/provider/ProviderRegistry.java"
click node_push_provider "https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/provider/push/MockPushProvider.java"
click node_realtime_provider "https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/provider/websocket/WebSocketNotificationProvider.java"
click node_realtime_broker "https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/realtime/RealtimeBroker.java"
click node_ws_handler "https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/realtime/RealtimeWebSocketHandler.java"
click node_connection_registry "https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/realtime/ConnectionRegistry.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_tenant_admin,node_tenant_store,node_api_key_service,node_api_key_store,node_auth_filter,node_rate_limit,node_client toneBlue
class node_device_api,node_device_service,node_device_store,node_notification_api,node_notification_service,node_notification_store,node_delivery_store,node_outbox_store,node_postgres toneAmber
class node_outbox_publisher,node_kafka,node_listeners,node_orchestrator,node_processed_store,node_processor toneMint
class node_registry,node_push_provider,node_realtime_provider,node_realtime_broker,node_ws_handler,node_connection_registry toneRose
class node_redis,node_admin toneIndigo
```

## Components

### Tenant access

- [Tenant administration](https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/tenant/TenantAdminController.java): `src/main/java/com/notifyhub/tenant/TenantAdminController.java`
- [Tenant records](https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/tenant/TenantRepository.java): `src/main/java/com/notifyhub/tenant/TenantRepository.java`
- [API key service](https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/auth/ApiKeyService.java): `src/main/java/com/notifyhub/auth/ApiKeyService.java`
- [API key records](https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/auth/ApiKeyRepository.java): `src/main/java/com/notifyhub/auth/ApiKeyRepository.java`
- [API key authentication](https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/security/ApiKeyAuthenticationFilter.java): `src/main/java/com/notifyhub/security/ApiKeyAuthenticationFilter.java`
- [Tenant rate limiting](https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/security/TenantRateLimitFilter.java): `src/main/java/com/notifyhub/security/TenantRateLimitFilter.java`

### Request and state

- [Device API](https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/device/DeviceController.java): `src/main/java/com/notifyhub/device/DeviceController.java`
- [Device management](https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/device/DeviceService.java): `src/main/java/com/notifyhub/device/DeviceService.java`
- [Device records](https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/device/DeviceRepository.java): `src/main/java/com/notifyhub/device/DeviceRepository.java`
- [Notification API](https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/notification/NotificationController.java): `src/main/java/com/notifyhub/notification/NotificationController.java`
- [Notification intake and status](https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/notification/NotificationService.java): `src/main/java/com/notifyhub/notification/NotificationService.java`
- [Notification records](https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/notification/NotificationRepository.java): `src/main/java/com/notifyhub/notification/NotificationRepository.java`
- [Delivery records](https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/delivery/DeliveryRepository.java): `src/main/java/com/notifyhub/delivery/DeliveryRepository.java`
- [Outbox records](https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/outbox/OutboxRepository.java): `src/main/java/com/notifyhub/outbox/OutboxRepository.java`
- **PostgreSQL**

### Async delivery

- [Outbox publisher](https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/outbox/OutboxPublisher.java): `src/main/java/com/notifyhub/outbox/OutboxPublisher.java`
- **Kafka**
- [Notification listeners](https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/messaging/NotificationListeners.java): `src/main/java/com/notifyhub/messaging/NotificationListeners.java`
- [Delivery orchestration](https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/delivery/NotificationOrchestrator.java): `src/main/java/com/notifyhub/delivery/NotificationOrchestrator.java`
- [Processed event records](https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/messaging/ProcessedEventRepository.java): `src/main/java/com/notifyhub/messaging/ProcessedEventRepository.java`
- [Delivery processing and retries](https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/delivery/DeliveryProcessor.java): `src/main/java/com/notifyhub/delivery/DeliveryProcessor.java`

### Providers and realtime

- [Provider registry](https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/provider/ProviderRegistry.java): `src/main/java/com/notifyhub/provider/ProviderRegistry.java`
- [Push provider](https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/provider/push/MockPushProvider.java): `src/main/java/com/notifyhub/provider/push/MockPushProvider.java`
- [WebSocket provider](https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/provider/websocket/WebSocketNotificationProvider.java): `src/main/java/com/notifyhub/provider/websocket/WebSocketNotificationProvider.java`
- [Realtime broker](https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/realtime/RealtimeBroker.java): `src/main/java/com/notifyhub/realtime/RealtimeBroker.java`
- [WebSocket sessions](https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/realtime/RealtimeWebSocketHandler.java): `src/main/java/com/notifyhub/realtime/RealtimeWebSocketHandler.java`
- [Connection and presence registry](https://github.com/tiwarikrishna14/notifyhub/blob/master/src/main/java/com/notifyhub/realtime/ConnectionRegistry.java): `src/main/java/com/notifyhub/realtime/ConnectionRegistry.java`

### Platform services

- **Redis**

### Other components

- **API client**
- **Tenant administrator**

## Connections

- Tenant administrator → Tenant administration: creates tenant
- Tenant administration → Tenant records: stores tenant (evidence: `src/main/java/com/notifyhub/tenant/TenantAdminController.java`)
- Tenant administration → API key service: creates key (evidence: `src/main/java/com/notifyhub/tenant/TenantAdminController.java`)
- API key service → API key records: stores and verifies (evidence: `src/main/java/com/notifyhub/auth/ApiKeyService.java`)
- API client → API key authentication: presents API key
- API key authentication → API key service: authenticates (evidence: `src/main/java/com/notifyhub/security/ApiKeyAuthenticationFilter.java`)
- API key authentication → Tenant rate limiting: passes tenant identity
- API client → Device API: registers device
- Device API → Device management: manages devices (evidence: `src/main/java/com/notifyhub/device/DeviceController.java`)
- Device management → Device records: reads and writes (evidence: `src/main/java/com/notifyhub/device/DeviceService.java`)
- API client → Notification API: submits request
- Notification API → Notification intake and status: accepts and queries (evidence: `src/main/java/com/notifyhub/notification/NotificationController.java`)
- Notification intake and status → Notification records: checks and saves (evidence: `src/main/java/com/notifyhub/notification/NotificationService.java`)
- Notification intake and status → Outbox records: records request event (evidence: `src/main/java/com/notifyhub/notification/NotificationService.java`)
- Notification intake and status → Delivery records: loads delivery status (evidence: `src/main/java/com/notifyhub/notification/NotificationService.java`)
- Notification records → PostgreSQL: persists
- Delivery records → PostgreSQL: persists
- Outbox records → PostgreSQL: persists
- Outbox publisher → Outbox records: claims pending events
- Outbox publisher → Kafka: publishes after acknowledgement
- Kafka → Notification listeners: dispatches work
- Notification listeners → Delivery orchestration: delegates request
- Delivery orchestration → Processed event records: deduplicates events (evidence: `src/main/java/com/notifyhub/delivery/NotificationOrchestrator.java`)
- Delivery orchestration → Notification records: locks notification (evidence: `src/main/java/com/notifyhub/delivery/NotificationOrchestrator.java`)
- Delivery orchestration → Device management: finds active devices (evidence: `src/main/java/com/notifyhub/delivery/NotificationOrchestrator.java`)
- Delivery orchestration → Delivery records: creates work items (evidence: `src/main/java/com/notifyhub/delivery/NotificationOrchestrator.java`)
- Delivery orchestration → Outbox records: records delivery events (evidence: `src/main/java/com/notifyhub/delivery/NotificationOrchestrator.java`)
- Kafka → Delivery processing and retries: dispatches delivery work
- Delivery processing and retries → Provider registry: selects provider
- Provider registry → Push provider: routes push
- Provider registry → WebSocket provider: routes realtime
- WebSocket provider → Realtime broker: sends realtime (evidence: `src/main/java/com/notifyhub/provider/websocket/WebSocketNotificationProvider.java`)
- Realtime broker → Connection and presence registry: routes to session (evidence: `src/main/java/com/notifyhub/realtime/RealtimeBroker.java`)
- WebSocket sessions → Connection and presence registry: registers sessions (evidence: `src/main/java/com/notifyhub/realtime/RealtimeWebSocketHandler.java`)
- Connection and presence registry → Redis: tracks distributed presence
- Realtime broker → Redis: broadcasts pub/sub
- Tenant rate limiting → Redis: counts tenant requests
