# owaisahmadshah/queue-service architecture

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

- Interactive diagram: https://gitdiagram.com/owaisahmadshah/queue-service
- Repository: https://github.com/owaisahmadshah/queue-service

## Overview

Queue Service accepts notification jobs over REST, persists them, queues delivery work, and uses channel workers to deliver and record outcomes; exhausted failures can be inspected and replayed. The API also provides user and API-key management, job cancellation, statistics, pagination, and delivery/dead-letter log endpoints. The graph combines sampled call/reference evidence with explicit README capabilities; unsampled route wiring and some channel/queue details are shown only where documented, or omitted when ownership is unclear.

Main entry points: [`src/services/notification-job-service.ts`](https://github.com/owaisahmadshah/queue-service/blob/main/src/services/notification-job-service.ts) (Job Service), [`src/app.ts`](https://github.com/owaisahmadshah/queue-service/blob/main/src/app.ts) (Express App), [`src/workers/email-worker.ts`](https://github.com/owaisahmadshah/queue-service/blob/main/src/workers/email-worker.ts) (Email Worker), [`src/workers/webhook-worker.ts`](https://github.com/owaisahmadshah/queue-service/blob/main/src/workers/webhook-worker.ts) (Webhook Worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_app["Express App<br/>[app.ts]"]
  node_job_routes["Job Routes"]
  node_job_controller["Job Controller"]
  node_log_routes["Log Routes"]
  node_log_controllers["Log Controllers"]
  node_dlq_controller["DLQ Controller"]
end

subgraph group_identity["Identity and Access"]
  node_user_routes["User Routes<br/>[user-route.ts]"]
  node_user_controller["User Controller<br/>[user-controller.ts]"]
  node_user_service["User Service<br/>[user-service.ts]"]
  node_api_key["API Key Management<br/>[api-key-service.ts]"]
end

subgraph group_jobs["Job Lifecycle"]
  node_job_service["Job Service"]
  node_delivery_logs["Delivery Log Service"]
  node_dlq_service["Dead Letter Service"]
end

subgraph group_delivery["Delivery Runtime"]
  node_queue["Notification Queues"]
  node_email_worker["Email Worker<br/>[email-worker.ts]"]
  node_webhook_worker["Webhook Worker<br/>[webhook-worker.ts]"]
  node_email_service["Email Sender<br/>[email-service.ts]"]
  node_webhook_service["Webhook Sender<br/>[webhook-service.ts]"]
  node_redis[("Redis<br/>[redis.ts]")]
end

subgraph group_persistence["Persistence"]
  node_job_repo["Job Repository"]
  node_delivery_repo["Delivery Log Repository"]
  node_dlq_repo["Dead Letter Repository"]
  node_postgres[("PostgreSQL<br/>[pool.ts]")]
end

node_client(("Client"))
node_email_provider(("Email Provider"))
node_webhook_target(("Webhook Target"))

node_client -->|"sends requests"| node_app
node_app -->|"mounts routes"| node_job_routes
node_app -->|"mounts routes"| node_user_routes
node_app -->|"mounts routes"| node_log_routes
node_job_routes -->|"routes to"| node_job_controller
node_user_routes -->|"routes to"| node_user_controller
node_job_controller -->|"calls"| node_job_service
node_user_controller -->|"calls"| node_user_service
node_log_routes -.->|"routes to"| node_log_controllers
node_log_controllers -->|"calls"| node_delivery_logs
node_app -.->|"mounts endpoint"| node_dlq_controller
node_dlq_controller -->|"calls"| node_dlq_service
node_user_service -->|"creates OTP jobs"| node_job_service
node_job_service -->|"persists jobs"| node_job_repo
node_job_service -->|"enqueues email"| node_queue
node_email_worker -->|"updates job state"| node_job_service
node_webhook_worker -->|"updates job state"| node_job_service
node_email_worker -->|"delivers email"| node_email_service
node_webhook_worker -->|"sends webhook"| node_webhook_service
node_email_service -.->|"sends email"| node_email_provider
node_webhook_service -.->|"posts payload"| node_webhook_target
node_email_worker -->|"records attempts"| node_delivery_logs
node_webhook_worker -->|"records attempts"| node_delivery_logs
node_delivery_logs -->|"stores logs"| node_delivery_repo
node_job_service -->|"deletes logs"| node_delivery_logs
node_job_service -->|"deletes DLQ logs"| node_dlq_service
node_dlq_service -->|"reads and writes"| node_dlq_repo
node_dlq_service -->|"replays job"| node_job_service
node_job_repo -->|"queries"| node_postgres
node_delivery_repo -->|"queries"| node_postgres
node_dlq_repo -->|"queries"| node_postgres
node_app -->|"starts worker"| node_email_worker
node_app -->|"starts worker"| node_webhook_worker
node_app -->|"initializes queues"| node_queue
node_queue -.->|"uses connection"| node_redis
node_email_worker -.->|"consumes channel jobs"| node_queue
node_webhook_worker -.->|"consumes channel jobs"| node_queue

click node_app "https://github.com/owaisahmadshah/queue-service/blob/main/src/app.ts"
click node_job_routes "https://github.com/owaisahmadshah/queue-service/blob/main/src/routes/notification-job-route.ts"
click node_job_controller "https://github.com/owaisahmadshah/queue-service/blob/main/src/controllers/notification-job-controller.ts"
click node_log_routes "https://github.com/owaisahmadshah/queue-service/blob/main/src/routes/delivery-logs-route.ts"
click node_log_controllers "https://github.com/owaisahmadshah/queue-service/blob/main/src/controllers/delivery-logs-controller.ts"
click node_dlq_controller "https://github.com/owaisahmadshah/queue-service/blob/main/src/controllers/dead-letter-logs-controller.ts"
click node_user_routes "https://github.com/owaisahmadshah/queue-service/blob/main/src/routes/user-route.ts"
click node_user_controller "https://github.com/owaisahmadshah/queue-service/blob/main/src/controllers/user-controller.ts"
click node_user_service "https://github.com/owaisahmadshah/queue-service/blob/main/src/services/user-service.ts"
click node_api_key "https://github.com/owaisahmadshah/queue-service/blob/main/src/services/api-key-service.ts"
click node_job_service "https://github.com/owaisahmadshah/queue-service/blob/main/src/services/notification-job-service.ts"
click node_job_repo "https://github.com/owaisahmadshah/queue-service/blob/main/src/repositories/notification-job-repository.ts"
click node_queue "https://github.com/owaisahmadshah/queue-service/blob/main/src/queues/notification-queue.ts"
click node_email_worker "https://github.com/owaisahmadshah/queue-service/blob/main/src/workers/email-worker.ts"
click node_webhook_worker "https://github.com/owaisahmadshah/queue-service/blob/main/src/workers/webhook-worker.ts"
click node_email_service "https://github.com/owaisahmadshah/queue-service/blob/main/src/services/email-service.ts"
click node_webhook_service "https://github.com/owaisahmadshah/queue-service/blob/main/src/services/webhook-service.ts"
click node_delivery_logs "https://github.com/owaisahmadshah/queue-service/blob/main/src/services/delivery-logs-service.ts"
click node_delivery_repo "https://github.com/owaisahmadshah/queue-service/blob/main/src/repositories/delivery-logs-repository.ts"
click node_dlq_service "https://github.com/owaisahmadshah/queue-service/blob/main/src/services/dead-letter-logs-service.ts"
click node_dlq_repo "https://github.com/owaisahmadshah/queue-service/blob/main/src/repositories/dead-letter-logs-repository.ts"
click node_postgres "https://github.com/owaisahmadshah/queue-service/blob/main/src/db/pool.ts"
click node_redis "https://github.com/owaisahmadshah/queue-service/blob/main/src/config/redis.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_job_routes,node_job_controller,node_log_routes,node_log_controllers,node_dlq_controller,node_client toneBlue
class node_user_routes,node_user_controller,node_user_service,node_api_key toneAmber
class node_job_service,node_delivery_logs,node_dlq_service,node_webhook_target toneMint
class node_queue,node_email_worker,node_webhook_worker,node_email_service,node_webhook_service,node_redis toneRose
class node_job_repo,node_delivery_repo,node_dlq_repo,node_postgres,node_email_provider toneIndigo
```

## Components

### HTTP API

- [Express App](https://github.com/owaisahmadshah/queue-service/blob/main/src/app.ts): `src/app.ts`
- [Job Routes](https://github.com/owaisahmadshah/queue-service/blob/main/src/routes/notification-job-route.ts): `src/routes/notification-job-route.ts`
- [Job Controller](https://github.com/owaisahmadshah/queue-service/blob/main/src/controllers/notification-job-controller.ts): `src/controllers/notification-job-controller.ts`
- [Log Routes](https://github.com/owaisahmadshah/queue-service/blob/main/src/routes/delivery-logs-route.ts): `src/routes/delivery-logs-route.ts`
- [Log Controllers](https://github.com/owaisahmadshah/queue-service/blob/main/src/controllers/delivery-logs-controller.ts): `src/controllers/delivery-logs-controller.ts`
- [DLQ Controller](https://github.com/owaisahmadshah/queue-service/blob/main/src/controllers/dead-letter-logs-controller.ts): `src/controllers/dead-letter-logs-controller.ts`

### Identity and Access

- [User Routes](https://github.com/owaisahmadshah/queue-service/blob/main/src/routes/user-route.ts): `src/routes/user-route.ts`
- [User Controller](https://github.com/owaisahmadshah/queue-service/blob/main/src/controllers/user-controller.ts): `src/controllers/user-controller.ts`
- [User Service](https://github.com/owaisahmadshah/queue-service/blob/main/src/services/user-service.ts): `src/services/user-service.ts`
- [API Key Management](https://github.com/owaisahmadshah/queue-service/blob/main/src/services/api-key-service.ts): `src/services/api-key-service.ts`

### Job Lifecycle

- [Job Service](https://github.com/owaisahmadshah/queue-service/blob/main/src/services/notification-job-service.ts): `src/services/notification-job-service.ts`
- [Delivery Log Service](https://github.com/owaisahmadshah/queue-service/blob/main/src/services/delivery-logs-service.ts): `src/services/delivery-logs-service.ts`
- [Dead Letter Service](https://github.com/owaisahmadshah/queue-service/blob/main/src/services/dead-letter-logs-service.ts): `src/services/dead-letter-logs-service.ts`

### Delivery Runtime

- [Notification Queues](https://github.com/owaisahmadshah/queue-service/blob/main/src/queues/notification-queue.ts): `src/queues/notification-queue.ts`
- [Email Worker](https://github.com/owaisahmadshah/queue-service/blob/main/src/workers/email-worker.ts): `src/workers/email-worker.ts`
- [Webhook Worker](https://github.com/owaisahmadshah/queue-service/blob/main/src/workers/webhook-worker.ts): `src/workers/webhook-worker.ts`
- [Email Sender](https://github.com/owaisahmadshah/queue-service/blob/main/src/services/email-service.ts): `src/services/email-service.ts`
- [Webhook Sender](https://github.com/owaisahmadshah/queue-service/blob/main/src/services/webhook-service.ts): `src/services/webhook-service.ts`
- [Redis](https://github.com/owaisahmadshah/queue-service/blob/main/src/config/redis.ts): `src/config/redis.ts`

### Persistence

- [Job Repository](https://github.com/owaisahmadshah/queue-service/blob/main/src/repositories/notification-job-repository.ts): `src/repositories/notification-job-repository.ts`
- [Delivery Log Repository](https://github.com/owaisahmadshah/queue-service/blob/main/src/repositories/delivery-logs-repository.ts): `src/repositories/delivery-logs-repository.ts`
- [Dead Letter Repository](https://github.com/owaisahmadshah/queue-service/blob/main/src/repositories/dead-letter-logs-repository.ts): `src/repositories/dead-letter-logs-repository.ts`
- [PostgreSQL](https://github.com/owaisahmadshah/queue-service/blob/main/src/db/pool.ts): `src/db/pool.ts`

### Other components

- **Client**
- **Email Provider**
- **Webhook Target**

## Connections

- Client → Express App: sends requests
- Express App → Job Routes: mounts routes (evidence: `src/app.ts`)
- Express App → User Routes: mounts routes (evidence: `src/app.ts`)
- Express App → Log Routes: mounts routes (evidence: `src/app.ts`)
- Job Routes → Job Controller: routes to
- User Routes → User Controller: routes to (evidence: `src/routes/user-route.ts`)
- Job Controller → Job Service: calls (evidence: `src/controllers/notification-job-controller.ts`)
- User Controller → User Service: calls (evidence: `src/controllers/user-controller.ts`)
- Log Routes → Log Controllers: routes to
- Log Controllers → Delivery Log Service: calls (evidence: `src/controllers/delivery-logs-controller.ts`)
- Express App → DLQ Controller: mounts endpoint
- DLQ Controller → Dead Letter Service: calls (evidence: `src/controllers/dead-letter-logs-controller.ts`)
- User Service → Job Service: creates OTP jobs (evidence: `src/services/user-service.ts`)
- Job Service → Job Repository: persists jobs (evidence: `src/services/notification-job-service.ts`)
- Job Service → Notification Queues: enqueues email (evidence: `src/services/notification-job-service.ts`)
- Email Worker → Job Service: updates job state (evidence: `src/workers/email-worker.ts`)
- Webhook Worker → Job Service: updates job state (evidence: `src/workers/webhook-worker.ts`)
- Email Worker → Email Sender: delivers email (evidence: `src/workers/email-worker.ts`)
- Webhook Worker → Webhook Sender: sends webhook (evidence: `src/workers/webhook-worker.ts`)
- Email Sender → Email Provider: sends email
- Webhook Sender → Webhook Target: posts payload
- Email Worker → Delivery Log Service: records attempts (evidence: `src/workers/email-worker.ts`)
- Webhook Worker → Delivery Log Service: records attempts (evidence: `src/workers/webhook-worker.ts`)
- Delivery Log Service → Delivery Log Repository: stores logs (evidence: `src/services/delivery-logs-service.ts`)
- Job Service → Delivery Log Service: deletes logs (evidence: `src/services/notification-job-service.ts`)
- Job Service → Dead Letter Service: deletes DLQ logs (evidence: `src/services/notification-job-service.ts`)
- Dead Letter Service → Dead Letter Repository: reads and writes (evidence: `src/services/dead-letter-logs-service.ts`)
- Dead Letter Service → Job Service: replays job (evidence: `src/services/dead-letter-logs-service.ts`)
- Job Repository → PostgreSQL: queries (evidence: `src/repositories/notification-job-repository.ts`)
- Delivery Log Repository → PostgreSQL: queries (evidence: `src/repositories/delivery-logs-repository.ts`)
- Dead Letter Repository → PostgreSQL: queries (evidence: `src/repositories/dead-letter-logs-repository.ts`)
- Express App → Email Worker: starts worker (evidence: `src/app.ts`)
- Express App → Webhook Worker: starts worker (evidence: `src/app.ts`)
- Express App → Notification Queues: initializes queues (evidence: `src/app.ts`)
- Notification Queues → Redis: uses connection
- Email Worker → Notification Queues: consumes channel jobs
- Webhook Worker → Notification Queues: consumes channel jobs
