Architecture

Grafana is a single binary that bundles an HTTP server, a plugin host, and a precompiled frontend SPA. At runtime users hit the Go server, which serves the React app on first load and then handles JSON/gRPC API calls and proxied datasource queries.

High-level components

graph LR
    Browser[Browser SPA<br/>public/app] -->|HTTP/JSON| HTTP[HTTP server<br/>pkg/api]
    HTTP --> AC[Access control<br/>pkg/services/accesscontrol]
    HTTP --> Services[Domain services<br/>pkg/services/*]
    Services --> SQL[sqlstore<br/>pkg/services/sqlstore]
    Services --> Plugins[Plugin host<br/>pkg/plugins]
    Plugins -->|gRPC| TSDB[Datasource backend<br/>pkg/tsdb/*]
    Services --> NGAlert[ngalert<br/>alert evaluation]
    NGAlert --> Notifier[notifier<br/>contact points]
    HTTP --> Live[Live channels<br/>pkg/services/live]
    SQL --> DB[(SQLite / Postgres / MySQL)]

Every box maps to a directory in this repo. The HTTP server is an HTTP mux (web/), the services are wired with Wire DI in pkg/server/wire.go, and the plugin host launches each datasource plugin as a separate gRPC subprocess.

Backend layers

Grafana follows a relatively classic three-layer split inside pkg/:

1. API handlers in pkg/api/ parse the HTTP request, do authentication via middleware, and call out to a service. Files like pkg/api/dashboard.go, pkg/api/folder.go, pkg/api/datasources.go are typical.
2. Services in pkg/services/<domain>/ hold the business logic. Each service exposes an interface in the same package and is implemented by a concrete struct that's wired via DI. Services rarely talk to HTTP — they receive Go structs and return Go structs/errors.
3. Storage in pkg/services/sqlstore/ is the historical SQL layer (xorm-based). Newer code uses the unified storage / app-platform path through pkg/storage/ and the apps in apps/ which expose Kubernetes-style resources.

The pkg/api/api.go file wires up every route to a handler. The plugin/datasource subsystem lives in pkg/plugins/ (loader, registry, sandboxing) plus pkg/services/pluginsintegration/ (DI glue) and the per-datasource backends in pkg/tsdb/<name>/.

Frontend layers

The frontend is a React SPA. The high-level shape:

graph TD
    Index[public/app/index.ts] --> App[AppWrapper]
    App --> Routes[Router config<br/>public/app/routes]
    Routes --> Features[features/*]
    Features --> Core[core/* services & components]
    Features --> UI["@grafana/ui"]
    Features --> Data["@grafana/data"]
    Features --> Runtime["@grafana/runtime"]
    Features --> Plugins[plugins/*]

• public/app/index.ts bootstraps the Redux store, the runtime services (theme, config, location), and mounts <AppWrapper>.
• public/app/core/ contains shared utilities, services, and components used by every feature.
• public/app/features/ holds feature areas — dashboards, explore, alerting, datasources, plugins, profile, admin, etc. Each feature has its own routes, Redux slice (or RTK Query api), and React components.
• public/app/plugins/ ships the built-in datasource and panel plugins.

The shared @grafana/* packages in packages/ are consumed both by public/app and by external plugin authors, which is why they live in their own workspaces.

Apps and unified storage

The newer "apps" architecture in apps/ is built on the Grafana App SDK and exposes resources (Dashboard, Folder, Playlist, IamUser, AlertRule, …) over a Kubernetes-style API. Each app declares its CRDs/kinds in CUE and generates Go and TS types via make gen-cue / make gen-apps.

This sits alongside the legacy services in pkg/services/ — over time more functionality is migrating from the SQL store to the app-platform path. See Backend / unified storage for the migration shape.

Plugins and datasources

Datasource plugins are split into two halves:

• A frontend plugin (TypeScript, in public/app/plugins/datasource/<name>/ or in a workspace under public/app/plugins/) implementing query editor UI and the DataSource class.
• A backend plugin (Go, in pkg/tsdb/<name>/) implementing query execution, called by the Go server over gRPC via the plugin host.

Built-in plugins are compiled into the binary. External plugins are loaded at startup from disk by pkg/plugins/manager.

Runtime topology

A typical Grafana deployment runs:

• The Grafana server binary (one or more replicas behind a load balancer for HA),
• A relational database (SQLite by default; Postgres or MySQL for production),
• Optional separate processes for image rendering (pkg/services/rendering/) and remote alerting,
• Datasource backends run as child processes of the server (managed by the plugin host) — they're not separate deployments.

For real-time features (live tail in Explore, alert state changes), the server uses Centrifuge under pkg/services/live/ to push messages to the SPA over WebSockets.

Cross-cutting concerns

• Configuration — flat INI files (conf/defaults.ini + conf/custom.ini), parsed by pkg/setting/. See Configuration reference.
• Authentication & RBAC — many auth methods (basic, OAuth, LDAP, SAML, JWT, OAuth2 server, anonymous, service accounts) implemented under pkg/services/auth/, pkg/services/authn/, pkg/services/login/, with role-based access control in pkg/services/accesscontrol/. See Backend / Authentication.
• Feature toggles — defined in pkg/services/featuremgmt/, checked from both Go (features.IsEnabled) and TypeScript (config.featureToggles).
• Schema — CUE definitions in kinds/ generate Go and TS code via make gen-cue.