# rushi055/notifyhub architecture

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

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

## Overview

1. **Overall shape**
   - NotifyHub is a single Node.js codebase split into multiple independently runnable processes: an Express API server, a Kafka consumer, BullMQ workers, and a browser frontend.
   - The architecture is event-driven: the API accepts requests quickly, persists state in PostgreSQL, then hands off delivery work asynchronously.

2. **HTTP/API boundary**
   - `src/server.js` is the main runtime entrypoint for the backend.
   - `src/routes/` defines the API surface: auth, notifications, notify, and preferences.
   - Requests are protected by `src/middleware/auth.js` and throttled by `src/middleware/rateLimiter.js`, so the API is the enforcement point for identity and per-user request volume.

3. **Business logic layer**
   - `src/services/` contains the core use-case logic:
     - `authService.js` for registration/login and JWT-related flows
     - `notificationService.js` for creation, persistence, dispatch, and status updates
     - `preferenceService.js` for user delivery settings and caching behavior
   - This layer is the main boundary between HTTP handlers and infrastructure dependencies.

4. **Persistent storage**
   - PostgreSQL is the system of record.
   - `src/db/postgres.js` is the database access layer.
   - Migrations in `src/db/migrations/` create three core tables:
     - users
     - notifications
     - user_preferences
   - Notification delivery state is persisted here, so delivery is durable even when downstream processing is delayed.

5. **Async event pipeline**
   - `src/kafka/producer.js`, `consumer.js`, and `client.js` implement the Kafka boundary.
   - The API publishes notification events to Kafka after inserting them into PostgreSQL.
   - Kafka is the decoupling layer between request handling and delivery execution, allowing separate scaling of ingestion and processing.

6. **Channel routing and job queues**
   - The Kafka consumer routes events into BullMQ queues defined in `src/queues/`.
   - There are two delivery queues:
     - `emailQueue.js`
     - `inappQueue.js`
   - This is the point where a single notification fan-outs into channel-specific work.

7. **Delivery workers**
   - `src/queues/emailWorker.js` handles email delivery, using Nodemailer and user email data from the database.
   - `src/queues/inappWorker.js` handles real-time in-app delivery.
   - Workers are separate processes, so retries, concurrency, and failure handling are isolated from the API.

8. **Redis usage**
   - `src/redis/client.js` supports low-latency shared state.
   - Redis is used for preference caching, rate limiting counters, and WebSocket/session mapping for online users.
   - It is not the primary data store; it supports fast coordination across processes.

9. **Real-time WebSocket path**
   - `src/websocket/socketHandler.js` manages Socket.io connections and the live in-app notification channel.
   - The in-app worker checks Redis for connection state, then emits to connected clients when possible.
   - This means real-time delivery depends on a shared connection registry, not on the API process itself.

10. **Authentication and preferences flow**
    - `src/routes/auth.js` and `src/services/authService.js` cover user signup/login.
    - `src/routes/preferences.js` and `src/services/preferenceService.js` manage per-user channel toggles and notification delivery settings.
    - Preference data is persisted in PostgreSQL and cached in Redis for fast lookup during dispatch.

11. **Operations and observability**
    - `src/dashboard/bullboard.js` mounts Bull Board at `/dashboard` to inspect queue health, retries, and failures.
    - `docker-compose.yml` provides the supporting infrastructure: PostgreSQL, Redis, Kafka, and Zookeeper.
    - The repo is designed for local reproducibility and for running each backend component independently in production-like deployments.

12. **Frontend and test surfaces**
    - `frontend/` contains a browser-based UI (`app.js`, HTML pages, CSS) for login, sending notifications, viewing history, and monitoring WebSocket activity.
    - `public/test.html` is a lightweight test page for WebSocket verification.
    - These frontend assets are separate from the backend API and consume it over HTTP plus WebSocket connections.

13. **End-to-end notification lifecycle**
    - A client posts to `/api/notify`.
    - The API validates, rate-limits, and stores the notification as `pending`.
    - The notification is published to Kafka.
    - The consumer reads it, checks preferences, and enqueues email and/or in-app jobs.
    - Workers deliver the notification and update status to `delivered` or `failed`.
    - Online users receive the in-app event immediately; offline users can retrieve it later from PostgreSQL.

14. **Architecture diagram boundaries to show**
    - Frontend/browser clients
    - Express API and middleware
    - PostgreSQL as durable storage
    - Redis as shared low-latency state
    - Kafka as the async event backbone
    - BullMQ as channel-specific job processing
    - Email worker and in-app/WebSocket worker as separate delivery subsystems

