Dashboards (backend)

Backend handling of dashboards is currently in transition: the long-lived service in pkg/services/dashboards/ coexists with the new app-platform implementation under apps/dashboard/. Both speak the same JSON model on the wire.

Legacy service: pkg/services/dashboards/

pkg/services/dashboards/
├── dashboards.go            # Service interface
├── service/                 # Implementation
├── database/                # SQL queries (xorm)
├── manager/                 # Higher-level manager glue
├── models/                  # Persistence + DTO Go structs
└── accesscontrol/           # Dashboard-permission helpers

This service handles CRUD, save validation (folder ID, title length, version conflict), and version history. Permissions are checked through pkg/services/accesscontrol/ using the dashboards:read|write|create|delete actions and the dashboards:uid:<uid> and folders:uid:<uid> scopes.

Folders

Folders are a separate domain in pkg/services/folder/. They are containers for dashboards (and increasingly other resources via app-platform). Folder hierarchy and permissions are the primary unit of access control — the dashboard's permission falls back to its parent folder unless overridden.

• Service: pkg/services/folder/folder.go
• App: apps/folder/ (k8s-style resource)

Library elements and panels

Reusable panels are stored in pkg/services/libraryelements/. Library panels are referenced from dashboards by UID. The legacy "library panels" service in pkg/services/librarypanels/ is the original (panel-only) variant; library elements is the generic version.

Dashboard versioning

Every save creates a new dashboard version row. pkg/services/dashboardversion/ exposes the history endpoints and a "restore version" operation. Version retention is configurable via [dashboards] versions_to_keep.

Snapshots

pkg/services/dashboardsnapshots/ stores rendered, point-in-time copies of a dashboard with embedded data, used for sharing without granting access to the source data. External snapshots can be pushed to https://snapshots.raintank.io (or a self-hosted instance) when configured.

Public dashboards

pkg/services/publicdashboards/ wraps a dashboard in an unauthenticated, token-gated proxy. The proxy strips PII, restricts editing, and exposes a separate URL space.

App-platform dashboards: apps/dashboard/

apps/dashboard/ is the new home of the dashboard resource. It exposes Kubernetes-style endpoints under /apis/dashboard.grafana.app/<version>/.

apps/dashboard/
├── pkg/apis/dashboard/v0alpha1/    # Compatibility schema (v0)
├── pkg/apis/dashboard/v1/          # Stable v1 schema
├── pkg/apis/dashboard/v2alpha1/    # Newer v2 spec (alpha)
├── pkg/apis/dashboard/v2beta1/     # Newer v2 spec (beta)
├── pkg/apis/dashboard/v2/          # v2 GA
├── pkg/migration/                  # v1 ↔ v2 conversion
├── pkg/storage/                    # Storage adapter
└── kinds/                          # CUE schemas (source of truth)

The conversion in apps/dashboard/pkg/migration/conversion/v1_to_v2alpha1.go is the single largest non-generated Go file in the repo (>3,000 lines) — it implements the full lossless transform between the legacy panels[] model and the new layout-tree-based v2 model.

The schema versions coexist on the wire: clients can opt into a specific version via the API path, and the storage layer transparently converts on read.

Save flow

sequenceDiagram
    participant UI as Dashboard SPA
    participant API as pkg/api/dashboard.go
    participant Svc as dashboards.Service
    participant ACL as accesscontrol
    participant Store as sqlstore
    participant Live as live channel

    UI->>API: POST /api/dashboards/db
    API->>ACL: Authorize(dashboards:write or :create)
    API->>Svc: SaveDashboard(cmd)
    Svc->>Svc: Validate (title, folder, version)
    Svc->>Store: Insert/Update + new version row
    Store-->>Svc: dashboard
    Svc->>Live: publish change event
    API-->>UI: { uid, version, slug }

The Live publish step lets other users currently viewing the dashboard see the new version (or a "dashboard updated" toast) in real time — see Live.

Provisioned dashboards

Dashboards on disk under provisioning/dashboards/ are loaded by pkg/services/provisioning/ at startup and on file change. Provisioned dashboards are read-only from the UI to prevent drift.

Key source files

File	Purpose
pkg/api/dashboard.go	HTTP handlers (/api/dashboards/*)
pkg/services/dashboards/dashboards.go	Service interface
pkg/services/dashboards/service/	Implementation
pkg/services/dashboards/database/	SQL access
pkg/services/folder/folder.go	Folder service
pkg/services/dashboardversion/	Version history
pkg/services/publicdashboards/	Public dashboards
apps/dashboard/	App-platform implementation
apps/folder/	App-platform folder resource

Frontend counterpart

The dashboard rendering and editing UI lives in public/app/features/dashboard/ (legacy) and public/app/features/dashboard-scene/ (the new Scenes-based runtime). See Frontend / Dashboards.