# prometheus/alertmanager architecture

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

- Interactive diagram: https://gitdiagram.com/prometheus/alertmanager
- Repository: https://github.com/prometheus/alertmanager

## Overview

##### Project type and purpose
- Alertmanager is a full-stack, stateless (but clustered) alert‐routing and notification service written in Go.
- It ingests alerts (typically from Prometheus), applies grouping, silencing, and inhibition rules, and dispatches notifications via various receivers (email, Slack, PagerDuty, webhooks, etc.).
- It exposes a REST/OpenAPI v2 API, a web UI (Elm+React), a command‐line client (amtool), and a metrics endpoint.

##### File structure
- cmd/alertmanager → the main HTTP server binary
- cmd/amtool → the CLI tool
- api/… → auto‐generated HTTP handlers and client code for the API v2
- cluster/… → gossip-based peer communication and replication
- config/… → parsing the YAML routing, inhibition, silences, and receiver configs
- store/…, silence/…, dispatch/… → in-memory stores, dispatch logic (grouping & routing), silence engine
- notify/… → individual notifier adapters (email, Slack, PagerDuty, webhook, etc.)
- template/… → Go template rendering for notification payloads
- ui/app (Elm) + ui/react-app (React) → two separate web UIs
- asset/ & embed → static asset bundling into the Go binary
- test/… & examples/… → acceptance tests and sample configs

##### README for additional insights
- README describes alert flow, clustering flags, high-availability requirements, and the OpenAPI contract
– HTTP ingress → API → core services → dispatch → notifiers
– Cluster messaging between peers
– CLI & web UI calling into the API

