# suhas1010/webhookorchestrator architecture

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

- Interactive diagram: https://gitdiagram.com/suhas1010/webhookorchestrator
- Repository: https://github.com/suhas1010/webhookorchestrator

## Overview

WebhookOrchestrator is a multi-tenant webhook API: applications register endpoints and event types, subscribe endpoints, then publish events. The sampled event service selects enabled subscriptions and transactionally records an event plus pending deliveries. The README also describes asynchronous delivery, retries, signatures and failure handling, but the tree shows no worker or delivery processor, so those capabilities are represented as documented, unverified stages. Authentication and endpoint-management paths are better evidenced than event-route wiring; the graph avoids asserting unsampled calls.

Main entry points: [`src/routes/index.ts`](https://github.com/suhas1010/webhookorchestrator/blob/main/src/routes/index.ts) (API routes), [`src/routes/endpoint.routes.ts`](https://github.com/suhas1010/webhookorchestrator/blob/main/src/routes/endpoint.routes.ts) (Endpoint routes), [`src/services/event.service.ts`](https://github.com/suhas1010/webhookorchestrator/blob/main/src/services/event.service.ts) (Event publishing), [`src/services`](https://github.com/suhas1010/webhookorchestrator/tree/main/src/services) (Async delivery processing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and security"]
  node_server["Express server<br/>[server.ts]"]
  node_routes["API routes<br/>[index.ts]"]
  node_auth_routes["Auth routes<br/>[auth.routes.ts]"]
  node_endpoint_routes["Endpoint routes<br/>[endpoint.routes.ts]"]
  node_event_routes["Event routes<br/>[event.routes.ts]"]
  node_auth_controller["Auth handlers<br/>[auth.controller.ts]"]
  node_endpoint_controller["Endpoint handlers"]
  node_event_controller["Event handlers"]
  node_auth_middleware["Authentication<br/>[auth.middleware.ts]"]
  node_auth_service["Identity and API keys<br/>[auth.service.ts]"]
end

subgraph group_domain["Webhook domain"]
  node_endpoint_service["Endpoint management"]
  node_event_service["Event publishing<br/>[event.service.ts]"]
end

subgraph group_storage["Persistence"]
  node_postgres[("PostgreSQL")]
end

subgraph group_delivery["Delivery operations"]
  node_delivery_records[("Pending delivery records<br/>[event.service.ts]")]
  node_delivery_worker["Async delivery processing"]
  node_retry_reliability["Retries and failure handling"]
end

node_client(("Client applications"))
node_webhook_targets(("Subscribed endpoints"))

node_client -->|"sends requests"| node_server
node_server -->|"mounts routes"| node_routes
node_routes -->|"mounts auth"| node_auth_routes
node_routes -->|"mounts endpoints"| node_endpoint_routes
node_auth_routes -->|"dispatches to"| node_auth_controller
node_endpoint_routes -->|"authenticates with"| node_auth_middleware
node_endpoint_routes -->|"dispatches to"| node_endpoint_controller
node_auth_controller -->|"calls"| node_auth_service
node_auth_middleware -->|"checks API key"| node_auth_service
node_event_routes -.->|"dispatches to"| node_event_controller
node_event_controller -->|"calls"| node_event_service
node_event_service -->|"queries"| node_postgres
node_endpoint_service -->|"queries"| node_postgres
node_auth_service -.->|"queries"| node_postgres
node_event_service -->|"creates tasks"| node_delivery_records
node_delivery_records -.->|"processed asynchronously"| node_delivery_worker
node_delivery_worker -.->|"sends requests"| node_webhook_targets
node_delivery_worker -.->|"handles failures"| node_retry_reliability

click node_server "https://github.com/suhas1010/webhookorchestrator/blob/main/src/server.ts"
click node_routes "https://github.com/suhas1010/webhookorchestrator/blob/main/src/routes/index.ts"
click node_auth_routes "https://github.com/suhas1010/webhookorchestrator/blob/main/src/routes/auth.routes.ts"
click node_endpoint_routes "https://github.com/suhas1010/webhookorchestrator/blob/main/src/routes/endpoint.routes.ts"
click node_event_routes "https://github.com/suhas1010/webhookorchestrator/blob/main/src/routes/event.routes.ts"
click node_auth_controller "https://github.com/suhas1010/webhookorchestrator/blob/main/src/controllers/auth.controller.ts"
click node_endpoint_controller "https://github.com/suhas1010/webhookorchestrator/blob/main/src/controllers/endpoint.controller.ts"
click node_event_controller "https://github.com/suhas1010/webhookorchestrator/blob/main/src/controllers/event.controller.ts"
click node_auth_middleware "https://github.com/suhas1010/webhookorchestrator/blob/main/src/middleware/auth.middleware.ts"
click node_auth_service "https://github.com/suhas1010/webhookorchestrator/blob/main/src/services/auth.service.ts"
click node_endpoint_service "https://github.com/suhas1010/webhookorchestrator/blob/main/src/services/endpoint.service.ts"
click node_event_service "https://github.com/suhas1010/webhookorchestrator/blob/main/src/services/event.service.ts"
click node_delivery_records "https://github.com/suhas1010/webhookorchestrator/blob/main/src/services/event.service.ts"
click node_delivery_worker "https://github.com/suhas1010/webhookorchestrator/tree/main/src/services"
click node_retry_reliability "https://github.com/suhas1010/webhookorchestrator/tree/main/src/services"

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_server,node_routes,node_auth_routes,node_endpoint_routes,node_event_routes,node_auth_controller,node_endpoint_controller,node_event_controller,node_auth_middleware,node_auth_service,node_client toneBlue
class node_endpoint_service,node_event_service toneAmber
class node_postgres toneMint
class node_delivery_records,node_delivery_worker,node_retry_reliability toneRose
class node_webhook_targets toneIndigo
```

## Components

### API and security

- [Express server](https://github.com/suhas1010/webhookorchestrator/blob/main/src/server.ts): `src/server.ts`
- [API routes](https://github.com/suhas1010/webhookorchestrator/blob/main/src/routes/index.ts): `src/routes/index.ts`
- [Auth routes](https://github.com/suhas1010/webhookorchestrator/blob/main/src/routes/auth.routes.ts): `src/routes/auth.routes.ts`
- [Endpoint routes](https://github.com/suhas1010/webhookorchestrator/blob/main/src/routes/endpoint.routes.ts): `src/routes/endpoint.routes.ts`
- [Event routes](https://github.com/suhas1010/webhookorchestrator/blob/main/src/routes/event.routes.ts): `src/routes/event.routes.ts`
- [Auth handlers](https://github.com/suhas1010/webhookorchestrator/blob/main/src/controllers/auth.controller.ts): `src/controllers/auth.controller.ts`
- [Endpoint handlers](https://github.com/suhas1010/webhookorchestrator/blob/main/src/controllers/endpoint.controller.ts): `src/controllers/endpoint.controller.ts`
- [Event handlers](https://github.com/suhas1010/webhookorchestrator/blob/main/src/controllers/event.controller.ts): `src/controllers/event.controller.ts`
- [Authentication](https://github.com/suhas1010/webhookorchestrator/blob/main/src/middleware/auth.middleware.ts): `src/middleware/auth.middleware.ts`
- [Identity and API keys](https://github.com/suhas1010/webhookorchestrator/blob/main/src/services/auth.service.ts): `src/services/auth.service.ts`

### Webhook domain

- [Endpoint management](https://github.com/suhas1010/webhookorchestrator/blob/main/src/services/endpoint.service.ts): `src/services/endpoint.service.ts`
- [Event publishing](https://github.com/suhas1010/webhookorchestrator/blob/main/src/services/event.service.ts): `src/services/event.service.ts`

### Persistence

- **PostgreSQL**

### Delivery operations

- [Pending delivery records](https://github.com/suhas1010/webhookorchestrator/blob/main/src/services/event.service.ts): `src/services/event.service.ts`
- [Async delivery processing](https://github.com/suhas1010/webhookorchestrator/tree/main/src/services): `src/services`
- [Retries and failure handling](https://github.com/suhas1010/webhookorchestrator/tree/main/src/services): `src/services`

### Other components

- **Client applications**
- **Subscribed endpoints**

## Connections

- Client applications → Express server: sends requests (evidence: `README.md`)
- Express server → API routes: mounts routes (evidence: `src/server.ts`)
- API routes → Auth routes: mounts auth (evidence: `src/routes/index.ts`)
- API routes → Endpoint routes: mounts endpoints (evidence: `src/routes/index.ts`)
- Auth routes → Auth handlers: dispatches to (evidence: `src/routes/auth.routes.ts`)
- Endpoint routes → Authentication: authenticates with (evidence: `src/routes/endpoint.routes.ts`)
- Endpoint routes → Endpoint handlers: dispatches to (evidence: `src/routes/endpoint.routes.ts`)
- Auth handlers → Identity and API keys: calls (evidence: `src/controllers/auth.controller.ts`)
- Authentication → Identity and API keys: checks API key (evidence: `src/middleware/auth.middleware.ts`)
- Event routes → Event handlers: dispatches to
- Event handlers → Event publishing: calls (evidence: `src/controllers/event.controller.ts`)
- Event publishing → PostgreSQL: queries (evidence: `src/services/event.service.ts`)
- Endpoint management → PostgreSQL: queries (evidence: `src/services/endpoint.service.ts`)
- Identity and API keys → PostgreSQL: queries
- Event publishing → Pending delivery records: creates tasks (evidence: `src/services/event.service.ts`)
- Pending delivery records → Async delivery processing: processed asynchronously (evidence: `README.md`)
- Async delivery processing → Subscribed endpoints: sends requests (evidence: `README.md`)
- Async delivery processing → Retries and failure handling: handles failures (evidence: `README.md`)
