# louislam/uptime-kuma architecture

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

- Interactive diagram: https://gitdiagram.com/louislam/uptime-kuma
- Repository: https://github.com/louislam/uptime-kuma

## Overview

Uptime Kuma is a self-hosted monitoring application. An operator configures monitors in the reactive UI; the server runs monitor checks, records heartbeat and uptime history, and exposes status and metrics, with notifications available for alerts. Other documented capabilities include authentication, multiple status pages, certificate information, and proxy support. The graph focuses on these product paths. Some server wiring and monitor implementations were not excerpted, so uncertain runtime links are omitted; README-backed capabilities remain represented without implying unshown call sequences.

Main entry points: [`server/model/monitor.js`](https://github.com/louislam/uptime-kuma/blob/master/server/model/monitor.js) (Monitor execution), [`server/database.js`](https://github.com/louislam/uptime-kuma/blob/master/server/database.js) (Database), [`server/routers/api-router.js`](https://github.com/louislam/uptime-kuma/blob/master/server/routers/api-router.js) (API routes), [`server/better-auth.ts`](https://github.com/louislam/uptime-kuma/blob/master/server/better-auth.ts) (Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_frontend["Web interface<br/>[App.vue]"]
  node_socket["Socket client<br/>[socket.js]"]
  node_api["API routes<br/>[api-router.js]"]
  node_statusroutes["Status routes"]
end

subgraph group_runtime["Monitoring runtime"]
  node_server["Server runtime<br/>[server.js]"]
  node_registry["Monitor registry"]
  node_monitors["Monitor execution<br/>[monitor.js]"]
  node_types["Monitor types"]
  node_conditions["Check conditions"]
end

subgraph group_data["Persistence and reporting"]
  node_heartbeat["Heartbeat history<br/>[heartbeat.js]"]
  node_uptime["Uptime statistics"]
  node_database[("Database<br/>[database.js]")]
  node_statuspages["Status pages<br/>[status_page.js]"]
  node_metrics["Prometheus metrics<br/>[prometheus.js]"]
end

subgraph group_identity["Identity and configuration"]
  node_auth["Authentication<br/>[better-auth.ts]"]
  node_authroutes["Auth routes"]
  node_settings["Settings<br/>[settings.js]"]
end

subgraph group_integrations["External integrations"]
  node_notify["Notification dispatch<br/>[notification.js]"]
  node_providers["Notification providers"]
end

node_operator(("Operator"))
node_targets{{"Monitored services"}}
node_notificationservices{{"Notification services"}}

node_operator -->|"configures"| node_frontend
node_frontend -->|"uses"| node_socket
node_socket -->|"authenticates"| node_auth
node_operator -.->|"manages monitors"| node_api
node_api -->|"routes to"| node_monitors
node_server -->|"initializes"| node_registry
node_registry -->|"registers"| node_types
node_monitors -.->|"executes checks"| node_types
node_monitors -->|"checks"| node_targets
node_monitors -->|"records"| node_heartbeat
node_monitors -->|"updates"| node_uptime
node_uptime -->|"reads and writes"| node_database
node_monitors -->|"alerts through"| node_notify
node_notify -.->|"dispatches"| node_providers
node_providers -->|"sends alerts"| node_notificationservices
node_api -->|"exposes"| node_metrics
node_operator -->|"views pages"| node_statusroutes
node_statusroutes -->|"reads"| node_statuspages
node_authroutes -->|"delegates"| node_auth
node_auth -->|"uses"| node_database
node_monitors -.->|"persists monitor data"| node_database
node_conditions -.->|"evaluates checks"| node_monitors
node_settings -->|"reads and writes"| node_database

click node_frontend "https://github.com/louislam/uptime-kuma/blob/master/src/App.vue"
click node_socket "https://github.com/louislam/uptime-kuma/blob/master/src/mixins/socket.js"
click node_api "https://github.com/louislam/uptime-kuma/blob/master/server/routers/api-router.js"
click node_statusroutes "https://github.com/louislam/uptime-kuma/blob/master/server/routers/status-page-router.js"
click node_server "https://github.com/louislam/uptime-kuma/blob/master/server/server.js"
click node_registry "https://github.com/louislam/uptime-kuma/blob/master/server/uptime-kuma-server.js"
click node_monitors "https://github.com/louislam/uptime-kuma/blob/master/server/model/monitor.js"
click node_types "https://github.com/louislam/uptime-kuma/tree/master/server/monitor-types"
click node_conditions "https://github.com/louislam/uptime-kuma/tree/master/server/monitor-conditions"
click node_heartbeat "https://github.com/louislam/uptime-kuma/blob/master/server/model/heartbeat.js"
click node_uptime "https://github.com/louislam/uptime-kuma/blob/master/server/uptime-calculator.js"
click node_database "https://github.com/louislam/uptime-kuma/blob/master/server/database.js"
click node_statuspages "https://github.com/louislam/uptime-kuma/blob/master/server/model/status_page.js"
click node_metrics "https://github.com/louislam/uptime-kuma/blob/master/server/prometheus.js"
click node_auth "https://github.com/louislam/uptime-kuma/blob/master/server/better-auth.ts"
click node_authroutes "https://github.com/louislam/uptime-kuma/blob/master/server/routers/better-auth-router.ts"
click node_settings "https://github.com/louislam/uptime-kuma/blob/master/server/settings.js"
click node_notify "https://github.com/louislam/uptime-kuma/blob/master/server/notification.js"
click node_providers "https://github.com/louislam/uptime-kuma/tree/master/server/notification-providers"

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_frontend,node_socket,node_api,node_statusroutes toneBlue
class node_server,node_registry,node_monitors,node_types,node_conditions toneAmber
class node_heartbeat,node_uptime,node_database,node_statuspages,node_metrics toneMint
class node_auth,node_authroutes,node_settings toneRose
class node_notify,node_providers,node_operator,node_targets,node_notificationservices toneIndigo
```

## Components

### User experience

- [Web interface](https://github.com/louislam/uptime-kuma/blob/master/src/App.vue): `src/App.vue`
- [Socket client](https://github.com/louislam/uptime-kuma/blob/master/src/mixins/socket.js): `src/mixins/socket.js`
- [API routes](https://github.com/louislam/uptime-kuma/blob/master/server/routers/api-router.js): `server/routers/api-router.js`
- [Status routes](https://github.com/louislam/uptime-kuma/blob/master/server/routers/status-page-router.js): `server/routers/status-page-router.js`

### Monitoring runtime

- [Server runtime](https://github.com/louislam/uptime-kuma/blob/master/server/server.js): `server/server.js`
- [Monitor registry](https://github.com/louislam/uptime-kuma/blob/master/server/uptime-kuma-server.js): `server/uptime-kuma-server.js`
- [Monitor execution](https://github.com/louislam/uptime-kuma/blob/master/server/model/monitor.js): `server/model/monitor.js`
- [Monitor types](https://github.com/louislam/uptime-kuma/tree/master/server/monitor-types): `server/monitor-types`
- [Check conditions](https://github.com/louislam/uptime-kuma/tree/master/server/monitor-conditions): `server/monitor-conditions`

### Persistence and reporting

- [Heartbeat history](https://github.com/louislam/uptime-kuma/blob/master/server/model/heartbeat.js): `server/model/heartbeat.js`
- [Uptime statistics](https://github.com/louislam/uptime-kuma/blob/master/server/uptime-calculator.js): `server/uptime-calculator.js`
- [Database](https://github.com/louislam/uptime-kuma/blob/master/server/database.js): `server/database.js`
- [Status pages](https://github.com/louislam/uptime-kuma/blob/master/server/model/status_page.js): `server/model/status_page.js`
- [Prometheus metrics](https://github.com/louislam/uptime-kuma/blob/master/server/prometheus.js): `server/prometheus.js`

### Identity and configuration

- [Authentication](https://github.com/louislam/uptime-kuma/blob/master/server/better-auth.ts): `server/better-auth.ts`
- [Auth routes](https://github.com/louislam/uptime-kuma/blob/master/server/routers/better-auth-router.ts): `server/routers/better-auth-router.ts`
- [Settings](https://github.com/louislam/uptime-kuma/blob/master/server/settings.js): `server/settings.js`

### External integrations

- [Notification dispatch](https://github.com/louislam/uptime-kuma/blob/master/server/notification.js): `server/notification.js`
- [Notification providers](https://github.com/louislam/uptime-kuma/tree/master/server/notification-providers): `server/notification-providers`

### Other components

- **Operator**
- **Monitored services**
- **Notification services**

## Connections

- Operator → Web interface: configures (evidence: `README.md`)
- Web interface → Socket client: uses (evidence: `src/App.vue`)
- Socket client → Authentication: authenticates
- Operator → API routes: manages monitors
- API routes → Monitor execution: routes to (evidence: `server/routers/api-router.js`)
- Server runtime → Monitor registry: initializes (evidence: `server/server.js`)
- Monitor registry → Monitor types: registers (evidence: `server/uptime-kuma-server.js`)
- Monitor execution → Monitor types: executes checks
- Monitor execution → Monitored services: checks (evidence: `README.md`)
- Monitor execution → Heartbeat history: records (evidence: `server/model/monitor.js`)
- Monitor execution → Uptime statistics: updates (evidence: `server/model/monitor.js`)
- Uptime statistics → Database: reads and writes (evidence: `server/uptime-calculator.js`)
- Monitor execution → Notification dispatch: alerts through (evidence: `server/model/monitor.js`)
- Notification dispatch → Notification providers: dispatches
- Notification providers → Notification services: sends alerts (evidence: `README.md`)
- API routes → Prometheus metrics: exposes (evidence: `server/routers/api-router.js`)
- Operator → Status routes: views pages (evidence: `README.md`)
- Status routes → Status pages: reads (evidence: `server/routers/status-page-router.js`)
- Auth routes → Authentication: delegates (evidence: `server/routers/better-auth-router.ts`)
- Authentication → Database: uses (evidence: `server/better-auth.ts`)
- Monitor execution → Database: persists monitor data
- Check conditions → Monitor execution: evaluates checks
- Settings → Database: reads and writes (evidence: `server/settings.js`)