##### Components & interactions
A. Ingress Layer
1. HTTP Server (cmd/alertmanager)
– Exposes endpoints:
- /api/v2 (OpenAPI handlers in api/v2/restapi)
- /metrics (Prometheus metrics via api/metrics)
- Web UI assets (embedded Elm and React static files)
2. CLI Client (amtool)
– Calls the same HTTP API (/api/v2/*) over HTTP
B. Core Processing
1. Config Loader (config/)
– Parses YAML into Route Tree, Inhibition Rules, Receivers
2. Store
– Alerts Store (in‐memory, store/)
– Silences Store (in‐memory, silence/)
3. Dispatch Engine (dispatch/)
– Applies group_by and routes to build AlertGroups
– Checks silences & inhibition rules
4. Template Renderer (template/)
– Renders notification payloads (email HTML, JSON, Slack markdown)
C. Notification Layer
– Notify Adapters (notify/email, notify/slack, notify/pagerduty, etc.)
– Each adapter implements a common interface (notify/notify.go)
D. Cluster Subsystem (cluster/)
– Gossip protocol over UDP/TCP
– Connection pooling, TLS transport, delegate messages
– Replicates state (alerts, silences, etc.) across peers
E. Web UIs
1. Elm-based UI (ui/app) served as static assets
2. React-based UI (ui/react-app) also embedded and served
F. External Integrations
– Prometheus or any alerting client POSTs to /api/v2/alerts
– Prometheus scrapes /metrics
– External notifiers (email servers, Slack endpoints, PagerDuty API)

##### Architectural patterns & principles
- Layered architecture: Ingress → Core → Dispatch → Notifier
- Modular adapters for every notifier in notify/
- In-memory state replication via gossip for HA (distributed state)
- OpenAPI‐first API generation (api/v2/openapi.yaml + Go-Swagger)
- Embedded static assets (asset/ + Promu + go:embed)
- Separation of concerns: config parsing, business logic, transport

##### Be very detailed
- Inside “Core”, show sub-modules: Config Parser, Grouping Engine, Silence Engine, Inhibition Engine
- Static asset embedding (asset/ and ui/*) flowing into the HTTP server binary

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Ingress Layer
  subgraph "Ingress Layer"
    direction TB
    HTTP_Server["HTTP Server\n(cmd/alertmanager)"]:::ingress
    API_Handlers["OpenAPI v2 API Handlers"]:::ingress
    API_Client["API Client & Models"]:::ingress
    API_Models["API Models"]:::ingress
    Metrics_Endpoint["Metrics Endpoint"]:::ingress
    Static_Assets["Static Assets (Elm & React)"]:::ingress
    Web_Embed["UI Embed Code (ui/web.go)"]:::ingress
    CLI_Client["CLI Client (amtool)"]:::ingress
  end

  %% Core Processing
  subgraph "Core Processing"
    direction TB
    Config_Loader["Config Loader"]:::core
    Alerts_Store["Alerts Store (in-memory)"]:::core
    Silences_Store["Silences Store (in-memory)"]:::core
    Dispatch_Engine["Dispatch Engine"]:::core
    Template_Renderer["Template Renderer"]:::core
  end

  %% Notification Layer
  subgraph "Notification Layer"
    direction TB
    Notification_Adapters["Notifier Adapters"]:::notify
  end

  %% Cluster Subsystem
  subgraph "Cluster Subsystem"
    direction TB
    Cluster_Subsystem["Cluster Subsystem (gossip)"]:::cluster
  end

  %% External Systems
  subgraph "External Integrations"
    direction TB
    Prometheus["Prometheus"]:::external
    Prom_Scrape["Prometheus Scrape"]:::external
    External_Notifiers["External Notifiers\n(email, Slack, PagerDuty)"]:::external
    Browsers["Web Browsers"]:::external
  end

  %% Connections
  Prometheus -->|HTTP/JSON| HTTP_Server
  CLI_Client -->|HTTP/JSON| HTTP_Server
  Browsers -->|HTTP| Static_Assets
  Browsers -->|HTTP/API| API_Handlers

  HTTP_Server -->|routes to| API_Handlers
  HTTP_Server -->|serves| Static_Assets
  HTTP_Server -->|calls| Metrics_Endpoint
  HTTP_Server -->|static embed via| Web_Embed

  HTTP_Server -->|loads config| Config_Loader
  Config_Loader --> Alerts_Store
  Config_Loader --> Silences_Store

  Alerts_Store --> Dispatch_Engine
  Silences_Store --> Dispatch_Engine
  Dispatch_Engine --> Template_Renderer
  Template_Renderer --> Notification_Adapters

  Notification_Adapters -->|SMTP, Webhook, HTTPS| External_Notifiers

  HTTP_Server -->|gossip HTTP| Cluster_Subsystem
  Cluster_Subsystem -->|state replication| Alerts_Store
  Cluster_Subsystem --> Silences_Store

  Prom_Scrape -->|pull metrics| Metrics_Endpoint

  %% Click Events
  click HTTP_Server "https://github.com/prometheus/alertmanager/blob/main/cmd/alertmanager/main.go"
  click API_Handlers "https://github.com/prometheus/alertmanager/tree/main/api/v2/restapi/"
  click API_Client "https://github.com/prometheus/alertmanager/tree/main/api/v2/client/"
  click API_Models "https://github.com/prometheus/alertmanager/tree/main/api/v2/models/"
  click Metrics_Endpoint "https://github.com/prometheus/alertmanager/blob/main/api/metrics/metrics.go"
  click Static_Assets "https://github.com/prometheus/alertmanager/tree/main/asset/"
  click Web_Embed "https://github.com/prometheus/alertmanager/blob/main/ui/web.go"
  click CLI_Client "https://github.com/prometheus/alertmanager/blob/main/cmd/amtool/main.go"
  click Config_Loader "https://github.com/prometheus/alertmanager/blob/main/config/config.go"
  click Alerts_Store "https://github.com/prometheus/alertmanager/blob/main/store/store.go"
  click Silences_Store "https://github.com/prometheus/alertmanager/blob/main/silence/silence.go"
  click Dispatch_Engine "https://github.com/prometheus/alertmanager/blob/main/dispatch/dispatch.go"
  click Template_Renderer "https://github.com/prometheus/alertmanager/blob/main/template/template.go"
  click Notification_Adapters "https://github.com/prometheus/alertmanager/tree/main/notify/"
  click Cluster_Subsystem "https://github.com/prometheus/alertmanager/blob/main/cluster/cluster.go"
  click Elm_UI "https://github.com/prometheus/alertmanager/tree/main/ui/app/"
  click React_UI "https://github.com/prometheus/alertmanager/tree/main/ui/react-app/"

  %% Styles
  classDef ingress fill:#cce5ff,stroke:#3399ff
  classDef core fill:#d4edda,stroke:#28a745
  classDef notify fill:#fff3cd,stroke:#ffcd39
  classDef cluster fill:#e2d5f9,stroke:#9c27b0
  classDef external fill:#f0f0f0,stroke:#999
```
