# grafana-cold-storage/oncall architecture

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

- Interactive diagram: https://gitdiagram.com/grafana-cold-storage/oncall
- Repository: https://github.com/grafana-cold-storage/oncall

## Overview

Grafana OnCall is an incident-response and on-call management application, integrated with Grafana. Its principal workflow collects alerts from monitoring systems, groups and escalates incidents according to on-call policies, then notifies responders through configured channels. Schedules, APIs, Grafana integration, and metrics are distinct supporting capabilities. The README documents the product workflow; sampled source shows route handling, model responsibilities, and selected integrations, but most runtime wiring was not sampled, so inferred workflow links are dashed and uncited.

Main entry points: [`engine/apps/public_api/views/routes.py`](https://github.com/grafana-cold-storage/oncall/blob/dev/engine/apps/public_api/views/routes.py) (Public API), [`engine/apps/base/messaging.py`](https://github.com/grafana-cold-storage/oncall/blob/dev/engine/apps/base/messaging.py) (Notification backends), [`engine/apps/alerts/models/alert_group.py`](https://github.com/grafana-cold-storage/oncall/blob/dev/engine/apps/alerts/models/alert_group.py) (Alert grouping), [`grafana-plugin/src/containers/OutgoingWebhookForm/OutgoingWebhookForm.tsx`](https://github.com/grafana-cold-storage/oncall/blob/dev/grafana-plugin/src/containers/OutgoingWebhookForm/OutgoingWebhookForm.tsx) (Grafana plugin)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_alerting["Alert intake"]
  node_integrations["Alert integrations<br/>[views.py]"]
  node_alert_channels[("Alert channels")]
  node_alerts[("Incoming alerts<br/>[alert.py]")]
  node_grouping[("Alert grouping<br/>[alert_group.py]")]
  node_filters[("Channel filters<br/>[channel_filter.py]")]
end

subgraph group_incident["Incident response"]
  node_escalation_policies[("Escalation policies")]
  node_escalation_tasks["Escalation tasks"]
  node_incident_logs[("Incident history")]
end

subgraph group_responders["On-call and notifications"]
  node_schedules[("On-call schedules")]
  node_messaging["Notification backends<br/>[messaging.py]"]
  node_slack["Slack integration"]
  node_telegram["Telegram updates<br/>[update_manager.py]"]
  node_phone["Phone notifications<br/>[phone_backend.py]"]
end

subgraph group_platform["Grafana and APIs"]
  node_api["Public API<br/>[routes.py]"]
  node_api_serializers["Route serializers<br/>[routes.py]"]
  node_permissions["API permissions<br/>[permissions.py]"]
  node_auth["Token authentication<br/>[auth.py]"]
  node_grafana_plugin["Grafana plugin"]
  node_grafana_sync["Grafana sync<br/>[sync_data.py]"]
end

subgraph group_operations["Observability"]
  node_metrics["Metrics exporter"]
  node_metric_helpers["Metric cache helpers<br/>[helpers.py]"]
  node_database[("Application database<br/>[database.py]")]
end

node_monitoring(("Monitoring systems"))
node_grafana(("Grafana"))

node_monitoring -.->|"sends alerts"| node_integrations
node_integrations -.->|"targets channels"| node_alert_channels
node_alert_channels -.->|"receives alerts"| node_alerts
node_alerts -.->|"groups alerts"| node_grouping
node_grouping -.->|"escalates incidents"| node_escalation_policies
node_escalation_policies -.->|"drives escalation"| node_escalation_tasks
node_grouping -.->|"records history"| node_incident_logs
node_schedules -.->|"provides rotations"| node_escalation_tasks
node_messaging -.->|"supports notifications"| node_slack
node_messaging -.->|"supports notifications"| node_telegram
node_messaging -.->|"supports notifications"| node_phone
node_grafana -->|"hosts plugin"| node_grafana_plugin
node_grafana_plugin -.->|"requests sync"| node_grafana_sync
node_grafana_plugin -->|"calls engine API"| node_api
node_api -->|"authenticates with"| node_auth
node_api -->|"checks permissions"| node_permissions
node_api -->|"uses serializers"| node_api_serializers
node_api -->|"queries filters"| node_filters
node_api_serializers -->|"validates and updates"| node_filters
node_metric_helpers -->|"updates metric cache"| node_metrics
node_grafana -.->|"scrapes metrics"| node_metrics

click node_integrations "https://github.com/grafana-cold-storage/oncall/blob/dev/engine/apps/integrations/views.py"
click node_alert_channels "https://github.com/grafana-cold-storage/oncall/blob/dev/engine/apps/alerts/models/alert_receive_channel.py"
click node_alerts "https://github.com/grafana-cold-storage/oncall/blob/dev/engine/apps/alerts/models/alert.py"
click node_grouping "https://github.com/grafana-cold-storage/oncall/blob/dev/engine/apps/alerts/models/alert_group.py"
click node_filters "https://github.com/grafana-cold-storage/oncall/blob/dev/engine/apps/alerts/models/channel_filter.py"
click node_api "https://github.com/grafana-cold-storage/oncall/blob/dev/engine/apps/public_api/views/routes.py"
click node_api_serializers "https://github.com/grafana-cold-storage/oncall/blob/dev/engine/apps/public_api/serializers/routes.py"
click node_permissions "https://github.com/grafana-cold-storage/oncall/blob/dev/engine/apps/api/permissions.py"
click node_auth "https://github.com/grafana-cold-storage/oncall/blob/dev/engine/apps/auth_token/auth.py"
click node_escalation_policies "https://github.com/grafana-cold-storage/oncall/blob/dev/engine/apps/alerts/models/escalation_policy.py"
click node_escalation_tasks "https://github.com/grafana-cold-storage/oncall/blob/dev/engine/apps/alerts/tasks/escalate_alert_group.py"
click node_incident_logs "https://github.com/grafana-cold-storage/oncall/blob/dev/engine/apps/alerts/models/alert_group_log_record.py"
click node_schedules "https://github.com/grafana-cold-storage/oncall/blob/dev/engine/apps/schedules/models/on_call_schedule.py"
click node_messaging "https://github.com/grafana-cold-storage/oncall/blob/dev/engine/apps/base/messaging.py"
click node_slack "https://github.com/grafana-cold-storage/oncall/blob/dev/engine/apps/slack/alert_group_slack_service.py"
click node_telegram "https://github.com/grafana-cold-storage/oncall/blob/dev/engine/apps/telegram/updates/update_manager.py"
click node_phone "https://github.com/grafana-cold-storage/oncall/blob/dev/engine/apps/phone_notifications/phone_backend.py"
click node_grafana_plugin "https://github.com/grafana-cold-storage/oncall/blob/dev/grafana-plugin/src/containers/OutgoingWebhookForm/OutgoingWebhookForm.tsx"
click node_grafana_sync "https://github.com/grafana-cold-storage/oncall/blob/dev/engine/apps/grafana_plugin/sync_data.py"
click node_metrics "https://github.com/grafana-cold-storage/oncall/blob/dev/engine/apps/metrics_exporter/metrics_cache_manager.py"
click node_metric_helpers "https://github.com/grafana-cold-storage/oncall/blob/dev/engine/apps/metrics_exporter/helpers.py"
click node_database "https://github.com/grafana-cold-storage/oncall/blob/dev/engine/common/database.py"

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_integrations,node_alert_channels,node_alerts,node_grouping,node_filters toneBlue
class node_escalation_policies,node_escalation_tasks,node_incident_logs toneAmber
class node_schedules,node_messaging,node_slack,node_telegram,node_phone toneMint
class node_api,node_api_serializers,node_permissions,node_auth,node_grafana_plugin,node_grafana_sync toneRose
class node_metrics,node_metric_helpers,node_database,node_monitoring,node_grafana toneIndigo
```

## Components

### Alert intake

- [Alert integrations](https://github.com/grafana-cold-storage/oncall/blob/dev/engine/apps/integrations/views.py): `engine/apps/integrations/views.py`
- [Alert channels](https://github.com/grafana-cold-storage/oncall/blob/dev/engine/apps/alerts/models/alert_receive_channel.py): `engine/apps/alerts/models/alert_receive_channel.py`
- [Incoming alerts](https://github.com/grafana-cold-storage/oncall/blob/dev/engine/apps/alerts/models/alert.py): `engine/apps/alerts/models/alert.py`
- [Alert grouping](https://github.com/grafana-cold-storage/oncall/blob/dev/engine/apps/alerts/models/alert_group.py): `engine/apps/alerts/models/alert_group.py`
- [Channel filters](https://github.com/grafana-cold-storage/oncall/blob/dev/engine/apps/alerts/models/channel_filter.py): `engine/apps/alerts/models/channel_filter.py`

### Incident response

- [Escalation policies](https://github.com/grafana-cold-storage/oncall/blob/dev/engine/apps/alerts/models/escalation_policy.py): `engine/apps/alerts/models/escalation_policy.py`
- [Escalation tasks](https://github.com/grafana-cold-storage/oncall/blob/dev/engine/apps/alerts/tasks/escalate_alert_group.py): `engine/apps/alerts/tasks/escalate_alert_group.py`
- [Incident history](https://github.com/grafana-cold-storage/oncall/blob/dev/engine/apps/alerts/models/alert_group_log_record.py): `engine/apps/alerts/models/alert_group_log_record.py`

### On-call and notifications

- [On-call schedules](https://github.com/grafana-cold-storage/oncall/blob/dev/engine/apps/schedules/models/on_call_schedule.py): `engine/apps/schedules/models/on_call_schedule.py`
- [Notification backends](https://github.com/grafana-cold-storage/oncall/blob/dev/engine/apps/base/messaging.py): `engine/apps/base/messaging.py`
- [Slack integration](https://github.com/grafana-cold-storage/oncall/blob/dev/engine/apps/slack/alert_group_slack_service.py): `engine/apps/slack/alert_group_slack_service.py`
- [Telegram updates](https://github.com/grafana-cold-storage/oncall/blob/dev/engine/apps/telegram/updates/update_manager.py): `engine/apps/telegram/updates/update_manager.py`
- [Phone notifications](https://github.com/grafana-cold-storage/oncall/blob/dev/engine/apps/phone_notifications/phone_backend.py): `engine/apps/phone_notifications/phone_backend.py`

### Grafana and APIs

- [Public API](https://github.com/grafana-cold-storage/oncall/blob/dev/engine/apps/public_api/views/routes.py): `engine/apps/public_api/views/routes.py`
- [Route serializers](https://github.com/grafana-cold-storage/oncall/blob/dev/engine/apps/public_api/serializers/routes.py): `engine/apps/public_api/serializers/routes.py`
- [API permissions](https://github.com/grafana-cold-storage/oncall/blob/dev/engine/apps/api/permissions.py): `engine/apps/api/permissions.py`
- [Token authentication](https://github.com/grafana-cold-storage/oncall/blob/dev/engine/apps/auth_token/auth.py): `engine/apps/auth_token/auth.py`
- [Grafana plugin](https://github.com/grafana-cold-storage/oncall/blob/dev/grafana-plugin/src/containers/OutgoingWebhookForm/OutgoingWebhookForm.tsx): `grafana-plugin/src/containers/OutgoingWebhookForm/OutgoingWebhookForm.tsx`
- [Grafana sync](https://github.com/grafana-cold-storage/oncall/blob/dev/engine/apps/grafana_plugin/sync_data.py): `engine/apps/grafana_plugin/sync_data.py`

### Observability

- [Metrics exporter](https://github.com/grafana-cold-storage/oncall/blob/dev/engine/apps/metrics_exporter/metrics_cache_manager.py): `engine/apps/metrics_exporter/metrics_cache_manager.py`
- [Metric cache helpers](https://github.com/grafana-cold-storage/oncall/blob/dev/engine/apps/metrics_exporter/helpers.py): `engine/apps/metrics_exporter/helpers.py`
- [Application database](https://github.com/grafana-cold-storage/oncall/blob/dev/engine/common/database.py): `engine/common/database.py`

### Other components

- **Monitoring systems**
- **Grafana**

## Connections

- Monitoring systems → Alert integrations: sends alerts
- Alert integrations → Alert channels: targets channels
- Alert channels → Incoming alerts: receives alerts
- Incoming alerts → Alert grouping: groups alerts
- Alert grouping → Escalation policies: escalates incidents
- Escalation policies → Escalation tasks: drives escalation
- Alert grouping → Incident history: records history
- On-call schedules → Escalation tasks: provides rotations
- Notification backends → Slack integration: supports notifications
- Notification backends → Telegram updates: supports notifications
- Notification backends → Phone notifications: supports notifications
- Grafana → Grafana plugin: hosts plugin (evidence: `README.md`)
- Grafana plugin → Grafana sync: requests sync
- Grafana plugin → Public API: calls engine API (evidence: `README.md`)
- Public API → Token authentication: authenticates with (evidence: `engine/apps/public_api/views/routes.py`)
- Public API → API permissions: checks permissions (evidence: `engine/apps/public_api/views/routes.py`)
- Public API → Route serializers: uses serializers (evidence: `engine/apps/public_api/views/routes.py`)
- Public API → Channel filters: queries filters (evidence: `engine/apps/public_api/views/routes.py`)
- Route serializers → Channel filters: validates and updates (evidence: `engine/apps/public_api/serializers/routes.py`)
- Metric cache helpers → Metrics exporter: updates metric cache (evidence: `engine/apps/metrics_exporter/metrics_cache_manager.py`)
- Grafana → Metrics exporter: scrapes metrics