# onurcevik/notification-service architecture

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

- Interactive diagram: https://gitdiagram.com/onurcevik/notification-service
- Repository: https://github.com/onurcevik/notification-service

## Overview

This Go service accepts notification requests over REST and WebSocket, persists notification state and outbox events in PostgreSQL, then asynchronously relays work to priority Redis Streams. Workers apply per-channel rate limiting, retries and circuit breakers before calling a configured webhook; scheduled notifications enter the same outbox path when due. The README also documents health and metrics endpoints and inline templates. Edges reflect sampled calls and explicit README behavior; unsampled internals are represented only where the documented capability supports the subsystem.

Main entry points: [`internal/worker/processor.go`](https://github.com/onurcevik/notification-service/blob/main/internal/worker/processor.go) (Delivery processor), [`internal/handler/router.go`](https://github.com/onurcevik/notification-service/blob/main/internal/handler/router.go) (HTTP router), [`internal/repository/notification.go`](https://github.com/onurcevik/notification-service/blob/main/internal/repository/notification.go) (Notification repository), [`internal/repository/event.go`](https://github.com/onurcevik/notification-service/blob/main/internal/repository/event.go) (Outbox repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and updates"]
  node_router["HTTP router<br/>[router.go]"]
  node_notification_handler["Notification API<br/>[notification.go]"]
  node_templates["Inline templates<br/>[template_render.go]"]
  node_websocket["Status WebSocket<br/>[websocket.go]"]
  node_hub["Status hub<br/>[hub.go]"]
end

subgraph group_persistence["Notification state"]
  node_domain["Notification model<br/>[notification.go]"]
  node_notification_service["Notification service<br/>[notification.go]"]
  node_notification_repo["Notification repository<br/>[notification.go]"]
  node_event_repo["Outbox repository<br/>[event.go]"]
  node_postgres[("PostgreSQL")]
  node_scheduler["Schedule service<br/>[scheduler.go]"]
end

subgraph group_delivery["Queue and delivery"]
  node_relay["Outbox relay<br/>[relay.go]"]
  node_redis_queue["Priority streams<br/>[stream.go]"]
  node_worker_pool["Worker pool<br/>[pool.go]"]
  node_processor["Delivery processor<br/>[processor.go]"]
  node_rate_limiter["Rate limiter<br/>[ratelimiter.go]"]
  node_provider["Webhook provider<br/>[webhook.go]"]
end

subgraph group_operations["Reliability and telemetry"]
  node_health["Health checks<br/>[health.go]"]
  node_metrics["Metrics endpoint<br/>[metrics.go]"]
  node_telemetry["Tracing<br/>[telemetry.go]"]
end

node_client(("API client"))
node_webhook_endpoint(("Webhook endpoint"))
node_redis[("Redis")]

node_client -->|"sends requests"| node_router
node_router -->|"routes requests"| node_notification_handler
node_notification_handler -->|"delegates operations"| node_notification_service
node_notification_handler -.->|"renders templates"| node_templates
node_router -->|"routes stream"| node_websocket
node_websocket -.->|"subscribes status"| node_hub
node_notification_service -->|"persists state"| node_notification_repo
node_notification_service -->|"inserts outbox events"| node_event_repo
node_notification_repo -->|"reads and writes"| node_postgres
node_event_repo -.->|"reads and writes"| node_postgres
node_scheduler -->|"loads due items"| node_notification_repo
node_scheduler -->|"inserts due events"| node_event_repo
node_relay -->|"fetches events"| node_event_repo
node_relay -->|"loads notifications"| node_notification_repo
node_relay -->|"enqueues work"| node_redis_queue
node_redis_queue -->|"stores streams"| node_redis
node_worker_pool -->|"starts processors"| node_processor
node_processor -->|"consumes and acknowledges"| node_redis_queue
node_processor -.->|"updates delivery state"| node_notification_repo
node_processor -.->|"checks throughput"| node_rate_limiter
node_processor -->|"sends notification"| node_provider
node_provider -->|"posts payload"| node_webhook_endpoint
node_processor -->|"broadcasts status"| node_hub
node_router -->|"routes checks"| node_health
node_router -->|"routes metrics"| node_metrics
node_metrics -->|"reads queue stats"| node_redis
node_health -.->|"checks database"| node_postgres
node_health -.->|"checks queue"| node_redis
node_telemetry -.->|"instruments HTTP"| node_router

click node_router "https://github.com/onurcevik/notification-service/blob/main/internal/handler/router.go"
click node_notification_handler "https://github.com/onurcevik/notification-service/blob/main/internal/handler/notification.go"
click node_templates "https://github.com/onurcevik/notification-service/blob/main/internal/handler/template_render.go"
click node_websocket "https://github.com/onurcevik/notification-service/blob/main/internal/handler/websocket.go"
click node_hub "https://github.com/onurcevik/notification-service/blob/main/internal/hub/hub.go"
click node_domain "https://github.com/onurcevik/notification-service/blob/main/internal/domain/notification.go"
click node_notification_service "https://github.com/onurcevik/notification-service/blob/main/internal/service/notification.go"
click node_notification_repo "https://github.com/onurcevik/notification-service/blob/main/internal/repository/notification.go"
click node_event_repo "https://github.com/onurcevik/notification-service/blob/main/internal/repository/event.go"
click node_scheduler "https://github.com/onurcevik/notification-service/blob/main/internal/service/scheduler.go"
click node_relay "https://github.com/onurcevik/notification-service/blob/main/internal/queue/relay.go"
click node_redis_queue "https://github.com/onurcevik/notification-service/blob/main/internal/queue/stream.go"
click node_worker_pool "https://github.com/onurcevik/notification-service/blob/main/internal/worker/pool.go"
click node_processor "https://github.com/onurcevik/notification-service/blob/main/internal/worker/processor.go"
click node_rate_limiter "https://github.com/onurcevik/notification-service/blob/main/internal/ratelimit/ratelimiter.go"
click node_provider "https://github.com/onurcevik/notification-service/blob/main/internal/provider/webhook.go"
click node_health "https://github.com/onurcevik/notification-service/blob/main/internal/handler/health.go"
click node_metrics "https://github.com/onurcevik/notification-service/blob/main/internal/handler/metrics.go"
click node_telemetry "https://github.com/onurcevik/notification-service/blob/main/internal/telemetry/telemetry.go"

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_router,node_notification_handler,node_templates,node_websocket,node_hub,node_client toneBlue
class node_domain,node_notification_service,node_notification_repo,node_event_repo,node_postgres,node_scheduler,node_redis toneAmber
class node_relay,node_redis_queue,node_worker_pool,node_processor,node_rate_limiter,node_provider,node_webhook_endpoint toneMint
class node_health,node_metrics,node_telemetry toneRose
```

## Components

### API and updates

- [HTTP router](https://github.com/onurcevik/notification-service/blob/main/internal/handler/router.go): `internal/handler/router.go`
- [Notification API](https://github.com/onurcevik/notification-service/blob/main/internal/handler/notification.go): `internal/handler/notification.go`
- [Inline templates](https://github.com/onurcevik/notification-service/blob/main/internal/handler/template_render.go): `internal/handler/template_render.go`
- [Status WebSocket](https://github.com/onurcevik/notification-service/blob/main/internal/handler/websocket.go): `internal/handler/websocket.go`
- [Status hub](https://github.com/onurcevik/notification-service/blob/main/internal/hub/hub.go): `internal/hub/hub.go`

### Notification state

- [Notification model](https://github.com/onurcevik/notification-service/blob/main/internal/domain/notification.go): `internal/domain/notification.go`
- [Notification service](https://github.com/onurcevik/notification-service/blob/main/internal/service/notification.go): `internal/service/notification.go`
- [Notification repository](https://github.com/onurcevik/notification-service/blob/main/internal/repository/notification.go): `internal/repository/notification.go`
- [Outbox repository](https://github.com/onurcevik/notification-service/blob/main/internal/repository/event.go): `internal/repository/event.go`
- **PostgreSQL**
- [Schedule service](https://github.com/onurcevik/notification-service/blob/main/internal/service/scheduler.go): `internal/service/scheduler.go`

### Queue and delivery

- [Outbox relay](https://github.com/onurcevik/notification-service/blob/main/internal/queue/relay.go): `internal/queue/relay.go`
- [Priority streams](https://github.com/onurcevik/notification-service/blob/main/internal/queue/stream.go): `internal/queue/stream.go`
- [Worker pool](https://github.com/onurcevik/notification-service/blob/main/internal/worker/pool.go): `internal/worker/pool.go`
- [Delivery processor](https://github.com/onurcevik/notification-service/blob/main/internal/worker/processor.go): `internal/worker/processor.go`
- [Rate limiter](https://github.com/onurcevik/notification-service/blob/main/internal/ratelimit/ratelimiter.go): `internal/ratelimit/ratelimiter.go`
- [Webhook provider](https://github.com/onurcevik/notification-service/blob/main/internal/provider/webhook.go): `internal/provider/webhook.go`

### Reliability and telemetry

- [Health checks](https://github.com/onurcevik/notification-service/blob/main/internal/handler/health.go): `internal/handler/health.go`
- [Metrics endpoint](https://github.com/onurcevik/notification-service/blob/main/internal/handler/metrics.go): `internal/handler/metrics.go`
- [Tracing](https://github.com/onurcevik/notification-service/blob/main/internal/telemetry/telemetry.go): `internal/telemetry/telemetry.go`

### Other components

- **API client**
- **Webhook endpoint**
- **Redis**

## Connections

- API client → HTTP router: sends requests (evidence: `README.md`)
- HTTP router → Notification API: routes requests (evidence: `internal/handler/router.go`)
- Notification API → Notification service: delegates operations (evidence: `internal/handler/notification.go`)
- Notification API → Inline templates: renders templates
- HTTP router → Status WebSocket: routes stream (evidence: `internal/handler/router.go`)
- Status WebSocket → Status hub: subscribes status
- Notification service → Notification repository: persists state (evidence: `internal/service/notification.go`)
- Notification service → Outbox repository: inserts outbox events (evidence: `internal/service/notification.go`)
- Notification repository → PostgreSQL: reads and writes (evidence: `internal/repository/notification.go`)
- Outbox repository → PostgreSQL: reads and writes
- Schedule service → Notification repository: loads due items (evidence: `internal/service/scheduler.go`)
- Schedule service → Outbox repository: inserts due events (evidence: `internal/service/scheduler.go`)
- Outbox relay → Outbox repository: fetches events (evidence: `internal/queue/relay.go`)
- Outbox relay → Notification repository: loads notifications (evidence: `internal/queue/relay.go`)
- Outbox relay → Priority streams: enqueues work (evidence: `internal/queue/relay.go`)
- Priority streams → Redis: stores streams (evidence: `internal/queue/stream.go`)
- Worker pool → Delivery processor: starts processors (evidence: `internal/worker/pool.go`)
- Delivery processor → Priority streams: consumes and acknowledges (evidence: `internal/worker/processor.go`)
- Delivery processor → Notification repository: updates delivery state
- Delivery processor → Rate limiter: checks throughput
- Delivery processor → Webhook provider: sends notification (evidence: `internal/worker/processor.go`)
- Webhook provider → Webhook endpoint: posts payload (evidence: `internal/provider/webhook.go`)
- Delivery processor → Status hub: broadcasts status (evidence: `internal/worker/processor.go`)
- HTTP router → Health checks: routes checks (evidence: `internal/handler/router.go`)
- HTTP router → Metrics endpoint: routes metrics (evidence: `internal/handler/router.go`)
- Metrics endpoint → Redis: reads queue stats (evidence: `internal/handler/metrics.go`)
- Health checks → PostgreSQL: checks database
- Health checks → Redis: checks queue
- Tracing → HTTP router: instruments HTTP