louislam/uptime-kuma

A fancy self-hosted monitoring tool

84,695 stars JavaScript 10 components 7 connections

Self-hosted monitoring tool with Vue frontend and Node.js Express backend

Monitors run background checks, store heartbeats in database, trigger notifications on status changes, and push real-time updates to connected clients via WebSocket

Under the hood, the system uses 3 feedback loops, 4 data pools, 5 control points to manage its runtime behavior.

Structural Verdict

A 10-component dashboard with 7 connections. 342 files analyzed. Well-connected — clear data flow between components.

How Data Flows Through the System

Monitors run background checks, store heartbeats in database, trigger notifications on status changes, and push real-time updates to connected clients via WebSocket

Monitor Execution — Background jobs execute monitor checks using MonitorType implementations
Heartbeat Storage — Monitor results stored as heartbeat records in SQLite/MariaDB database
Condition Evaluation — Custom monitor conditions evaluated using ConditionExpression system
Notification Dispatch — Status changes trigger notifications via configured NotificationProvider instances
Real-time Updates — Monitor status and heartbeat data pushed to connected clients via Socket.IO

System Behavior

How the system actually operates at runtime — where data accumulates, what loops, what waits, and what controls what.

Data Pools

monitor table (database)
Monitor configurations and settings

heartbeat table (database)
Time-series monitoring results and uptime data

setting table (database)
Application configuration and user preferences

Settings cache (in-memory)
Cached configuration values with TTL

Feedback Loops

Monitor retry logic (retry, balancing) — Trigger: Monitor check failure. Action: Retry with exponential backoff. Exit: Success or max retries reached.
Cache cleanup (polling, balancing) — Trigger: 60-second timer. Action: Remove expired cache entries. Exit: Never stops.
WebSocket reconnection (retry, balancing) — Trigger: Connection loss. Action: Attempt reconnection. Exit: Successful connection.

Delays & Async Processing

Monitor intervals (scheduled-job, ~20 seconds to 24 days) — Time between monitor checks
Cache TTL (cache-ttl, ~60 seconds) — Settings changes may take up to 1 minute to reflect
Database migration (async-processing, ~variable) — Application startup blocked during schema updates

Control Points

UPTIME_KUMA_HOST (env-var) — Controls: Server bind address
UPTIME_KUMA_PORT (env-var) — Controls: Server port number. Default: 3001
NODE_ENV (env-var) — Controls: Development vs production mode
Monitor interval (runtime-toggle) — Controls: Check frequency per monitor. Default: 20 seconds default
Demo mode (runtime-toggle) — Controls: Read-only demonstration mode. Default: false

Technology Stack

Vue.js (framework)
Frontend framework with SPA

Express (framework)
HTTP server and API

Socket.IO (library)
Real-time WebSocket communication

SQLite/MariaDB (database)
Primary data storage

RedBean ORM (library)
Database abstraction layer

Vite (build)
Frontend build tool

Playwright (testing)
E2E testing framework

Docker (infra)
Containerization and deployment

axios (library)
HTTP client for monitoring

dayjs (library)
Date/time manipulation

Key Components

UptimeKumaServer (class) — Main server singleton that manages monitors, WebSocket connections, and HTTP server server/uptime-kuma-server.js
MonitorType (class) — Base class for different monitoring types (HTTP, TCP, ping, etc.) server/monitor-types/monitor-type.js
NotificationProvider (class) — Base class for sending alerts via Discord, Slack, email, and 90+ other services server/notification-providers/notification-provider.js
Database (class) — Database management with SQLite/MariaDB support and migration system server/database.js
Settings (class) — Configuration management with caching for application settings server/settings.js
util (utility) — Shared utility functions for frontend and backend including logging and constants src/util.js
server config (config) — Server configuration from environment variables and command line arguments server/config.js
socket-handlers (module) — WebSocket message handlers for real-time client-server communication server/socket-handlers/
ConditionExpression (class) — Evaluates custom monitor conditions with logical operators and grouping server/monitor-conditions/expression.js
notification components (component) — Vue components for configuring 90+ notification providers src/components/notifications/index.js

Sub-Modules

Push Examples (independence: high)
Standalone client examples for push-based monitoring in different languages

Configuration

compose.yaml (yaml)

services.uptime-kuma.image (string, unknown) — default: louislam/uptime-kuma:2
services.uptime-kuma.restart (string, unknown) — default: unless-stopped
services.uptime-kuma.volumes (array, unknown) — default: ./data:/app/data
services.uptime-kuma.ports (array, unknown) — default: 3001:3001

Explore the interactive analysis

See the full architecture map, data flow, and code patterns visualization.

Analyze on CodeSea

Related Dashboard Repositories

Frequently Asked Questions

What is uptime-kuma used for?

Self-hosted monitoring tool with Vue frontend and Node.js Express backend louislam/uptime-kuma is a 10-component dashboard written in JavaScript. Well-connected — clear data flow between components. The codebase contains 342 files.

How is uptime-kuma architected?

uptime-kuma is organized into 4 architecture layers: Frontend, API & WebSocket, Monitor Engine, Database. Well-connected — clear data flow between components. This layered structure enables tight integration between components.

How does data flow through uptime-kuma?

Data moves through 5 stages: Monitor Execution → Heartbeat Storage → Condition Evaluation → Notification Dispatch → Real-time Updates. Monitors run background checks, store heartbeats in database, trigger notifications on status changes, and push real-time updates to connected clients via WebSocket This pipeline design reflects a complex multi-stage processing system.

What technologies does uptime-kuma use?

The core stack includes Vue.js (Frontend framework with SPA), Express (HTTP server and API), Socket.IO (Real-time WebSocket communication), SQLite/MariaDB (Primary data storage), RedBean ORM (Database abstraction layer), Vite (Frontend build tool), and 4 more. This broad technology surface reflects a mature project with many integration points.

What system dynamics does uptime-kuma have?

uptime-kuma exhibits 4 data pools (monitor table, heartbeat table), 3 feedback loops, 5 control points, 3 delays. The feedback loops handle retry and polling. These runtime behaviors shape how the system responds to load, failures, and configuration changes.

What design patterns does uptime-kuma use?

5 design patterns detected: Plugin Architecture, Singleton Server, WebSocket Communication, ORM with Migrations, Configuration Caching.

Analyzed on March 31, 2026 by CodeSea. Written by Karolina Sarna.