# grafana/scenes architecture

> Architecture diagram of the GitHub repository grafana/scenes, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/grafana/scenes
- Repository: https://github.com/grafana/scenes

## Overview

##### Project type and purpose
- This is a monorepo for the “Grafana Scenes” SDK: a framework for building interactive Grafana apps.
- It consists of three published packages:
- @grafana/scenes     (core rendering engine, behaviors, querying, variables)
- @grafana/scenes-react (React bindings and components)
- scenes-app           (a demo Grafana plugin/app built with the SDK)
- It also includes a Docusaurus-based documentation website and CI/CD workflows for testing, bundling, and deploying to the Grafana plugin registry.

##### File structure
- Root-level:
- Yarn v4 workspaces (.yarnrc.yml, .yarn/, package.json, lerna.json, turbo.json)
- CI/CD definitions (GitHub Actions under .github/workflows, custom action for Yarn builds)
- Lint, Prettier, Husky hooks, build scripts.
- packages/scenes
- TS source implementing core “scene graph,” behaviors, panel builders, query runners, variable handling.
- Rollup build config, Jest tests.
- packages/scenes-react
- React component wrappers, hooks, contexts, utilities.
- Rollup config, Jest, integration tests.
- packages/scenes-app
- Demo app (React + Grafana plugin manifest/plugin.json) showcasing SDK features.
- Webpack config, Docker compose provisioning for data sources, Cypress end-to-end tests.
- docusaurus/website
- Static site generator for user docs—Markdown + React pages + custom themes.

##### Key insights from README
- Primary goal: provide an SDK to build “Scenes” (interactive panels) in Grafana.
- Demo app lives in packages/scenes-app/README.md; core docs in packages/scenes/README.md.
- CI flows automate build/test of each package and deployment of the demo/documentation.

a. Main components
- Monorepo root (Yarn/Lerna/Turbo)
- Core library (@grafana/scenes)
- React binding library (@grafana/scenes-react)
- Demo app (scenes-app)
- Documentation site (Docusaurus)
- CI/CD pipeline (GitHub Actions)
- External services (Grafana plugin registry, npm registry)
b. Relationships & interactions
- scenes-app → imports → scenes-react → imports → scenes
- Docusaurus site → renders docs for all packages (pulls code examples from packages)
- CI → installs monorepo → runs tests/build on each package → publishes to npm/Grafana portal
c. Architectural patterns & principles
- Monorepo with Yarn Workspaces + Lerna for versioning and cross-package linking
- Modular package separation: core engine vs UI adapters vs example app
- CI/CD as code via GitHub Actions, ensuring atomic builds of all packages
d. Key technologies & frameworks
- TypeScript, React, Rollup, Webpack, Jest, Cypress, Docusaurus, GitHub Actions, Docker

##### Detail
- Three package boundaries, shared config, CI workflows, and external deployment targets
- Don’t omit the Docusaurus site—treat it as a first-class component

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Monorepo"
        Root["Monorepo Root"]:::monorepo
        subgraph "Workspace Packages"
            Scenes["@grafana/scenes"]:::lib
            ScenesReact["@grafana/scenes-react"]:::lib
            ScenesApp["scenes-app (Demo App)"]:::app
        end
        Docs["Docs Site (Docusaurus)"]:::docs
        CI["CI/CD Pipeline"]:::ci
    end

    External["External Services\n(NPM & Grafana Registry)"]:::external

    ScenesReact -->|"imports"| Scenes
    ScenesApp -->|"imports"| ScenesReact

    CI -->|"build & test"| Scenes
    CI -->|"build & test"| ScenesReact
    CI -->|"build & test"| ScenesApp
    CI -->|"build & test"| Docs
    CI -->|"publish to"| External
    CI -->|"deploy docs to site"| Docs

    Docs -->|"renders docs from"| Scenes
    Docs -->|"renders docs from"| ScenesReact
    Docs -->|"renders docs from"| ScenesApp

    click Root "https://github.com/grafana/scenes/blob/main/package.json"
    click CI "https://github.com/grafana/scenes/tree/main/.github/workflows/"
    click Scenes "https://github.com/grafana/scenes/blob/main/packages/scenes/package.json"
    click ScenesReact "https://github.com/grafana/scenes/blob/main/packages/scenes-react/package.json"
    click ScenesApp "https://github.com/grafana/scenes/blob/main/packages/scenes-app/package.json"
    click Docs "https://github.com/grafana/scenes/blob/main/docusaurus/website/package.json"

    classDef monorepo fill:#e0e0e0,stroke:#888,stroke-width:2px;
    classDef lib fill:#cce5ff,stroke:#339,stroke-width:1px;
    classDef app fill:#d4edda,stroke:#27632a,stroke-width:1px;
    classDef docs fill:#ffe5b4,stroke:#cc8400,stroke-width:1px;
    classDef ci fill:#f0f0f0,stroke:#666,stroke-width:1px;
    classDef external fill:#fff3cd,stroke:#856404,stroke-width:1px;
```
