# signoz/dashboards architecture

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

- Interactive diagram: https://gitdiagram.com/signoz/dashboards
- Repository: https://github.com/signoz/dashboards

## Overview

##### Project type and purpose
- This is an open-source “dashboard templates” repository for SigNoz, an observability platform.
- It does not contain a front-end or back-end application in the usual sense, but rather a collection of JSON dashboard definitions organized by service (MySQL, MongoDB, APM, etc.).

##### File structure
- Top-level folders correspond to each supported service. For example:
- apache-web-server/
- aws-rds/
- kubernetes-infra-metrics/
- llm-observability/
…and so on.
- Inside each folder:
- A `.json` file (or multiple versions) defining the dashboard.
- An optional README.md explaining the metrics and usage.
- An assets/ subdirectory containing sample screenshots.
- Root files include CONTRIBUTING, CODE_OF_CONDUCT, LICENSE, and README describing how to contribute new dashboards.

##### README for additional insights
- README.md lists all available dashboards and their use cases.
- It defines naming conventions (`service-source-version.json`).
- It describes the contribution workflow (create file, add README, add screenshots, PR).

##### Main components
a. Component: GitHub Repository
- Hosts JSON dashboard definitions.
- Contains CI/CD for validating JSON syntax and possibly automated releases (could be GitHub Actions).
b. Component: SigNoz Observability Platform
- Ingestion pipeline (OpenTelemetry collector, Prometheus scraper).
- Storage layer (e.g., ClickHouse).
- Query/API layer.
- UI Dashboard Engine (Angular/React-based front-end).
c. Component: Data Sources (Instrumented Applications & Infrastructure)
- Services like MySQL, Redis, Kubernetes, JVM apps, etc., emitting metrics via OTLP/Prometheus endpoints.
d. Component: End User / DevOps Engineer
- Browses the GitHub repository.
- Imports JSON into the SigNoz UI.
- Visualizes dashboards.
e. (Optional) CI/CD Pipeline
- Lint JSON dashboards.
- Deploy example dashboards to a demo SigNoz instance.

##### Relationships & interactions
- Data Sources → (OTLP/Prometheus) → SigNoz Ingestion Pipeline → Storage.
- User → (HTTP) → SigNoz UI/API.
- User → (Git clone / PR) → GitHub Repo.
- GitHub Repo → (CI/CD) → optionally publish versioned dashboards to a release or demo instance.

##### Architectural patterns and principles
- Separation of concerns:
- Dashboard definitions are decoupled from the SigNoz codebase.
- Versioned templates per service.
- Extensibility:
- New dashboards can be plugged in by dropping a new JSON and assets folder.
- Declarative configuration:
- Dashboards described entirely in JSON.
- Content-distribution:
- Static assets served from GitHub.

