# knadh/listmonk architecture

> Architecture diagram of the GitHub repository knadh/listmonk, 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/knadh/listmonk
- Repository: https://github.com/knadh/listmonk

## Overview

listmonk is a self-hosted newsletter and mailing-list manager. Administrators use the Vue application (and embedded email builder) to manage lists, subscribers, templates, media, and campaigns. Requests pass through authenticated HTTP handlers into domain services and PostgreSQL. The campaign manager batches eligible subscribers, renders messages, loads media, and sends through SMTP. Public forms collect subscriptions, while bounce integrations feed delivery events back into the system. Sampled code confirms startup, routing, authentication, campaign storage, delivery, and frontend API boundaries; some unsampled handler-to-domain calls are represented at subsystem level.

Main entry points: [`cmd/handlers.go`](https://github.com/knadh/listmonk/blob/master/cmd/handlers.go) (HTTP Handlers), [`cmd/main.go`](https://github.com/knadh/listmonk/blob/master/cmd/main.go) (Application Runtime), [`frontend/src/App.vue`](https://github.com/knadh/listmonk/blob/master/frontend/src/App.vue) (Admin UI), [`internal/media/media.go`](https://github.com/knadh/listmonk/blob/master/internal/media/media.go) (Media Store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web Applications"]
  node_admin_ui["Admin UI<br/>[App.vue]"]
  node_public_forms["Public Forms<br/>[Forms.vue]"]
  node_email_builder["Email Builder<br/>[main.tsx]"]
  node_api_client["API Client<br/>[index.js]"]
end

subgraph group_http["HTTP and Auth"]
  node_http_handlers["HTTP Handlers<br/>[handlers.go]"]
  node_auth["Authentication<br/>[auth.go]"]
  node_runtime["Application Runtime<br/>[main.go]"]
end

subgraph group_domain["Domain Services"]
  node_core["Core Services<br/>[core.go]"]
  node_audiences["Lists and Audiences<br/>[lists.go]"]
  node_subscribers["Subscriber Management<br/>[subscribers.go]"]
  node_campaigns["Campaign Management<br/>[campaigns.go]"]
  node_templates["Template Management<br/>[templates.go]"]
  node_dashboard["Dashboard Analytics<br/>[dashboard.go]"]
end

subgraph group_delivery["Campaign Delivery"]
  node_manager["Campaign Manager<br/>[manager.go]"]
  node_email["Email Messenger<br/>[email.go]"]
  node_bounce["Bounce Processing<br/>[bounce.go]"]
end

subgraph group_storage["Storage and Events"]
  node_manager_store["Campaign Store<br/>[manager_store.go]"]
  node_media["Media Store<br/>[media.go]"]
  node_filesystem["Filesystem Media<br/>[filesystem.go]"]
  node_s3["S3 Media<br/>[s3.go]"]
  node_postgres[("PostgreSQL")]
  node_events["Event Stream<br/>[events.go]"]
end

node_admin(("Administrator"))
node_subscriber(("Subscriber"))
node_smtp["SMTP Service"]
node_bounce_services["Bounce Providers"]

node_admin -->|"uses"| node_admin_ui
node_subscriber -->|"submits forms"| node_public_forms
node_admin_ui -->|"issues requests"| node_api_client
node_public_forms -->|"submits data"| node_api_client
node_admin_ui -->|"edits emails"| node_email_builder
node_api_client -->|"calls API"| node_http_handlers
node_http_handlers -->|"checks access"| node_auth
node_http_handlers -->|"dispatches requests"| node_core
node_http_handlers -->|"manages lists"| node_audiences
node_http_handlers -->|"manages subscribers"| node_subscribers
node_http_handlers -->|"manages campaigns"| node_campaigns
node_http_handlers -->|"manages templates"| node_templates
node_http_handlers -->|"manages media"| node_media
node_http_handlers -->|"reads analytics"| node_dashboard
node_runtime -->|"starts server"| node_http_handlers
node_runtime -->|"starts workers"| node_manager
node_runtime -->|"starts scanning"| node_bounce
node_manager -->|"loads campaigns"| node_manager_store
node_manager_store -->|"queries data"| node_postgres
node_manager_store -->|"loads blobs"| node_media
node_manager -->|"pushes messages"| node_email
node_email -->|"sends mail"| node_smtp
node_media -.->|"uses provider"| node_filesystem
node_media -.->|"uses provider"| node_s3
node_bounce_services -.->|"posts bounces"| node_bounce
node_runtime -->|"publishes logs"| node_events
node_events -->|"streams events"| node_admin_ui

click node_admin_ui "https://github.com/knadh/listmonk/blob/master/frontend/src/App.vue"
click node_public_forms "https://github.com/knadh/listmonk/blob/master/frontend/src/views/Forms.vue"
click node_email_builder "https://github.com/knadh/listmonk/blob/master/frontend/email-builder/src/main.tsx"
click node_api_client "https://github.com/knadh/listmonk/blob/master/frontend/src/api/index.js"
click node_http_handlers "https://github.com/knadh/listmonk/blob/master/cmd/handlers.go"
click node_auth "https://github.com/knadh/listmonk/blob/master/internal/auth/auth.go"
click node_runtime "https://github.com/knadh/listmonk/blob/master/cmd/main.go"
click node_core "https://github.com/knadh/listmonk/blob/master/internal/core/core.go"
click node_audiences "https://github.com/knadh/listmonk/blob/master/internal/core/lists.go"
click node_subscribers "https://github.com/knadh/listmonk/blob/master/internal/core/subscribers.go"
click node_campaigns "https://github.com/knadh/listmonk/blob/master/internal/core/campaigns.go"
click node_templates "https://github.com/knadh/listmonk/blob/master/internal/core/templates.go"
click node_dashboard "https://github.com/knadh/listmonk/blob/master/internal/core/dashboard.go"
click node_manager "https://github.com/knadh/listmonk/blob/master/internal/manager/manager.go"
click node_email "https://github.com/knadh/listmonk/blob/master/internal/messenger/email/email.go"
click node_bounce "https://github.com/knadh/listmonk/blob/master/internal/bounce/bounce.go"
click node_manager_store "https://github.com/knadh/listmonk/blob/master/cmd/manager_store.go"
click node_media "https://github.com/knadh/listmonk/blob/master/internal/media/media.go"
click node_filesystem "https://github.com/knadh/listmonk/blob/master/internal/media/providers/filesystem/filesystem.go"
click node_s3 "https://github.com/knadh/listmonk/blob/master/internal/media/providers/s3/s3.go"
click node_events "https://github.com/knadh/listmonk/blob/master/internal/events/events.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_admin_ui,node_public_forms,node_email_builder,node_api_client toneBlue
class node_http_handlers,node_auth,node_runtime toneAmber
class node_core,node_audiences,node_subscribers,node_campaigns,node_templates,node_dashboard toneMint
class node_manager,node_email,node_bounce toneRose
class node_manager_store,node_media,node_filesystem,node_s3,node_postgres,node_events,node_admin,node_subscriber,node_smtp,node_bounce_services toneIndigo
```

## Components

### Web Applications

- [Admin UI](https://github.com/knadh/listmonk/blob/master/frontend/src/App.vue): `frontend/src/App.vue`
- [Public Forms](https://github.com/knadh/listmonk/blob/master/frontend/src/views/Forms.vue): `frontend/src/views/Forms.vue`
- [Email Builder](https://github.com/knadh/listmonk/blob/master/frontend/email-builder/src/main.tsx): `frontend/email-builder/src/main.tsx`
- [API Client](https://github.com/knadh/listmonk/blob/master/frontend/src/api/index.js): `frontend/src/api/index.js`

### HTTP and Auth

- [HTTP Handlers](https://github.com/knadh/listmonk/blob/master/cmd/handlers.go): `cmd/handlers.go`
- [Authentication](https://github.com/knadh/listmonk/blob/master/internal/auth/auth.go): `internal/auth/auth.go`
- [Application Runtime](https://github.com/knadh/listmonk/blob/master/cmd/main.go): `cmd/main.go`

### Domain Services

- [Core Services](https://github.com/knadh/listmonk/blob/master/internal/core/core.go): `internal/core/core.go`
- [Lists and Audiences](https://github.com/knadh/listmonk/blob/master/internal/core/lists.go): `internal/core/lists.go`
- [Subscriber Management](https://github.com/knadh/listmonk/blob/master/internal/core/subscribers.go): `internal/core/subscribers.go`
- [Campaign Management](https://github.com/knadh/listmonk/blob/master/internal/core/campaigns.go): `internal/core/campaigns.go`
- [Template Management](https://github.com/knadh/listmonk/blob/master/internal/core/templates.go): `internal/core/templates.go`
- [Dashboard Analytics](https://github.com/knadh/listmonk/blob/master/internal/core/dashboard.go): `internal/core/dashboard.go`

### Campaign Delivery

- [Campaign Manager](https://github.com/knadh/listmonk/blob/master/internal/manager/manager.go): `internal/manager/manager.go`
- [Email Messenger](https://github.com/knadh/listmonk/blob/master/internal/messenger/email/email.go): `internal/messenger/email/email.go`
- [Bounce Processing](https://github.com/knadh/listmonk/blob/master/internal/bounce/bounce.go): `internal/bounce/bounce.go`

### Storage and Events

- [Campaign Store](https://github.com/knadh/listmonk/blob/master/cmd/manager_store.go): `cmd/manager_store.go`
- [Media Store](https://github.com/knadh/listmonk/blob/master/internal/media/media.go): `internal/media/media.go`
- [Filesystem Media](https://github.com/knadh/listmonk/blob/master/internal/media/providers/filesystem/filesystem.go): `internal/media/providers/filesystem/filesystem.go`
- [S3 Media](https://github.com/knadh/listmonk/blob/master/internal/media/providers/s3/s3.go): `internal/media/providers/s3/s3.go`
- **PostgreSQL**
- [Event Stream](https://github.com/knadh/listmonk/blob/master/internal/events/events.go): `internal/events/events.go`

### Other components

- **Administrator**
- **Subscriber**
- **SMTP Service**
- **Bounce Providers**

## Connections

- Administrator → Admin UI: uses
- Subscriber → Public Forms: submits forms
- Admin UI → API Client: issues requests
- Public Forms → API Client: submits data
- Admin UI → Email Builder: edits emails
- API Client → HTTP Handlers: calls API
- HTTP Handlers → Authentication: checks access
- HTTP Handlers → Core Services: dispatches requests
- HTTP Handlers → Lists and Audiences: manages lists
- HTTP Handlers → Subscriber Management: manages subscribers
- HTTP Handlers → Campaign Management: manages campaigns
- HTTP Handlers → Template Management: manages templates
- HTTP Handlers → Media Store: manages media
- HTTP Handlers → Dashboard Analytics: reads analytics
- Application Runtime → HTTP Handlers: starts server
- Application Runtime → Campaign Manager: starts workers
- Application Runtime → Bounce Processing: starts scanning
- Campaign Manager → Campaign Store: loads campaigns
- Campaign Store → PostgreSQL: queries data
- Campaign Store → Media Store: loads blobs
- Campaign Manager → Email Messenger: pushes messages
- Email Messenger → SMTP Service: sends mail
- Media Store → Filesystem Media: uses provider
- Media Store → S3 Media: uses provider
- Bounce Providers → Bounce Processing: posts bounces
- Application Runtime → Event Stream: publishes logs
- Event Stream → Admin UI: streams events
