# priyansh00soni/nexus architecture

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

- Interactive diagram: https://gitdiagram.com/priyansh00soni/nexus
- Repository: https://github.com/priyansh00soni/nexus

## Overview

Nexus is a multi-tenant notification delivery API. Clients register tenants, then submit authenticated, validated and deduplicated notification requests; the service records and enqueues work, returning before channel delivery. Email, in-app and webhook workers process jobs with retries and update delivery state. Templates, notification lookup, tenant rate limits, and health, queue and delivery metrics are additional capabilities. Worker and service internals are partly documented rather than sampled, so those links follow README-described behavior; monitoring integrations reflect documented scraping and dashboards.

Main entry points: [`src/monitoring/monitoring.controller.ts`](https://github.com/priyansh00soni/nexus/blob/main/src/monitoring/monitoring.controller.ts) (Monitoring controller), [`src/features/notifications/notification.service.ts`](https://github.com/priyansh00soni/nexus/blob/main/src/features/notifications/notification.service.ts) (Notification service), [`src/config/prismaClient.ts`](https://github.com/priyansh00soni/nexus/blob/main/src/config/prismaClient.ts) (PostgreSQL), [`src/app.ts`](https://github.com/priyansh00soni/nexus/blob/main/src/app.ts) (HTTP application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and tenancy"]
  node_app["HTTP application<br/>[app.ts]"]
  node_tenant_routes["Tenant routes<br/>[tenant.routes.ts]"]
  node_tenant_service["Tenant service<br/>[tenant.service.ts]"]
  node_auth["API-key auth<br/>[auth.middleware.ts]"]
  node_idempotency["Idempotency"]
  node_rate_limit["Tenant rate limit"]
end

subgraph group_content["Templates and notifications"]
  node_notification_routes["Notification routes"]
  node_notification_controller["Notification controller"]
  node_notification_service["Notification service"]
  node_template_routes["Template routes<br/>[template.routes.ts]"]
  node_template_service["Template service"]
end

subgraph group_delivery["Asynchronous delivery"]
  node_email_worker["Email worker<br/>[email.worker.ts]"]
  node_inapp_worker["In-app worker<br/>[inapp.worker.ts]"]
  node_webhook_worker["Webhook worker<br/>[webhook.worker.ts]"]
  node_renderer["Message resolution"]
end

subgraph group_state["State and queues"]
  node_email_queue["Email queue<br/>[email.queue.ts]"]
  node_inapp_queue["In-app queue<br/>[inapp.queue.ts]"]
  node_webhook_queue["Webhook queue<br/>[webhook.queue.ts]"]
  node_postgres[("PostgreSQL<br/>[prismaClient.ts]")]
  node_redis[("Redis<br/>[redis.ts]")]
end

subgraph group_observability["Monitoring"]
  node_monitoring_routes["Monitoring routes"]
  node_monitoring_controller["Monitoring controller"]
  node_metrics["Metrics registry<br/>[metrics.ts]"]
end

node_client(("Business client"))
node_resend["Resend email"]
node_tenant_endpoint["Tenant webhook endpoint"]
node_prometheus["Prometheus"]
node_grafana["Grafana"]

node_client -->|"sends API requests"| node_app
node_app -->|"dispatches"| node_tenant_routes
node_app -->|"dispatches"| node_notification_routes
node_app -->|"dispatches"| node_template_routes
node_app -->|"dispatches"| node_monitoring_routes
node_tenant_routes -->|"invokes"| node_tenant_service
node_tenant_service -->|"creates tenant"| node_postgres
node_notification_routes -->|"authenticates"| node_auth
node_auth -->|"continues request"| node_notification_routes
node_notification_routes -->|"checks duplicate"| node_idempotency
node_idempotency -->|"claims key"| node_redis
node_idempotency -->|"continues request"| node_rate_limit
node_rate_limit -->|"checks tenant limit"| node_redis
node_rate_limit -->|"continues request"| node_notification_controller
node_notification_controller -->|"invokes"| node_notification_service
node_notification_service -->|"records notification"| node_postgres
node_notification_service -->|"enqueues email"| node_email_queue
node_notification_service -->|"enqueues in-app job"| node_inapp_queue
node_notification_service -->|"enqueues webhook"| node_webhook_queue
node_notification_service -->|"returns acceptance"| node_client
node_template_routes -->|"authenticates"| node_auth
node_template_routes -->|"invokes"| node_template_service
node_template_service -->|"manages templates"| node_postgres
node_email_queue -->|"dispatches jobs"| node_email_worker
node_inapp_queue -->|"dispatches jobs"| node_inapp_worker
node_webhook_queue -->|"dispatches jobs"| node_webhook_worker
node_email_worker -->|"resolves content"| node_renderer
node_email_worker -->|"sends email"| node_resend
node_email_worker -->|"records attempts and status"| node_postgres
node_inapp_worker -->|"resolves content"| node_renderer
node_inapp_worker -->|"persists delivery"| node_postgres
node_webhook_worker -->|"resolves content"| node_renderer
node_webhook_worker -->|"posts webhook"| node_tenant_endpoint
node_webhook_worker -->|"records delivery"| node_postgres
node_monitoring_routes -->|"invokes"| node_monitoring_controller
node_monitoring_controller -->|"checks health"| node_postgres
node_monitoring_controller -->|"checks health"| node_redis
node_monitoring_controller -->|"reads counts and failures"| node_email_queue
node_monitoring_controller -->|"reads counts and failures"| node_inapp_queue
node_monitoring_controller -->|"reads counts and failures"| node_webhook_queue
node_monitoring_controller -->|"updates and serves"| node_metrics
node_email_worker -->|"records delivery metrics"| node_metrics
node_inapp_worker -->|"records delivery metrics"| node_metrics
node_webhook_worker -->|"records delivery metrics"| node_metrics
node_prometheus -->|"scrapes"| node_metrics
node_prometheus -->|"feeds dashboards"| node_grafana

click node_app "https://github.com/priyansh00soni/nexus/blob/main/src/app.ts"
click node_tenant_routes "https://github.com/priyansh00soni/nexus/blob/main/src/features/tenants/tenant.routes.ts"
click node_tenant_service "https://github.com/priyansh00soni/nexus/blob/main/src/features/tenants/tenant.service.ts"
click node_auth "https://github.com/priyansh00soni/nexus/blob/main/src/middleware/auth.middleware.ts"
click node_idempotency "https://github.com/priyansh00soni/nexus/blob/main/src/middleware/idempotency.middleware.ts"
click node_rate_limit "https://github.com/priyansh00soni/nexus/blob/main/src/middleware/rateLimit.middleware.ts"
click node_notification_routes "https://github.com/priyansh00soni/nexus/blob/main/src/features/notifications/notification.routes.ts"
click node_notification_controller "https://github.com/priyansh00soni/nexus/blob/main/src/features/notifications/notification.controller.ts"
click node_notification_service "https://github.com/priyansh00soni/nexus/blob/main/src/features/notifications/notification.service.ts"
click node_template_routes "https://github.com/priyansh00soni/nexus/blob/main/src/features/templates/template.routes.ts"
click node_template_service "https://github.com/priyansh00soni/nexus/blob/main/src/features/templates/template.service.ts"
click node_email_queue "https://github.com/priyansh00soni/nexus/blob/main/src/queues/email.queue.ts"
click node_inapp_queue "https://github.com/priyansh00soni/nexus/blob/main/src/queues/inapp.queue.ts"
click node_webhook_queue "https://github.com/priyansh00soni/nexus/blob/main/src/queues/webhook.queue.ts"
click node_email_worker "https://github.com/priyansh00soni/nexus/blob/main/src/workers/email.worker.ts"
click node_inapp_worker "https://github.com/priyansh00soni/nexus/blob/main/src/workers/inapp.worker.ts"
click node_webhook_worker "https://github.com/priyansh00soni/nexus/blob/main/src/workers/webhook.worker.ts"
click node_renderer "https://github.com/priyansh00soni/nexus/blob/main/src/utils/resolveNotificationMessage.ts"
click node_postgres "https://github.com/priyansh00soni/nexus/blob/main/src/config/prismaClient.ts"
click node_redis "https://github.com/priyansh00soni/nexus/blob/main/src/config/redis.ts"
click node_monitoring_routes "https://github.com/priyansh00soni/nexus/blob/main/src/monitoring/monitoring.routes.ts"
click node_monitoring_controller "https://github.com/priyansh00soni/nexus/blob/main/src/monitoring/monitoring.controller.ts"
click node_metrics "https://github.com/priyansh00soni/nexus/blob/main/src/monitoring/metrics.ts"

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_app,node_tenant_routes,node_tenant_service,node_auth,node_idempotency,node_rate_limit,node_client toneBlue
class node_notification_routes,node_notification_controller,node_notification_service,node_template_routes,node_template_service toneAmber
class node_email_worker,node_inapp_worker,node_webhook_worker,node_renderer,node_tenant_endpoint toneMint
class node_email_queue,node_inapp_queue,node_webhook_queue,node_postgres,node_redis toneRose
class node_monitoring_routes,node_monitoring_controller,node_metrics,node_resend,node_prometheus,node_grafana toneIndigo
```

## Components

### API and tenancy

- [HTTP application](https://github.com/priyansh00soni/nexus/blob/main/src/app.ts): `src/app.ts`
- [Tenant routes](https://github.com/priyansh00soni/nexus/blob/main/src/features/tenants/tenant.routes.ts): `src/features/tenants/tenant.routes.ts`
- [Tenant service](https://github.com/priyansh00soni/nexus/blob/main/src/features/tenants/tenant.service.ts): `src/features/tenants/tenant.service.ts`
- [API-key auth](https://github.com/priyansh00soni/nexus/blob/main/src/middleware/auth.middleware.ts): `src/middleware/auth.middleware.ts`
- [Idempotency](https://github.com/priyansh00soni/nexus/blob/main/src/middleware/idempotency.middleware.ts): `src/middleware/idempotency.middleware.ts`
- [Tenant rate limit](https://github.com/priyansh00soni/nexus/blob/main/src/middleware/rateLimit.middleware.ts): `src/middleware/rateLimit.middleware.ts`

### Templates and notifications

- [Notification routes](https://github.com/priyansh00soni/nexus/blob/main/src/features/notifications/notification.routes.ts): `src/features/notifications/notification.routes.ts`
- [Notification controller](https://github.com/priyansh00soni/nexus/blob/main/src/features/notifications/notification.controller.ts): `src/features/notifications/notification.controller.ts`
- [Notification service](https://github.com/priyansh00soni/nexus/blob/main/src/features/notifications/notification.service.ts): `src/features/notifications/notification.service.ts`
- [Template routes](https://github.com/priyansh00soni/nexus/blob/main/src/features/templates/template.routes.ts): `src/features/templates/template.routes.ts`
- [Template service](https://github.com/priyansh00soni/nexus/blob/main/src/features/templates/template.service.ts): `src/features/templates/template.service.ts`

### Asynchronous delivery

- [Email worker](https://github.com/priyansh00soni/nexus/blob/main/src/workers/email.worker.ts): `src/workers/email.worker.ts`
- [In-app worker](https://github.com/priyansh00soni/nexus/blob/main/src/workers/inapp.worker.ts): `src/workers/inapp.worker.ts`
- [Webhook worker](https://github.com/priyansh00soni/nexus/blob/main/src/workers/webhook.worker.ts): `src/workers/webhook.worker.ts`
- [Message resolution](https://github.com/priyansh00soni/nexus/blob/main/src/utils/resolveNotificationMessage.ts): `src/utils/resolveNotificationMessage.ts`

### State and queues

- [Email queue](https://github.com/priyansh00soni/nexus/blob/main/src/queues/email.queue.ts): `src/queues/email.queue.ts`
- [In-app queue](https://github.com/priyansh00soni/nexus/blob/main/src/queues/inapp.queue.ts): `src/queues/inapp.queue.ts`
- [Webhook queue](https://github.com/priyansh00soni/nexus/blob/main/src/queues/webhook.queue.ts): `src/queues/webhook.queue.ts`
- [PostgreSQL](https://github.com/priyansh00soni/nexus/blob/main/src/config/prismaClient.ts): `src/config/prismaClient.ts`
- [Redis](https://github.com/priyansh00soni/nexus/blob/main/src/config/redis.ts): `src/config/redis.ts`

### Monitoring

- [Monitoring routes](https://github.com/priyansh00soni/nexus/blob/main/src/monitoring/monitoring.routes.ts): `src/monitoring/monitoring.routes.ts`
- [Monitoring controller](https://github.com/priyansh00soni/nexus/blob/main/src/monitoring/monitoring.controller.ts): `src/monitoring/monitoring.controller.ts`
- [Metrics registry](https://github.com/priyansh00soni/nexus/blob/main/src/monitoring/metrics.ts): `src/monitoring/metrics.ts`

### Other components

- **Business client**
- **Resend email**
- **Tenant webhook endpoint**
- **Prometheus**
- **Grafana**

## Connections

- Business client → HTTP application: sends API requests
- HTTP application → Tenant routes: dispatches
- HTTP application → Notification routes: dispatches
- HTTP application → Template routes: dispatches
- HTTP application → Monitoring routes: dispatches
- Tenant routes → Tenant service: invokes
- Tenant service → PostgreSQL: creates tenant
- Notification routes → API-key auth: authenticates
- API-key auth → Notification routes: continues request
- Notification routes → Idempotency: checks duplicate
- Idempotency → Redis: claims key
- Idempotency → Tenant rate limit: continues request
- Tenant rate limit → Redis: checks tenant limit
- Tenant rate limit → Notification controller: continues request
- Notification controller → Notification service: invokes
- Notification service → PostgreSQL: records notification
- Notification service → Email queue: enqueues email
- Notification service → In-app queue: enqueues in-app job
- Notification service → Webhook queue: enqueues webhook
- Notification service → Business client: returns acceptance
- Template routes → API-key auth: authenticates
- Template routes → Template service: invokes
- Template service → PostgreSQL: manages templates
- Email queue → Email worker: dispatches jobs
- In-app queue → In-app worker: dispatches jobs
- Webhook queue → Webhook worker: dispatches jobs
- Email worker → Message resolution: resolves content
- Email worker → Resend email: sends email
- Email worker → PostgreSQL: records attempts and status
- In-app worker → Message resolution: resolves content
- In-app worker → PostgreSQL: persists delivery
- Webhook worker → Message resolution: resolves content
- Webhook worker → Tenant webhook endpoint: posts webhook
- Webhook worker → PostgreSQL: records delivery
- Monitoring routes → Monitoring controller: invokes
- Monitoring controller → PostgreSQL: checks health
- Monitoring controller → Redis: checks health
- Monitoring controller → Email queue: reads counts and failures
- Monitoring controller → In-app queue: reads counts and failures
- Monitoring controller → Webhook queue: reads counts and failures
- Monitoring controller → Metrics registry: updates and serves
- Email worker → Metrics registry: records delivery metrics
- In-app worker → Metrics registry: records delivery metrics
- Webhook worker → Metrics registry: records delivery metrics
- Prometheus → Metrics registry: scrapes
- Prometheus → Grafana: feeds dashboards