Backend services

pkg/services/ is the business-logic tree. With 73 service domains it dominates the backend by both file count and surface area.

Naming pattern

Most services follow a common shape:

pkg/services/<domain>/
├── <domain>.go            # Service interface + types + errors
├── <domain>impl/          # Concrete implementation (or directly: e.g. <domain>Service struct)
├── <domain>test/          # In-package test fakes
├── api/                   # HTTP handlers when the service exposes its own router
├── store/ or database/    # SQL access
└── models/                # Persistent + DTO Go structs

Some long-lived services keep handlers and types directly inside pkg/api/<domain>.go; newer ones prefer a service-local api/ package. There is no single canonical layout — match the surrounding code.

Domain catalog (high level)

The 73 services group naturally into themes:

Identity & access

• auth/ — auth-method abstractions
• authn/ — authentication clients (basic, OAuth, JWT, anonymous, render token, …)
• authz/ — authorization (RBAC) glue
• accesscontrol/ — RBAC primitives, evaluator, middleware
• anonymous/ — anonymous identity tracking
• apikey/ — legacy API keys
• serviceaccounts/ — service accounts + tokens
• ldap/ — LDAP backend
• login/ — login flow + remembered users
• loginattempt/ — bruteforce throttling
• oauthtoken/ — OAuth refresh
• signingkeys/ — JWT signing
• ssosettings/ — SSO config storage
• extsvcauth/ — auth for external services
• encryption/, secrets/, kmsproviders/ — secret encryption

Tenancy

• org/ — organizations
• team/ — teams
• user/ — users
• temp_user/ — invitation/onboarding state
• preference/ — user/team/org preferences
• quota/ — quota enforcement
• stats/ — admin stats roll-ups

Dashboards & content

• dashboards/ — dashboard CRUD
• folder/ — folder hierarchy + permissions
• dashboardimport/ — import from JSON / grafana.com
• dashboardsnapshots/ — share-by-snapshot
• dashboardversion/ — version history
• libraryelements/, librarypanels/ — library panels
• publicdashboards/ — public dashboard sharing
• star/ — favorites
• shorturls/ — share-link shortener
• playlist/ — dashboard rotation
• navtree/ — built-in navigation tree

Datasources & queries

• datasources/ — datasource registry + secrets
• datasourceproxy/ — /api/datasources/proxy/*
• query/ — query orchestration over the plugin host
• queryhistory/ — Explore query history
• correlations/ — Explore correlations
• dsquerierclient/ — datasource querier client

Alerting

• ngalert/ — unified alerting (see Alerting)
• notifications/ — email and webhook notifications
• screenshot/ — alert image rendering

Plugins & rendering

• pluginsintegration/ — DI glue around pkg/plugins
• plugindashboards/ — bundled-with-plugin dashboards
• rendering/ — image rendering plugin
• caching/ — query/dashboard cache hooks
• live/ — Centrifuge-backed channels (see Live)
• updatemanager/ — update notifications

Storage

• sqlstore/ — xorm SQL gateway + migrations
• apiserver/ — apiserver registration glue
• store/ — file/blob store abstraction
• tag/ — tag normalization
• annotations/ — annotation CRUD

Operations & migration

• provisioning/ — file-based provisioning at startup
• cloudmigration/ — migrate-to-cloud workflows
• featuremgmt/ — feature flags (see Feature management)
• gcom/ — grafana.com API client
• grpcserver/ — internal gRPC server scaffolding
• hooks/ — extension hook registry
• licensing/ — enterprise licensing surface
• search/, searchusers/ — search APIs
• setting/ — runtime-mutable settings
• supportbundles/ — diagnostic bundle bundling
• promtypemigration/ — Prometheus type migrations
• scimutil/ — SCIM utilities
• validations/ — request validators

How services are wired

Each service has a ProvideService(...) constructor (Go's wire idiom). The constructor is added to a wire.NewSet and the entire graph is materialized in pkg/server/wire.go → pkg/server/wire_gen.go after running make gen-go.

Many services also implement registry.BackgroundService — an interface that lets them run a goroutine for the lifetime of the server (e.g. ngalert scheduler, live coordinator, plugin updater). Background services are started by pkg/registry/ after Wire builds the graph.

Cross-cutting helpers

• pkg/util/errutil/ — typed-error builder for predictable HTTP mapping.
• pkg/infra/log/ — namespaced logger.
• pkg/infra/db/ — DB connection wrapper.
• pkg/infra/tracing/ — OpenTelemetry tracer.
• pkg/services/sqlstore/searchstore/ — generic search query builder used by dashboards/folders.

Where to add a new service

1. Create pkg/services/<name>/<name>.go defining the interface and types.
2. Implement under <name>impl/ (or directly).
3. Add a ProvideService constructor and wire.NewSet.
4. Reference the new set from pkg/server/wire.go.
5. Run make gen-go.
6. Add tests under <name>impl/<name>_test.go and (if HTTP) under pkg/api/.
7. If HTTP-facing: register routes in pkg/api/api.go or, preferably, expose via an app-platform resource.

See API layer for HTTP wiring details and Patterns and conventions for naming/error conventions.