I turned the Grafana codebase
into an onboarding guide

What is Grafana?

The big picture in 30 seconds.

Users connect data sources (Prometheus, Loki, PostgreSQL, etc.), build dashboards with visual panels (graphs, tables, gauges), and create alerting rules that fire notifications when thresholds are crossed.

Mental Model

How to think about this codebase without panicking.

Product Manager Guide PM

What you need to know about the product — no code required.

Core Product Areas

How Features Get Shipped

graph LR
    A["Feature flag
created in code"] --> B["Dev builds behind
flag (off by default)"]
    B --> C["Flag enabled for
internal/canary"]
    C --> D["Gradual rollout
to users"]
    D --> E["Flag removed,
feature is GA"]

    style A fill:#201a2e,stroke:#a78bfa,color:#e0e0e6
    style E fill:#1a2c2a,stroke:#10b981,color:#e0e0e6
        

Where to Find Product Context

Key Product Concepts

Key Concepts Explained SWE

If you're new to backend development or these specific technologies, start here.

Architecture

High-level system design — how the pieces fit together.

graph TB
    subgraph Client["Browser"]
        UI["React SPA
(public/app/)"]
    end

    subgraph Server["Go Backend (pkg/)"]
        API["HTTP API Layer
pkg/api/"]
        MW["Middleware
(Auth, CSRF, Logging)"]
        SVC["Service Layer
pkg/services/"]
        APPS["Modular Apps
apps/"]
        PLUG["Plugin Host
pkg/plugins/"]
    end

    subgraph Data["Data Layer"]
        DB["SQL Database
(SQLite / Postgres / MySQL)"]
        CACHE["Cache
(In-memory / Redis)"]
    end

    subgraph External["External"]
        DS["Data Sources
(Prometheus, Loki, etc.)"]
        BP["Backend Plugins
(gRPC)"]
    end

    UI -- "HTTP / WebSocket" --> MW
    MW --> API
    API --> SVC
    API --> APPS
    SVC --> DB
    SVC --> CACHE
    SVC --> PLUG
    PLUG -- "gRPC" --> BP
    API -- "Proxy" --> DS

    style Client fill:#1a2332,stroke:#3b82f6,color:#e0e0e6
    style Server fill:#1a2520,stroke:#10b981,color:#e0e0e6
    style Data fill:#2a2518,stroke:#fbbf24,color:#e0e0e6
    style External fill:#2a1a24,stroke:#f472b6,color:#e0e0e6
        

Core Components

The major building blocks.

Data Flow SWE

How a user request travels through the system — follow the numbers.

sequenceDiagram
    participant B as Browser (React)
    participant M as Middleware
    participant A as API Handler
    participant S as Service Layer
    participant DB as SQL Database
    participant P as Plugin / Data Source

    B->>M: 1. HTTP Request (e.g. POST /api/ds/query)
    M->>M: 2. Auth check, CSRF, logging
    M->>A: 3. Route to handler (pkg/api/)
    A->>S: 4. Call domain service
    S->>DB: 5. Read config (data source settings)
    DB-->>S: 6. Config response
    S->>P: 7. Forward query (gRPC / HTTP proxy)
    P-->>S: 8. Query results (data frames)
    S-->>A: 9. Return data frames
    A-->>B: 10. JSON response → rendered as panels
        

Development Loop SWE

How your daily edit-build-test cycle works.

graph LR
    A["Edit code"] --> B{"Frontend
or Backend?"}
    B -->|Frontend| C["Webpack auto-reloads
(yarn start)"]
    B -->|Backend| D["Air auto-rebuilds
(make run)"]
    C --> E["Check browser
localhost:3000"]
    D --> E
    E --> F["Run tests"]
    F --> G{"Tests pass?"}
    G -->|Yes| H["Commit & push"]
    G -->|No| A

    style A fill:#1a2332,stroke:#3b82f6,color:#e0e0e6
    style H fill:#1a2c2a,stroke:#10b981,color:#e0e0e6
        

Engineering Manager Guide EM

Team structure, code ownership, PR patterns, and deployment — what you need to lead here.

Service Ownership Map

The codebase is divided into domain areas. Each area typically maps to a squad or team. Here's the territory:

What to Look for in PRs

Deployment & Release Model

Technical Health Indicators

Where Do I Look? SWE

Common tasks mapped to the files you need.

Common Recipes SWE

Step-by-step for the tasks you'll do most often.

Key Folders

Where to find things.

Important Files SWE

Start here when you need to understand something specific.

• pkg/cmd/grafana/main.goCLI entry point — starts the Grafana server
• pkg/server/wire.goWire DI graph — every backend service and how they connect
• pkg/api/api.goAll HTTP route registrations — the API map
• pkg/api/http_server.goHTTP server setup — middleware, auth, TLS
• public/app/index.tsFrontend entry — boot data and React init
• public/app/routes/routes.tsxFrontend route definitions — URLs to components
• public/app/app.tsApp initialization — Redux, services, plugins, i18n
• conf/defaults.iniDefault configuration — all settings with defaults
• pkg/services/featuremgmt/Feature toggle definitions
• MakefileBuild commands — run, test, lint, codegen

Getting Started SWE

Your first day — follow these steps to get up and running.

# Quick reference — common commands
make run                                    # Backend with hot reload
yarn start                                  # Frontend dev server
go test -run TestName ./pkg/services/xxx/   # Run specific backend test
yarn jest --no-watch path/to/file           # Run specific frontend test
make lint-go                                # Go linter
yarn lint:fix                               # ESLint auto-fix
yarn typecheck                              # TypeScript type checking
make gen-go                                 # Regenerate Wire DI
make gen-cue                                # Regenerate CUE schemas
make gen-feature-toggles                    # Regenerate feature flag code
make devenv sources=postgres,loki           # Start backing services

Your First Week

A checklist for getting oriented without drowning in code.

Debugging Guide SWE

When something breaks, here's where to look.

Glossary

Terms you'll encounter in conversation and in the codebase.

Frequently Asked Questions

Questions every new hire asks in the first week.

AI Limitations

This guide was generated by AI. Here's what that means.

• ⚠️Simplified architecture. The real system has more nuance than any diagram can capture. Service boundaries, internal APIs, and edge cases are more complex than shown here.
• ⚠️Potentially outdated. The codebase evolves daily. File paths, service names, and patterns described here may have changed since this page was generated.
• ⚠️Missing tribal knowledge. AI can read code but can't capture team conventions, unwritten rules, deployment quirks, or "why we did it this way" context that lives in people's heads.
• ⚠️Ownership may be inaccurate. The team/domain mapping is inferred from directory structure. Actual code ownership may differ — check with your manager or CODEOWNERS file.
• ⚠️Recipes are patterns, not gospel. The step-by-step recipes reflect common patterns found in the codebase, but your team may have preferred approaches that differ.

Gotchas & Tips

Things that trip up new engineers.