Apps

The apps/ directory holds Kubernetes-style API modules built on the Grafana App SDK. Each app is its own Go module that declares one or more kinds (resource types) in CUE and exposes them via the apiserver under /apis/<group>/<version>/<resource>.

This is the new home for resource-style backend code. Older code lives in pkg/services/ — most apps coexist with their legacy counterparts during a transition period (see Unified storage).

App catalog

App	Group	Purpose
apps/dashboard/	dashboard.grafana.app	Dashboards (multiple coexisting schema versions)
apps/folder/	folder.grafana.app	Folders
apps/alerting/	alerting.grafana.app	Alert rules, contact points
apps/iam/	iam.grafana.app	Identity & access primitives
apps/provisioning/	provisioning.grafana.app	Provisioning state
apps/playlist/	playlist.grafana.app	Dashboard playlists
apps/preferences/	preferences.grafana.app	User/team/org preferences
apps/quotas/	quotas.grafana.app	Tenant quotas
apps/secret/	secret.grafana.app	Secret management
apps/scope/	scope.grafana.app	Scopes (drilldown filters)
apps/correlations/	correlations.grafana.app	Correlations
apps/annotation/	annotation.grafana.app	Annotations
apps/shorturl/	shorturl.grafana.app	Short URLs
apps/live/	live.grafana.app	Live channels
apps/advisor/	advisor.grafana.app	Advisor checks
apps/dashvalidator/	n/a (operator)	Dashboard validator (controller)
apps/collections/	collections.grafana.app	Resource collections
apps/logsdrilldown/	logsdrilldown.grafana.app	Logs drilldown state
apps/plugins/	plugins.grafana.app	Plugin metadata
apps/example/	example.grafana.app	Reference / template

The list grows over time — every workspace under apps/ follows the same recipe.

Standard layout

apps/<name>/
├── go.mod                       # Each app is its own Go module
├── Makefile                     # gen / build / test
├── kinds/                       # CUE schemas (source of truth)
├── plugin/                      # App SDK plugin definition
├── operator/                    # Optional: controller/reconciler
├── pkg/
│   ├── apis/<group>/<version>/  # Generated Go types + apiserver registration
│   │   ├── zz_generated_*.go
│   │   ├── *_spec_gen.go
│   │   └── ...
│   ├── storage/                 # Adapter to unified storage / legacy SQL
│   ├── migration/               # Schema version conversion (when applicable)
│   └── (more domain-specific code)
└── docs/                        # Per-app developer docs

Codegen

Apps are entirely codegen-driven. The flow:

1. Edit a CUE file under apps/<name>/kinds/.
2. Run make gen-apps (or cd apps/<name> && make gen).
3. The generator emits zz_generated_*.go, *_spec_gen.go, and OpenAPI definitions.
4. Commit both the CUE source and the regenerated outputs.

Codegen is intentionally noisy — generated files account for most of the largest Go files in the repo (see By the numbers).

Versioning

Apps support multiple coexisting schema versions so the API can evolve without breaking clients. Each version is its own subdirectory under pkg/apis/<group>/. Resources are dispatched to the right version by the apiserver based on the request path; a pkg/migration/ package implements lossless conversion between versions when needed.

apps/dashboard/ is the most extreme example — it has v0alpha1, v1, v2alpha1, v2beta1, and v2 all live at once.

Operators

Some apps include an operator (apps/<name>/operator/) — a controller goroutine that watches a resource and reconciles side effects. apps/dashvalidator/ is the canonical example: it watches Dashboard events and emits validation diagnostics.

The operator framework is part of the App SDK. Operators register themselves at startup via pkg/operators/.

Wiring

Each app is integrated into the Grafana server via:

• An import line in pkg/operators/ (for side-effect operators) or
• A wire entry in pkg/services/apiserver/ that mounts the app's apiserver routes alongside the legacy /api/* table.

See also

• Backend / unified storage — overall architecture.
• Backend / Dashboards — dashboards-specific story.