Main entry points: [`src/server.js`](https://github.com/rushi055/notifyhub/blob/main/src/server.js) (API Server), [`src/services`](https://github.com/rushi055/notifyhub/tree/main/src/services) (Services), [`src/kafka/consumer.js`](https://github.com/rushi055/notifyhub/blob/main/src/kafka/consumer.js) (Consumer), [`src/queues/inappWorker.js`](https://github.com/rushi055/notifyhub/blob/main/src/queues/inappWorker.js) (In-App Worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Clients"]
  node_frontend_app["Frontend UI<br/>browser app<br/>[app.js]"]
  node_public_test["Test Page<br/>ws test<br/>[test.html]"]
end

subgraph group_backend["Backend"]
  node_server["API Server<br/>express runtime<br/>[server.js]"]
  node_routes["Routes"]
  node_middleware["Middleware<br/>policy layer"]
  node_services["Services<br/>use cases"]
  node_dashboard["Bull Board<br/>ops dashboard<br/>[bullboard.js]"]
end

subgraph group_data["State"]
  node_postgres[("PostgreSQL<br/>primary db<br/>[postgres.js]")]
  node_redis[("Redis<br/>shared cache<br/>[client.js]")]
end

subgraph group_async["Async"]
  node_kafka_client["Kafka Client<br/>event bus<br/>[client.js]"]
  node_kafka_producer["Producer<br/>event publish<br/>[producer.js]"]
  node_kafka_consumer["Consumer<br/>event route<br/>[consumer.js]"]
  node_email_queue["Email Queue<br/>bullmq queue<br/>[emailQueue.js]"]
  node_inapp_queue["In-App Queue<br/>bullmq queue<br/>[inappQueue.js]"]
  node_email_worker["Email Worker<br/>delivery worker<br/>[emailWorker.js]"]
  node_inapp_worker["In-App Worker<br/>delivery worker<br/>[inappWorker.js]"]
  node_socket_handler["Socket Handler<br/>socket.io<br/>[socketHandler.js]"]
end

node_frontend_app -->|"HTTP API"| node_server
node_frontend_app -->|"WebSocket"| node_socket_handler
node_public_test -->|"WebSocket test"| node_socket_handler
node_server -->|"enforces"| node_middleware
node_server -->|"mounts"| node_routes
node_routes -->|"calls"| node_services
node_services -->|"persists"| node_postgres
node_services -->|"caches"| node_redis
node_services -->|"publishes"| node_kafka_producer
node_kafka_producer -->|"uses"| node_kafka_client
node_kafka_consumer -->|"subscribes"| node_kafka_client
node_kafka_consumer -->|"enqueues"| node_email_queue
node_kafka_consumer -->|"enqueues"| node_inapp_queue
node_email_worker -->|"consumes"| node_email_queue
node_email_worker -->|"reads users"| node_postgres
node_inapp_worker -->|"consumes"| node_inapp_queue
node_inapp_worker -->|"checks presence"| node_redis
node_inapp_worker -->|"emits"| node_socket_handler
node_dashboard -->|"inspects"| node_email_queue
node_dashboard -->|"inspects"| node_inapp_queue
node_server -->|"reads/writes"| node_postgres
node_server -->|"rate limits"| node_redis

click node_frontend_app "https://github.com/rushi055/notifyhub/blob/main/frontend/app.js"
click node_public_test "https://github.com/rushi055/notifyhub/blob/main/public/test.html"
click node_server "https://github.com/rushi055/notifyhub/blob/main/src/server.js"
click node_routes "https://github.com/rushi055/notifyhub/tree/main/src/routes"
click node_middleware "https://github.com/rushi055/notifyhub/tree/main/src/middleware"
click node_services "https://github.com/rushi055/notifyhub/tree/main/src/services"
click node_dashboard "https://github.com/rushi055/notifyhub/blob/main/src/dashboard/bullboard.js"
click node_postgres "https://github.com/rushi055/notifyhub/blob/main/src/db/postgres.js"
click node_redis "https://github.com/rushi055/notifyhub/blob/main/src/redis/client.js"
click node_kafka_client "https://github.com/rushi055/notifyhub/blob/main/src/kafka/client.js"
click node_kafka_producer "https://github.com/rushi055/notifyhub/blob/main/src/kafka/producer.js"
click node_kafka_consumer "https://github.com/rushi055/notifyhub/blob/main/src/kafka/consumer.js"
click node_email_queue "https://github.com/rushi055/notifyhub/blob/main/src/queues/emailQueue.js"
click node_inapp_queue "https://github.com/rushi055/notifyhub/blob/main/src/queues/inappQueue.js"
click node_email_worker "https://github.com/rushi055/notifyhub/blob/main/src/queues/emailWorker.js"
click node_inapp_worker "https://github.com/rushi055/notifyhub/blob/main/src/queues/inappWorker.js"
click node_socket_handler "https://github.com/rushi055/notifyhub/blob/main/src/websocket/socketHandler.js"

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_frontend_app,node_public_test toneBlue
class node_server,node_routes,node_middleware,node_services,node_dashboard toneAmber
class node_postgres,node_redis toneMint
class node_kafka_client,node_kafka_producer,node_kafka_consumer,node_email_queue,node_inapp_queue,node_email_worker,node_inapp_worker,node_socket_handler toneRose
```

## Components

### Clients

Browser and test entry points that consume the system.

- [Frontend UI](https://github.com/rushi055/notifyhub/blob/main/frontend/app.js): browser app · Browser-based UI for auth, sending notifications, history, and monitoring. · `frontend/app.js`
- [Test Page](https://github.com/rushi055/notifyhub/blob/main/public/test.html): ws test · Lightweight page for WebSocket verification. · `public/test.html`

### Backend

Express API, middleware, services, and supporting runtime entrypoints.

- [API Server](https://github.com/rushi055/notifyhub/blob/main/src/server.js): express runtime · Main backend entrypoint that hosts the HTTP API and mounts middleware/routes. · `src/server.js`
- [Routes](https://github.com/rushi055/notifyhub/tree/main/src/routes): http routes · API surface for auth, notifications, notify, and preferences. · `src/routes`
- [Middleware](https://github.com/rushi055/notifyhub/tree/main/src/middleware): policy layer · Authentication and rate limiting for request enforcement. · `src/middleware`
- [Services](https://github.com/rushi055/notifyhub/tree/main/src/services): use cases · Core business logic for auth, notifications, and preferences. · `src/services`
- [Bull Board](https://github.com/rushi055/notifyhub/blob/main/src/dashboard/bullboard.js): ops dashboard · Queue inspection UI mounted for retries, failures, and health. · `src/dashboard/bullboard.js`

### State

Durable and shared infrastructure used by backend processes.

- [PostgreSQL](https://github.com/rushi055/notifyhub/blob/main/src/db/postgres.js): primary db · System of record for users, notifications, and preferences. · `src/db/postgres.js`
- [Redis](https://github.com/rushi055/notifyhub/blob/main/src/redis/client.js): shared cache · Low-latency state for preference caching, rate limiting, and socket presence. · `src/redis/client.js`

### Async

Kafka, queues, and workers that process notification delivery.

- [Kafka Client](https://github.com/rushi055/notifyhub/blob/main/src/kafka/client.js): event bus · Kafka boundary used to publish and consume notification events. · `src/kafka/client.js`
- [Producer](https://github.com/rushi055/notifyhub/blob/main/src/kafka/producer.js): event publish · Publishes notification events after persistence. · `src/kafka/producer.js`
- [Consumer](https://github.com/rushi055/notifyhub/blob/main/src/kafka/consumer.js): event route · Reads notification events and routes them into delivery work. · `src/kafka/consumer.js`
- [Email Queue](https://github.com/rushi055/notifyhub/blob/main/src/queues/emailQueue.js): bullmq queue · Channel-specific queue for email delivery jobs. · `src/queues/emailQueue.js`
- [In-App Queue](https://github.com/rushi055/notifyhub/blob/main/src/queues/inappQueue.js): bullmq queue · Channel-specific queue for in-app delivery jobs. · `src/queues/inappQueue.js`
- [Email Worker](https://github.com/rushi055/notifyhub/blob/main/src/queues/emailWorker.js): delivery worker · Processes email jobs and sends notifications by email. · `src/queues/emailWorker.js`
- [In-App Worker](https://github.com/rushi055/notifyhub/blob/main/src/queues/inappWorker.js): delivery worker · Processes real-time in-app jobs and emits to connected clients. · `src/queues/inappWorker.js`
- [Socket Handler](https://github.com/rushi055/notifyhub/blob/main/src/websocket/socketHandler.js): socket.io · Manages live connections and the in-app notification channel. · `src/websocket/socketHandler.js`

## Connections

- Frontend UI → API Server: HTTP API · Browser UI talks to the backend over HTTP.
- Frontend UI → Socket Handler: WebSocket · Frontend subscribes to live notification events.
- Test Page → Socket Handler: WebSocket test · Test page verifies socket connectivity.
- API Server → Middleware: enforces · Requests pass through auth and rate limiting.
- API Server → Routes: mounts · Server exposes the API routes.
- Routes → Services: calls · Route handlers delegate to business logic.
- Services → PostgreSQL: persists · Services read and write durable application state.
- Services → Redis: caches · Preferences and shared counters use Redis.
- Services → Producer: publishes · Notification creation is handed off as an event.
- Producer → Kafka Client: uses · Producer sends events through the Kafka boundary.
- Consumer → Kafka Client: subscribes · Consumer receives events from Kafka.
- Consumer → Email Queue: enqueues · Email delivery work is queued separately.
- Consumer → In-App Queue: enqueues · In-app delivery work is queued separately.
- Email Worker → Email Queue: consumes · Worker processes email jobs from the queue.
- Email Worker → PostgreSQL: reads users · Worker resolves recipient and delivery data.
- In-App Worker → In-App Queue: consumes · Worker processes in-app jobs from the queue.
- In-App Worker → Redis: checks presence · Worker uses shared connection state for online users.
- In-App Worker → Socket Handler: emits · Worker pushes live notifications to connected clients.
- Bull Board → Email Queue: inspects · Dashboard surfaces queue health and failures.
- Bull Board → In-App Queue: inspects · Dashboard surfaces queue health and failures.
- API Server → PostgreSQL: reads/writes · API persists notification and preference state.
- API Server → Redis: rate limits · Shared counters support throttling.