##### Relevant technologies, frameworks, libraries
- Git/GitHub for version control.
- JSON schema for dashboard definitions.
- SigNoz project (Go-based backend, ClickHouse storage, React/TypeScript front-end).
- OpenTelemetry Collector or Prometheus for metric ingestion.
- CI/CD (e.g., GitHub Actions) for linting and publishing.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    User["DevOps Engineer / Contributor"]:::user

    %% GitHub Repository and Templates
    subgraph "GitHub Repository (Dashboard Templates)" 
        direction TB
        Repo["GitHub Repository"]:::static
        subgraph "Repository Files & CI"
            direction TB
            GH_ROOT["Root Files"]:::static
            CI_PIPELINE["CI/CD Pipeline"]:::ci
        end
        subgraph "Dashboard Template Providers"
            direction TB
            Apache["apache-web-server"]:::static
            AWS_MYSQL["aws-rds/mysql"]:::static
            K8S_INFRA["k8s-infra-metrics"]:::static
            LLM_OBS["llm-observability"]:::static
        end
    end

    %% SigNoz Platform
    subgraph "SigNoz Observability Platform"
        direction TB
        Collector["OpenTelemetry Collector / Prometheus Scraper"]:::processing
        Storage["ClickHouse Storage"]:::storage
        API["SigNoz API / Query Layer"]:::processing
        UI["SigNoz UI Dashboard Engine"]:::processing
    end

    %% Data Sources
    subgraph "Instrumented Services & Infrastructure"
        direction TB
        DS1["MySQL, Redis, JVM Apps, Kubernetes, etc."]:::processing
    end

    %% Interactions
    User -->|"git clone / PR"| Repo
    Repo -->|triggers| CI_PIPELINE
    CI_PIPELINE -->|validates & publishes| Repo
    Repo -->|"import JSON"| UI
    DS1 -->|"OTLP / Prometheus"| Collector
    Collector -->|"store metrics"| Storage
    Storage -->|"query data"| API
    API -->|"serves dashboards"| UI
    User -->|"HTTP / UI"| UI

    %% Click Events for Component Mapping
    click GH_ROOT "https://github.com/signoz/dashboards/tree/main/.github/"
    click GH_ROOT "https://github.com/signoz/dashboards/blob/main/CODE_OF_CONDUCT.md"
    click GH_ROOT "https://github.com/signoz/dashboards/blob/main/CONTRIBUTING.md"
    click GH_ROOT "https://github.com/signoz/dashboards/tree/main/LICENSE"
    click GH_ROOT "https://github.com/signoz/dashboards/blob/main/README.md"
    click CI_PIPELINE "https://github.com/signoz/dashboards/blob/main/cicd/cicd.json"
    click Apache "https://github.com/signoz/dashboards/blob/main/apache-web-server/apache.json"
    click AWS_MYSQL "https://github.com/signoz/dashboards/blob/main/aws-rds/mysql/overview.json"
    click AWS_MYSQL "https://github.com/signoz/dashboards/blob/main/aws-rds/mysql/db_metrics.json"
    click K8S_INFRA "https://github.com/signoz/dashboards/blob/main/k8s-infra-metrics/README.md"
    click K8S_INFRA "https://github.com/signoz/dashboards/blob/main/k8s-infra-metrics/host-metrics.json"
    click K8S_INFRA "https://github.com/signoz/dashboards/blob/main/k8s-infra-metrics/k8s-events-receiver.json"
    click K8S_INFRA "https://github.com/signoz/dashboards/blob/main/k8s-infra-metrics/kubernetes-cluster-metrics.json"
    click K8S_INFRA "https://github.com/signoz/dashboards/blob/main/k8s-infra-metrics/kubernetes-node-metrics-detailed.json"
    click K8S_INFRA "https://github.com/signoz/dashboards/blob/main/k8s-infra-metrics/kubernetes-node-metrics-overall.json"
    click K8S_INFRA "https://github.com/signoz/dashboards/blob/main/k8s-infra-metrics/kubernetes-pod-metrics-detailed.json"
    click K8S_INFRA "https://github.com/signoz/dashboards/blob/main/k8s-infra-metrics/kubernetes-pod-metrics-overall.json"
    click K8S_INFRA "https://github.com/signoz/dashboards/blob/main/k8s-infra-metrics/kubernetes-pvc-metrics.json"
    click LLM_OBS "https://github.com/signoz/dashboards/blob/main/llm-observability/sample-chatpdf-cost-dashboard.json"
    click LLM_OBS "https://github.com/signoz/dashboards/blob/main/llm-observability/sample-chatpdf-performance-metrics.json"

    %% Styles
    classDef static fill:#D0E6FF,stroke:#0366d6,color:#0366d6
    classDef processing fill:#E6FFEA,stroke:#28A745,color:#28A745
    classDef storage fill:#FFEBD6,stroke:#E36209,color:#E36209
    classDef user fill:#F5E6FF,stroke:#6F42C1,color:#6F42C1
    classDef ci fill:#FFF5E6,stroke:#D69F00,color:#D69F00
```
