apps/dashboard

The dashboard app. Source under apps/dashboard/. The biggest single app in the repo by both file count and lines of code, mostly because it manages multiple coexisting schema versions for the most-used resource in Grafana.

Resource versions

The dashboard resource is exposed under dashboard.grafana.app in five versions:

• v0alpha1 — wraps the legacy v1 JSON schema as a k8s resource for backwards compatibility.
• v1 — the stable v1 schema (still the format most clients write).
• v2alpha1 — first iteration of the new v2 schema (layout-tree, scenes-style).
• v2beta1 — refined v2 schema.
• v2 — v2 GA.

Clients pick the version via the request path (/apis/dashboard.grafana.app/<version>/dashboards). The storage layer maintains canonical state in one version internally and converts on read/write.

Layout

apps/dashboard/
├── kinds/                        # CUE schemas for each version
├── pkg/apis/dashboard/v0alpha1/
├── pkg/apis/dashboard/v1/
├── pkg/apis/dashboard/v2alpha1/
├── pkg/apis/dashboard/v2beta1/
├── pkg/apis/dashboard/v2/
├── pkg/migration/conversion/     # v1 ↔ v2 conversion (huge)
├── pkg/storage/                  # Storage adapter (unified storage / legacy)
├── pkg/embeddings/               # Optional vector embeddings
└── plugin/                       # App SDK plugin manifest

Each pkg/apis/<version>/ contains:

• Hand-written register.go, types.go, conversion.go.
• Generated zz_generated.deepcopy.go, zz_generated.openapi.go, dashboard_spec_gen.go.

The OpenAPI generator outputs are the largest single Go files in the repo (>5,000 lines each).

v1 → v2 migration

apps/dashboard/pkg/migration/conversion/v1_to_v2alpha1.go is the largest hand-written Go file in the repo at ~3,150 lines. It implements the full lossless transform between:

• v1's flat panels: [] model with gridPos per panel.
• v2's layout tree (SceneObject-style nodes) with explicit grouping and hierarchy.

The reverse transform (v2 → v1) lives alongside, plus per-version step files for the smaller alpha → beta → ga transitions.

Storage

The dashboard storage adapter writes to both the legacy dashboard SQL table and the unified resource server (when the right feature flags are enabled), with the unified copy as the canonical source for v2 reads. This dual-write pattern is the bridge for the long migration.

Failure modes:

• Dual-write inconsistency — handled by an "audit" pass that compares both stores.
• Conversion errors — surfaced as Reason: ConversionFailure on the resource status.

Plugin manifest

apps/dashboard/plugin/ contains the App SDK manifest for the dashboard app — operator config, resource registration, and runtime hooks. The Grafana server imports this on startup to mount the routes.

Embeddings

apps/dashboard/pkg/embeddings/ is a recent addition (commit bda397a0070) that extracts textual embeddings from dashboards for semantic search. Optional and behind a feature flag.

Frontend counterpart

The frontend pieces that read/write these resources live in:

• public/app/features/dashboard/api/ — RTK Query slice + v1↔v2 transformers.
• public/app/features/dashboard-scene/serialization/ — v1↔v2 conversion on the client.

See Frontend / Dashboards.

See also

• Backend / Dashboards
• Backend / Unified storage