High-Level Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The Grafana project is a monitoring and observability platform structured as a monorepo containing a Go-based backend and a TypeScript/React-based frontend. The system is currently undergoing a significant architectural transition toward a Kubernetes-inspired, resource-oriented model. This shift moves Grafana from traditional imperative APIs to a declarative, eventually-consistent design where system state is aligned with well-structured objects defined by the user.
Sources: AGENTS.md:10-14, contribute/architecture/k8s-inspired-backend-arch.md:3-8
System Overview and Core Components
The architecture is divided into three primary layers: the Frontend (Web UI), the Backend (API and Business Logic), and the Storage Layer. The backend is further categorized into Legacy APIs and the new Resource APIs, which are served by a Unified Storage abstraction.
| Component | Technology | Primary Purpose |
|---|---|---|
| Frontend | React, TypeScript, Redux Toolkit | User interface, data visualization, and resource management. |
| Backend | Go (Golang) | API handling, business logic services, and plugin management. |
| Resource APIs | Kubernetes-style APIs | Declarative resource management using CUE-defined schemas. |
| Unified Storage | Internal Go abstraction | Decouples API handlers from underlying SQL databases. |
| Database | SQL (Postgres, MySQL, SQLite) | Primary persistence layer for all core Grafana resources. |
Sources: AGENTS.md:10-14, contribute/architecture/k8s-inspired-backend-arch.md:40-55, contribute/developer-guide.md:44-52
Backend Architecture
Grafana's backend uses a service-oriented architecture managed by Wire for Dependency Injection (DI). The logic is organized into domains such as alerting, dashboards, and auth, primarily located within pkg/services/.
Key Backend Modules
pkg/api/: Contains HTTP API handlers and routing logic.pkg/services/: Houses the core business logic. Services typically implement interfaces defined within their own package.pkg/tsdb/: Backend components responsible for executing queries against various Time Series Databases.pkg/server/: Manages server initialization and Wire DI configuration.
Sources: AGENTS.md:112-121, contribute/backend/recommended-practices.md:65-69
Kubernetes-Inspired Resource Model
Grafana is adopting a model where resources like dashboards and datasources are managed via a /apis/... structure. This replaces Legacy APIs (/api/...) with versioned, schema-backed endpoints.
The diagram shows the request flow where both Legacy and Resource APIs eventually interact with the primary SQL database, often through a Unified Storage abstraction.
Sources: contribute/architecture/k8s-inspired-backend-arch.md:144-190
Storage and Persistence
Unlike a standard Kubernetes environment that uses etcd, Grafana's Unified Storage utilizes traditional SQL databases (PostgreSQL, MySQL, or SQLite) to ensure operational simplicity and backward compatibility.
Unified Storage Characteristics
storage.Interface: Implements the Kubernetes storage interface to translateCreate,Get,List, andWatchoperations into SQL queries.- Resource Versioning: Uses a monotonically increasing counter for optimistic concurrency control. Updates are rejected if the provided
resourceVersiondoes not match the stored version. - Native Watch Support: Monitors changes via a
resource_historytable. In HA mode, a poller detects changes; in non-HA mode, Go channels trigger direct notifications.
Sources: contribute/architecture/k8s-inspired-backend-arch.md:58-85
Frontend Architecture
The frontend is located in public/app/ and follows modern React patterns. It is organized by feature domains (e.g., features/dashboard, features/alerting).
Frontend Standards
- State Management: Uses Redux Toolkit with slices and RTK Query for data fetching.
- Styling: Utilizes Emotion for CSS-in-JS, specifically via the
useStyles2hook. - Communication: Frontend data requests are handled through the
backendSrvor specialized RTK Query hooks.
Sources: AGENTS.md:123-132, contribute/architecture/README.md:1-10, contribute/developer-guide.md:73-81
API Implementation Approaches
New APIs are implemented using two primary methods within the backend:
- Registry Approach (
pkg/registry/apis/): The original Go-based method where resources are registered viaregister.gofiles. - Apps Approach (
apps/): The newer, modular approach where APIs are defined using CUE schemas inkinds/*.cuefiles. This approach supports controllers/reconcilers that watch resources and align the system state.
This diagram illustrates how both the CUE-based Apps approach and the Go-based Registry approach converge at the API Registrar to expose standardized endpoints.
Sources: contribute/architecture/k8s-inspired-backend-arch.md:87-111, contribute/architecture/k8s-inspired-backend-arch.md:192-235
Release and Development Workflow
Grafana follows a trunk-based development model where the main branch is the primary target for all changes.
- Releases: Major releases occur yearly, minor releases every 4-6 weeks, and patch releases as needed.
- Feature Flags: Large architectural changes or new features are often hidden behind feature flags (defined in
pkg/services/featuremgmt/) to allow for incremental migration and testing in production environments. - Testing: The system employs a multi-tier testing strategy including backend unit/integration tests (Go), frontend unit tests (Jest), and end-to-end tests (Playwright).
Sources: WORKFLOW.md:37-65, AGENTS.md:144-150, contribute/developer-guide.md:144-180
Conclusion
The high-level architecture of Grafana represents a hybrid state, bridging a traditional service-oriented backend with a modern, Kubernetes-inspired resource management system. By unifying storage through SQL-backed Kubernetes interfaces and adopting schema-first development with CUE, the project aims to provide a more consistent, extensible, and programmatic interface for observability-as-code.