# vitaliandrushkevich/pulse architecture

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

- Interactive diagram: https://gitdiagram.com/vitaliandrushkevich/pulse
- Repository: https://github.com/vitaliandrushkevich/pulse

## Overview

Pulse is a self-hosted uptime-monitoring platform: users configure monitors and notification rules through the web UI or REST API, then inspect live status, history, incidents, and alerts. The scheduler dispatches bounded checks to protocol-specific workers; results feed time-series storage and the WebSocket hub, while notification dispatch evaluates state changes and delivers alerts. The MCP server provides a separate AI-assistant entry point to the Pulse API. Unsampled feature links reflect README documentation; source-specific links cite excerpts or indexed references.

Main entry points: [`backend/internal/api/router.go`](https://github.com/vitaliandrushkevich/pulse/blob/main/backend/internal/api/router.go) (HTTP router), [`backend/internal/monitor`](https://github.com/vitaliandrushkevich/pulse/tree/main/backend/internal/monitor) (Protocol checkers), [`frontend/src/routes/+page.svelte`](https://github.com/vitaliandrushkevich/pulse/blob/main/frontend/src/routes/%2Bpage.svelte) (Dashboard), [`backend/internal/monitor/scheduler.go`](https://github.com/vitaliandrushkevich/pulse/blob/main/backend/internal/monitor/scheduler.go) (Check scheduler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and access"]
  node_router["HTTP router<br/>[router.go]"]
  node_handlers["REST handlers"]
  node_auth["Authentication<br/>[auth.go]"]
  node_metrics["Prometheus metrics<br/>[prometheus.go]"]
end

subgraph group_monitoring["Monitoring engine"]
  node_scheduler["Check scheduler<br/>[scheduler.go]"]
  node_checkers["Protocol checkers"]
  node_normalization["Target normalization<br/>[normalize.go]"]
end

subgraph group_data["State and delivery"]
  node_postgres[("PostgreSQL state")]
  node_timescale[("Time-series store<br/>[store.go]")]
  node_hub["WebSocket hub<br/>[hub.go]"]
  node_notifications["Alert dispatch<br/>[dispatcher.go]"]
  node_delivery["Email and webhook"]
end

subgraph group_web["Web application"]
  node_frontend["Embedded frontend<br/>[frontend.go]"]
  node_dashboard["Dashboard<br/>[+page.svelte]"]
  node_monitor_ui["Monitor views<br/>[+page.svelte]"]
  node_insights["Dashboard insights"]
end

subgraph group_mcp["MCP integration"]
  node_mcp_server["MCP server<br/>[server.go]"]
  node_mcp_tools["MCP tools"]
  node_pulse_client["Pulse API client<br/>[http_client.go]"]
end

node_operator(("Operator"))
node_assistant(("AI assistant"))

node_operator -->|"uses API"| node_router
node_router -->|"routes requests"| node_handlers
node_router -->|"protects routes"| node_auth
node_router -->|"exposes metrics"| node_metrics
node_router -->|"serves assets"| node_frontend
node_handlers -.->|"reads and writes"| node_postgres
node_scheduler -->|"dispatches checks"| node_checkers
node_checkers -->|"persists results"| node_timescale
node_checkers -->|"broadcasts results"| node_hub
node_hub -->|"sends patches"| node_dashboard
node_dashboard -->|"renders"| node_insights
node_operator -->|"views status"| node_dashboard
node_operator -->|"manages monitors"| node_monitor_ui
node_notifications -->|"delivers alerts"| node_delivery
node_scheduler -->|"evaluates transitions"| node_notifications
node_assistant -->|"invokes tools"| node_mcp_server
node_mcp_server -->|"registers tools"| node_mcp_tools
node_mcp_tools -->|"calls API"| node_pulse_client
node_pulse_client -.->|"sends requests"| node_router

click node_router "https://github.com/vitaliandrushkevich/pulse/blob/main/backend/internal/api/router.go"
click node_handlers "https://github.com/vitaliandrushkevich/pulse/tree/main/backend/internal/api/handlers"
click node_auth "https://github.com/vitaliandrushkevich/pulse/blob/main/backend/internal/api/middleware/auth.go"
click node_metrics "https://github.com/vitaliandrushkevich/pulse/blob/main/backend/internal/metrics/prometheus.go"
click node_scheduler "https://github.com/vitaliandrushkevich/pulse/blob/main/backend/internal/monitor/scheduler.go"
click node_checkers "https://github.com/vitaliandrushkevich/pulse/tree/main/backend/internal/monitor"
click node_normalization "https://github.com/vitaliandrushkevich/pulse/blob/main/backend/internal/target/normalize.go"
click node_postgres "https://github.com/vitaliandrushkevich/pulse/tree/main/backend/internal/store/postgres"
click node_timescale "https://github.com/vitaliandrushkevich/pulse/blob/main/backend/internal/store/timescale/store.go"
click node_hub "https://github.com/vitaliandrushkevich/pulse/blob/main/backend/internal/hub/hub.go"
click node_notifications "https://github.com/vitaliandrushkevich/pulse/blob/main/backend/internal/notification/dispatcher.go"
click node_delivery "https://github.com/vitaliandrushkevich/pulse/tree/main/backend/internal/notification"
click node_frontend "https://github.com/vitaliandrushkevich/pulse/blob/main/backend/internal/frontend/frontend.go"
click node_dashboard "https://github.com/vitaliandrushkevich/pulse/blob/main/frontend/src/routes/%2Bpage.svelte"
click node_monitor_ui "https://github.com/vitaliandrushkevich/pulse/blob/main/frontend/src/routes/monitors/%5Bid%5D/%2Bpage.svelte"
click node_insights "https://github.com/vitaliandrushkevich/pulse/blob/main/frontend/src/components/dashboard/InsightsPanel.svelte"
click node_mcp_server "https://github.com/vitaliandrushkevich/pulse/blob/main/mcp/internal/server/server.go"
click node_mcp_tools "https://github.com/vitaliandrushkevich/pulse/tree/main/mcp/internal/tools"
click node_pulse_client "https://github.com/vitaliandrushkevich/pulse/blob/main/mcp/internal/pulseapi/http_client.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_handlers,node_auth,node_metrics toneBlue
class node_scheduler,node_checkers,node_normalization toneAmber
class node_postgres,node_timescale,node_hub,node_notifications,node_delivery toneMint
class node_frontend,node_dashboard,node_monitor_ui,node_insights toneRose
class node_mcp_server,node_mcp_tools,node_pulse_client,node_operator,node_assistant toneIndigo
```

## Components

### API and access

- [HTTP router](https://github.com/vitaliandrushkevich/pulse/blob/main/backend/internal/api/router.go): `backend/internal/api/router.go`
- [REST handlers](https://github.com/vitaliandrushkevich/pulse/tree/main/backend/internal/api/handlers): `backend/internal/api/handlers`
- [Authentication](https://github.com/vitaliandrushkevich/pulse/blob/main/backend/internal/api/middleware/auth.go): `backend/internal/api/middleware/auth.go`
- [Prometheus metrics](https://github.com/vitaliandrushkevich/pulse/blob/main/backend/internal/metrics/prometheus.go): `backend/internal/metrics/prometheus.go`

### Monitoring engine

- [Check scheduler](https://github.com/vitaliandrushkevich/pulse/blob/main/backend/internal/monitor/scheduler.go): `backend/internal/monitor/scheduler.go`
- [Protocol checkers](https://github.com/vitaliandrushkevich/pulse/tree/main/backend/internal/monitor): `backend/internal/monitor`
- [Target normalization](https://github.com/vitaliandrushkevich/pulse/blob/main/backend/internal/target/normalize.go): `backend/internal/target/normalize.go`

### State and delivery

- [PostgreSQL state](https://github.com/vitaliandrushkevich/pulse/tree/main/backend/internal/store/postgres): `backend/internal/store/postgres`
- [Time-series store](https://github.com/vitaliandrushkevich/pulse/blob/main/backend/internal/store/timescale/store.go): `backend/internal/store/timescale/store.go`
- [WebSocket hub](https://github.com/vitaliandrushkevich/pulse/blob/main/backend/internal/hub/hub.go): `backend/internal/hub/hub.go`
- [Alert dispatch](https://github.com/vitaliandrushkevich/pulse/blob/main/backend/internal/notification/dispatcher.go): `backend/internal/notification/dispatcher.go`
- [Email and webhook](https://github.com/vitaliandrushkevich/pulse/tree/main/backend/internal/notification): `backend/internal/notification`

### Web application

- [Embedded frontend](https://github.com/vitaliandrushkevich/pulse/blob/main/backend/internal/frontend/frontend.go): `backend/internal/frontend/frontend.go`
- [Dashboard](https://github.com/vitaliandrushkevich/pulse/blob/main/frontend/src/routes/%2Bpage.svelte): `frontend/src/routes/+page.svelte`
- [Monitor views](https://github.com/vitaliandrushkevich/pulse/blob/main/frontend/src/routes/monitors/%5Bid%5D/%2Bpage.svelte): `frontend/src/routes/monitors/[id]/+page.svelte`
- [Dashboard insights](https://github.com/vitaliandrushkevich/pulse/blob/main/frontend/src/components/dashboard/InsightsPanel.svelte): `frontend/src/components/dashboard/InsightsPanel.svelte`

### MCP integration

- [MCP server](https://github.com/vitaliandrushkevich/pulse/blob/main/mcp/internal/server/server.go): `mcp/internal/server/server.go`
- [MCP tools](https://github.com/vitaliandrushkevich/pulse/tree/main/mcp/internal/tools): `mcp/internal/tools`
- [Pulse API client](https://github.com/vitaliandrushkevich/pulse/blob/main/mcp/internal/pulseapi/http_client.go): `mcp/internal/pulseapi/http_client.go`

### Other components

- **Operator**
- **AI assistant**

## Connections

- Operator → HTTP router: uses API
- HTTP router → REST handlers: routes requests (evidence: `backend/internal/api/router.go`)
- HTTP router → Authentication: protects routes (evidence: `backend/internal/api/router.go`)
- HTTP router → Prometheus metrics: exposes metrics (evidence: `backend/internal/api/router.go`)
- HTTP router → Embedded frontend: serves assets (evidence: `backend/internal/api/router.go`)
- REST handlers → PostgreSQL state: reads and writes
- Check scheduler → Protocol checkers: dispatches checks
- Protocol checkers → Time-series store: persists results
- Protocol checkers → WebSocket hub: broadcasts results
- WebSocket hub → Dashboard: sends patches
- Dashboard → Dashboard insights: renders (evidence: `frontend/src/routes/+page.svelte`)
- Operator → Dashboard: views status
- Operator → Monitor views: manages monitors
- Alert dispatch → Email and webhook: delivers alerts
- Check scheduler → Alert dispatch: evaluates transitions
- AI assistant → MCP server: invokes tools
- MCP server → MCP tools: registers tools (evidence: `mcp/internal/server/server.go`)
- MCP tools → Pulse API client: calls API (evidence: `mcp/internal/tools/create_monitor.go`)
- Pulse API client → HTTP router: sends requests
