# binwiederhier/ntfy architecture

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

- Interactive diagram: https://gitdiagram.com/binwiederhier/ntfy
- Repository: https://github.com/binwiederhier/ntfy

## Overview

ntfy is an HTTP publish-subscribe notification service. Publishers send a message to a topic; the server authenticates and authorizes the request, dispatches it to topic subscribers, persists it for polling/replay, and triggers optional delivery side effects. Web and mobile-oriented clients subscribe, store notifications locally, and display them. The sampled source confirms server routing, topic subscription, user ACLs, persistence, attachments, web push, payments, and maintenance; several integrations are represented at their enclosing paths because their internals were not sampled.

Main entry points: [`server/server.go`](https://github.com/binwiederhier/ntfy/blob/main/server/server.go) (HTTP Server), [`attachment/store.go`](https://github.com/binwiederhier/ntfy/blob/main/attachment/store.go) (Attachment Store), [`db/db.go`](https://github.com/binwiederhier/ntfy/blob/main/db/db.go) (SQL Database), [`web/src/app/SubscriptionManager.js`](https://github.com/binwiederhier/ntfy/blob/main/web/src/app/SubscriptionManager.js) (Subscription Manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Notification Runtime"]
  node_server["HTTP Server<br/>[server.go]"]
  node_topic_router["Topic Router<br/>[topic.go]"]
end

subgraph group_domain["Domain Services"]
  node_user_manager["User Access Manager<br/>[manager.go]"]
  node_attachment_store["Attachment Store<br/>[store.go]"]
  node_webpush_store["Web Push Store<br/>[store.go]"]
end

subgraph group_persistence["Persistence"]
  node_message_cache["Message Cache<br/>[cache.go]"]
  node_database[("SQL Database<br/>[db.go]")]
  node_file_backend["File Backend<br/>[backend_file.go]"]
end

subgraph group_client["Client Application"]
  node_web_ui["Web Application<br/>[App.jsx]"]
  node_subscription_manager["Subscription Manager"]
  node_browser_db[("Browser Database<br/>[db.js]")]
  node_notifier["Client Notifier<br/>[Notifier.js]"]
end

subgraph group_integrations["External Integrations"]
  node_s3_client["S3 Client<br/>[client.go]"]
  node_payments["Payment Service<br/>[payments.go]"]
  node_mail_sender["Mail Sender<br/>[sender.go]"]
  node_metrics["Metrics Exporter<br/>[metrics.go]"]
end

node_publisher(("Publisher"))
node_subscriber(("Subscriber"))
node_object_storage[("Object Storage")]
node_stripe["Stripe"]
node_smtp["SMTP Service"]
node_firebase["Firebase"]

node_publisher -->|"publishes to"| node_server
node_subscriber -->|"subscribes via"| node_server
node_web_ui -->|"manages subscriptions"| node_subscription_manager
node_web_ui -->|"calls API"| node_server
node_server -->|"checks access"| node_user_manager
node_server -->|"dispatches topic"| node_topic_router
node_topic_router -->|"delivers messages"| node_subscriber
node_server -->|"caches messages"| node_message_cache
node_server -->|"handles attachments"| node_attachment_store
node_server -->|"manages subscriptions"| node_webpush_store
node_server -->|"checks plans"| node_payments
node_server -->|"sends email"| node_mail_sender
node_server -->|"updates metrics"| node_metrics
node_user_manager -->|"reads and writes"| node_database
node_message_cache -->|"reads and writes"| node_database
node_webpush_store -->|"reads and writes"| node_database
node_attachment_store -->|"tracks metadata"| node_database
node_attachment_store -->|"stores files"| node_file_backend
node_attachment_store -.->|"uploads objects"| node_s3_client
node_file_backend -->|"writes files"| node_object_storage
node_s3_client -.->|"reads and writes"| node_object_storage
node_payments -.->|"charges plans"| node_stripe
node_mail_sender -.->|"relays mail"| node_smtp
node_server -.->|"pushes keepalive"| node_firebase
node_subscription_manager -->|"stores notifications"| node_browser_db
node_subscription_manager -->|"triggers alerts"| node_notifier
node_server -->|"streams notifications"| node_web_ui

click node_server "https://github.com/binwiederhier/ntfy/blob/main/server/server.go"
click node_topic_router "https://github.com/binwiederhier/ntfy/blob/main/server/topic.go"
click node_web_ui "https://github.com/binwiederhier/ntfy/blob/main/web/src/components/App.jsx"
click node_subscription_manager "https://github.com/binwiederhier/ntfy/blob/main/web/src/app/SubscriptionManager.js"
click node_browser_db "https://github.com/binwiederhier/ntfy/blob/main/web/src/app/db.js"
click node_notifier "https://github.com/binwiederhier/ntfy/blob/main/web/src/app/Notifier.js"
click node_user_manager "https://github.com/binwiederhier/ntfy/blob/main/user/manager.go"
click node_attachment_store "https://github.com/binwiederhier/ntfy/blob/main/attachment/store.go"
click node_webpush_store "https://github.com/binwiederhier/ntfy/blob/main/webpush/store.go"
click node_message_cache "https://github.com/binwiederhier/ntfy/blob/main/message/cache.go"
click node_database "https://github.com/binwiederhier/ntfy/blob/main/db/db.go"
click node_file_backend "https://github.com/binwiederhier/ntfy/blob/main/attachment/backend_file.go"
click node_s3_client "https://github.com/binwiederhier/ntfy/blob/main/s3/client.go"
click node_payments "https://github.com/binwiederhier/ntfy/blob/main/payments/payments.go"
click node_mail_sender "https://github.com/binwiederhier/ntfy/blob/main/mail/sender.go"
click node_metrics "https://github.com/binwiederhier/ntfy/blob/main/metrics/metrics.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_server,node_topic_router toneBlue
class node_user_manager,node_attachment_store,node_webpush_store,node_object_storage toneAmber
class node_message_cache,node_database,node_file_backend toneMint
class node_web_ui,node_subscription_manager,node_browser_db,node_notifier toneRose
class node_s3_client,node_payments,node_mail_sender,node_metrics,node_publisher,node_subscriber,node_stripe,node_smtp,node_firebase toneIndigo
```

## Components

### Notification Runtime

- [HTTP Server](https://github.com/binwiederhier/ntfy/blob/main/server/server.go): `server/server.go`
- [Topic Router](https://github.com/binwiederhier/ntfy/blob/main/server/topic.go): `server/topic.go`

### Domain Services

- [User Access Manager](https://github.com/binwiederhier/ntfy/blob/main/user/manager.go): `user/manager.go`
- [Attachment Store](https://github.com/binwiederhier/ntfy/blob/main/attachment/store.go): `attachment/store.go`
- [Web Push Store](https://github.com/binwiederhier/ntfy/blob/main/webpush/store.go): `webpush/store.go`

### Persistence

- [Message Cache](https://github.com/binwiederhier/ntfy/blob/main/message/cache.go): `message/cache.go`
- [SQL Database](https://github.com/binwiederhier/ntfy/blob/main/db/db.go): `db/db.go`
- [File Backend](https://github.com/binwiederhier/ntfy/blob/main/attachment/backend_file.go): `attachment/backend_file.go`

### Client Application

- [Web Application](https://github.com/binwiederhier/ntfy/blob/main/web/src/components/App.jsx): `web/src/components/App.jsx`
- [Subscription Manager](https://github.com/binwiederhier/ntfy/blob/main/web/src/app/SubscriptionManager.js): `web/src/app/SubscriptionManager.js`
- [Browser Database](https://github.com/binwiederhier/ntfy/blob/main/web/src/app/db.js): `web/src/app/db.js`
- [Client Notifier](https://github.com/binwiederhier/ntfy/blob/main/web/src/app/Notifier.js): `web/src/app/Notifier.js`

### External Integrations

- [S3 Client](https://github.com/binwiederhier/ntfy/blob/main/s3/client.go): `s3/client.go`
- [Payment Service](https://github.com/binwiederhier/ntfy/blob/main/payments/payments.go): `payments/payments.go`
- [Mail Sender](https://github.com/binwiederhier/ntfy/blob/main/mail/sender.go): `mail/sender.go`
- [Metrics Exporter](https://github.com/binwiederhier/ntfy/blob/main/metrics/metrics.go): `metrics/metrics.go`

### Other components

- **Publisher**
- **Subscriber**
- **Object Storage**
- **Stripe**
- **SMTP Service**
- **Firebase**

## Connections

- Publisher → HTTP Server: publishes to
- Subscriber → HTTP Server: subscribes via
- Web Application → Subscription Manager: manages subscriptions
- Web Application → HTTP Server: calls API
- HTTP Server → User Access Manager: checks access
- HTTP Server → Topic Router: dispatches topic
- Topic Router → Subscriber: delivers messages
- HTTP Server → Message Cache: caches messages
- HTTP Server → Attachment Store: handles attachments
- HTTP Server → Web Push Store: manages subscriptions
- HTTP Server → Payment Service: checks plans
- HTTP Server → Mail Sender: sends email
- HTTP Server → Metrics Exporter: updates metrics
- User Access Manager → SQL Database: reads and writes
- Message Cache → SQL Database: reads and writes
- Web Push Store → SQL Database: reads and writes
- Attachment Store → SQL Database: tracks metadata
- Attachment Store → File Backend: stores files
- Attachment Store → S3 Client: uploads objects
- File Backend → Object Storage: writes files
- S3 Client → Object Storage: reads and writes
- Payment Service → Stripe: charges plans
- Mail Sender → SMTP Service: relays mail
- HTTP Server → Firebase: pushes keepalive
- Subscription Manager → Browser Database: stores notifications
- Subscription Manager → Client Notifier: triggers alerts
- HTTP Server → Web Application: streams notifications
