# grafana/synthetic-monitoring-app architecture

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

- Interactive diagram: https://gitdiagram.com/grafana/synthetic-monitoring-app
- Repository: https://github.com/grafana/synthetic-monitoring-app

## Overview

#### Purpose and host integration
This repository is the Grafana Synthetic Monitoring application: a TypeScript/React Grafana app plugin for configuring blackbox checks, probe locations, alerting, and viewing synthetic-monitoring results. It runs inside Grafana rather than as a standalone web application.
- `src/module.tsx`
- `src/plugin.json`
- `src/datasource/module.ts`

#### Entrypoints, initialization, and routing
The app plugin entry registers pages/components with Grafana. Initialization establishes tenant/setup, datasource, metadata, permissions, feature flags, and access contexts before routing users through initialized or uninitialized flows. Routing separates provisioning/setup states from normal check, probe, configuration, and dashboard navigation.
- `src/components/AppInitializer.tsx`
- `src/routing/InitialisedRouter.tsx`
- `src/routing/UninitialisedRouter.tsx`

#### Control plane: checks, probes, and configuration
The primary control-plane UI manages synthetic checks and probe agents. Check lists support filtering, folders, permissions, and bulk actions; dedicated pages create/edit checks and probes. The app targets public Grafana-managed probes and private probes, with API-server mapping data bundled for BYOC/development variants.
- `src/page/CheckList/CheckList.tsx`
- `src/page/NewCheck/NewCheckV2.tsx`
- `src/page/EditProbe/EditProbe.tsx`
- `src/data/probeAPIServerMappings.json`

#### Checkster form engine and API boundary
`Checkster` is the central check-editor system. It renders protocol-specific layouts (HTTP, DNS, gRPC, TCP, ping, traceroute, browser, scripted, multi-HTTP), maintains form state/sections, validates configurations, and converts between backend check objects and UI form values. The transformation layer is the key compatibility boundary: `toFormValues` ingests existing/API check data, while `toPayload` emits service-ready configuration.
- `src/components/Checkster/Checkster.tsx`
- `src/components/Checkster/transformations/toFormValues.http.ts`
- `src/components/Checkster/transformations/toPayload.http.ts`
- `src/schemas/forms/utils/createCheckSchema.ts`

#### Data access, authorization, and service dependencies
React data hooks centralize reads and mutations for checks, probes, folders, tenant limits, alerts, logs, secrets, and setup. Grafana permissions and folder access gate UI/actions. The plugin relies on Grafana-hosted Synthetic Monitoring APIs for configuration/execution, Prometheus/Mimir-compatible metrics datasources for measurements, Loki for logs, and a Secrets Manager API for protected values.
- `src/data/useChecks.ts`
- `src/data/useProbes.ts`
- `src/data/clients/SecretsManagerClient/SecretsManagerClient.ts`
- `src/features/queryDatasources/queryMimir.ts`

#### Observability results and dashboards
Protocol-specific Grafana Scenes dashboards compose metric queries and visualizations for availability, latency, traffic, DNS/browser results, and traceroute paths. Logs are fetched/parsing-normalized separately, then rendered with HTTP timings, screenshots, and trace links. Timepoint Explorer provides detailed per-execution/probe investigation.
- `src/scenes/HTTP/HttpDashboard.tsx`
- `src/scenes/Common/DashboardContainer.tsx`
- `src/features/parseLokiLogs/parseLokiLogs.ts`
- `src/scenes/components/TimepointExplorer/TimepointExplorer.tsx`

#### Alerts, export, and operational runtime
Check-level alert configuration supports routing previews and Grafana/legacy alert displays. Terraform generation converts check configuration into HCL for infrastructure-as-code workflows. The frontend is bundled with Webpack and developed against a Docker Compose Grafana environment; browser telemetry is integrated through Faro.
- `src/components/CheckForm/AlertsPerCheck/AlertsPerCheck.tsx`
- `src/components/TerraformConfig/hcl/terraformRenderer.ts`
- `.config/webpack/webpack.config.ts`
- `docker-compose.yaml`
- `src/faro.ts`

Main entry points: [`src/routing/InitialisedRouter.tsx`](https://github.com/grafana/synthetic-monitoring-app/blob/main/src/routing/InitialisedRouter.tsx) (Initialized router), [`src/scenes/HTTP/HttpDashboard.tsx`](https://github.com/grafana/synthetic-monitoring-app/blob/main/src/scenes/HTTP/HttpDashboard.tsx) (Scenes dashboards), [`src/module.tsx`](https://github.com/grafana/synthetic-monitoring-app/blob/main/src/module.tsx) (Plugin entry), [`src/components/Checkster/Checkster.tsx`](https://github.com/grafana/synthetic-monitoring-app/blob/main/src/components/Checkster/Checkster.tsx) (Checkster)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["Grafana host"]
  node_grafana{{"Grafana runtime<br/>host platform"}}
  node_synthetic_api[("Synthetic Monitoring APIs<br/>hosted control plane")]
end

subgraph group_app["Plugin application"]
  node_plugin_entry["Plugin entry<br/>app registration<br/>[module.tsx]"]
  node_plugin_manifest["Plugin manifest<br/>Grafana plugin config<br/>[plugin.json]"]
  node_datasource_module["Datasource module<br/>datasource integration<br/>[module.ts]"]
  node_initializer["App initializer<br/>bootstrap gate<br/>[AppInitializer.tsx]"]
  node_initialised_router["Initialized router<br/>application routing"]
  node_uninitialised_router["Setup router<br/>provisioning routing"]
end

subgraph group_control["Control plane"]
  node_check_list["Check list<br/>check management UI<br/>[CheckList.tsx]"]
  node_checkster["Checkster<br/>check editor engine<br/>[Checkster.tsx]"]
  node_check_schema["Check schema<br/>form validation"]
  node_to_form_values["API-to-form transform<br/>compatibility transform"]
  node_to_payload["Form-to-payload transform<br/>compatibility transform<br/>[toPayload.http.ts]"]
  node_new_check["New check<br/>check creation page<br/>[NewCheckV2.tsx]"]
  node_edit_probe["Probe editor<br/>probe management page<br/>[EditProbe.tsx]"]
  node_probe_mappings["Probe API mappings<br/>BYOC mapping data"]
  node_data_hooks["Data hooks<br/>control-plane data access<br/>[useChecks.ts]"]
  node_secrets_client["Secrets Manager client<br/>secret API client"]
end

subgraph group_results["Results and operations"]
  node_dashboards["Scenes dashboards<br/>results dashboards<br/>[HttpDashboard.tsx]"]
  node_dashboard_container["Dashboard container<br/>Scenes shell"]
  node_metrics_query["Mimir metrics queries<br/>metrics datasource access<br/>[queryMimir.ts]"]
  node_loki_parser["Loki log parser<br/>log normalization<br/>[parseLokiLogs.ts]"]
  node_timepoint_explorer["Timepoint Explorer<br/>execution investigation UI"]
  node_alerts["Check alerts<br/>alert configuration UI<br/>[AlertsPerCheck.tsx]"]
  node_terraform["Terraform renderer<br/>HCL export"]
  node_faro["Faro telemetry<br/>browser telemetry<br/>[faro.ts]"]
end

node_grafana -->|"loads"| node_plugin_entry
node_plugin_manifest -->|"declares"| node_plugin_entry
node_plugin_entry -->|"integrates"| node_datasource_module
node_plugin_entry -->|"starts"| node_initializer
node_initializer -->|"when initialized"| node_initialised_router
node_initializer -->|"when setup required"| node_uninitialised_router
node_initialised_router -->|"routes to"| node_check_list
node_initialised_router -->|"routes to"| node_new_check
node_initialised_router -->|"routes to"| node_edit_probe
node_initialised_router -->|"routes to"| node_dashboards
node_new_check -->|"uses"| node_checkster
node_checkster -->|"validates with"| node_check_schema
node_to_form_values -->|"hydrates form"| node_checkster
node_checkster -->|"produces values"| node_to_payload
node_check_list -->|"reads and mutates through"| node_data_hooks
node_edit_probe -->|"manages through"| node_data_hooks
node_data_hooks -->|"calls"| node_synthetic_api
node_to_payload -->|"submits configuration"| node_synthetic_api
node_edit_probe -->|"uses"| node_probe_mappings
node_secrets_client -->|"protects values via"| node_synthetic_api
node_dashboards -->|"renders in"| node_dashboard_container
node_dashboards -->|"queries measurements"| node_metrics_query
node_dashboards -->|"loads normalized logs"| node_loki_parser
node_dashboards -->|"drills into"| node_timepoint_explorer
node_alerts -->|"configures"| node_synthetic_api
node_terraform -.->|"exports check configuration"| node_to_payload
node_plugin_entry -.->|"reports telemetry"| node_faro

click node_plugin_entry "https://github.com/grafana/synthetic-monitoring-app/blob/main/src/module.tsx"
click node_plugin_manifest "https://github.com/grafana/synthetic-monitoring-app/blob/main/src/plugin.json"
click node_datasource_module "https://github.com/grafana/synthetic-monitoring-app/blob/main/src/datasource/module.ts"
click node_initializer "https://github.com/grafana/synthetic-monitoring-app/blob/main/src/components/AppInitializer.tsx"
click node_initialised_router "https://github.com/grafana/synthetic-monitoring-app/blob/main/src/routing/InitialisedRouter.tsx"
click node_uninitialised_router "https://github.com/grafana/synthetic-monitoring-app/blob/main/src/routing/UninitialisedRouter.tsx"
click node_check_list "https://github.com/grafana/synthetic-monitoring-app/blob/main/src/page/CheckList/CheckList.tsx"
click node_checkster "https://github.com/grafana/synthetic-monitoring-app/blob/main/src/components/Checkster/Checkster.tsx"
click node_check_schema "https://github.com/grafana/synthetic-monitoring-app/blob/main/src/schemas/forms/utils/createCheckSchema.ts"
click node_to_form_values "https://github.com/grafana/synthetic-monitoring-app/blob/main/src/components/Checkster/transformations/toFormValues.http.ts"
click node_to_payload "https://github.com/grafana/synthetic-monitoring-app/blob/main/src/components/Checkster/transformations/toPayload.http.ts"
click node_new_check "https://github.com/grafana/synthetic-monitoring-app/blob/main/src/page/NewCheck/NewCheckV2.tsx"
click node_edit_probe "https://github.com/grafana/synthetic-monitoring-app/blob/main/src/page/EditProbe/EditProbe.tsx"
click node_probe_mappings "https://github.com/grafana/synthetic-monitoring-app/blob/main/src/data/probeAPIServerMappings.json"
click node_data_hooks "https://github.com/grafana/synthetic-monitoring-app/blob/main/src/data/useChecks.ts"
click node_secrets_client "https://github.com/grafana/synthetic-monitoring-app/blob/main/src/data/clients/SecretsManagerClient/SecretsManagerClient.ts"
click node_dashboards "https://github.com/grafana/synthetic-monitoring-app/blob/main/src/scenes/HTTP/HttpDashboard.tsx"
click node_dashboard_container "https://github.com/grafana/synthetic-monitoring-app/blob/main/src/scenes/Common/DashboardContainer.tsx"
click node_metrics_query "https://github.com/grafana/synthetic-monitoring-app/blob/main/src/features/queryDatasources/queryMimir.ts"
click node_loki_parser "https://github.com/grafana/synthetic-monitoring-app/blob/main/src/features/parseLokiLogs/parseLokiLogs.ts"
click node_timepoint_explorer "https://github.com/grafana/synthetic-monitoring-app/blob/main/src/scenes/components/TimepointExplorer/TimepointExplorer.tsx"
click node_alerts "https://github.com/grafana/synthetic-monitoring-app/blob/main/src/components/CheckForm/AlertsPerCheck/AlertsPerCheck.tsx"
click node_terraform "https://github.com/grafana/synthetic-monitoring-app/blob/main/src/components/TerraformConfig/hcl/terraformRenderer.ts"
click node_faro "https://github.com/grafana/synthetic-monitoring-app/blob/main/src/faro.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_grafana,node_synthetic_api toneBlue
class node_plugin_entry,node_plugin_manifest,node_datasource_module,node_initializer,node_initialised_router,node_uninitialised_router toneAmber
class node_check_list,node_checkster,node_check_schema,node_to_form_values,node_to_payload,node_new_check,node_edit_probe,node_probe_mappings,node_data_hooks,node_secrets_client toneMint
class node_dashboards,node_dashboard_container,node_metrics_query,node_loki_parser,node_timepoint_explorer,node_alerts,node_terraform,node_faro toneRose
```

## Components

### Grafana host

- **Grafana runtime**: host platform · Hosts the app plugin and supplies permissions, routing, and datasource access.
- **Synthetic Monitoring APIs**: hosted control plane · Stores configuration and executes synthetic checks.

### Plugin application

- [Plugin entry](https://github.com/grafana/synthetic-monitoring-app/blob/main/src/module.tsx): app registration · `src/module.tsx`
- [Plugin manifest](https://github.com/grafana/synthetic-monitoring-app/blob/main/src/plugin.json): Grafana plugin config · `src/plugin.json`
- [Datasource module](https://github.com/grafana/synthetic-monitoring-app/blob/main/src/datasource/module.ts): datasource integration · `src/datasource/module.ts`
- [App initializer](https://github.com/grafana/synthetic-monitoring-app/blob/main/src/components/AppInitializer.tsx): bootstrap gate · Loads tenant, setup, metadata, access, permissions, and feature state. · `src/components/AppInitializer.tsx`
- [Initialized router](https://github.com/grafana/synthetic-monitoring-app/blob/main/src/routing/InitialisedRouter.tsx): application routing · `src/routing/InitialisedRouter.tsx`
- [Setup router](https://github.com/grafana/synthetic-monitoring-app/blob/main/src/routing/UninitialisedRouter.tsx): provisioning routing · `src/routing/UninitialisedRouter.tsx`

### Control plane

- [Check list](https://github.com/grafana/synthetic-monitoring-app/blob/main/src/page/CheckList/CheckList.tsx): check management UI · Filters, folders, permissions, and bulk check actions. · `src/page/CheckList/CheckList.tsx`
- [Checkster](https://github.com/grafana/synthetic-monitoring-app/blob/main/src/components/Checkster/Checkster.tsx): check editor engine · Protocol-specific form layouts, state, and validation. · `src/components/Checkster/Checkster.tsx`
- [Check schema](https://github.com/grafana/synthetic-monitoring-app/blob/main/src/schemas/forms/utils/createCheckSchema.ts): form validation · `src/schemas/forms/utils/createCheckSchema.ts`
- [API-to-form transform](https://github.com/grafana/synthetic-monitoring-app/blob/main/src/components/Checkster/transformations/toFormValues.http.ts): compatibility transform · `src/components/Checkster/transformations/toFormValues.http.ts`
- [Form-to-payload transform](https://github.com/grafana/synthetic-monitoring-app/blob/main/src/components/Checkster/transformations/toPayload.http.ts): compatibility transform · `src/components/Checkster/transformations/toPayload.http.ts`
- [New check](https://github.com/grafana/synthetic-monitoring-app/blob/main/src/page/NewCheck/NewCheckV2.tsx): check creation page · `src/page/NewCheck/NewCheckV2.tsx`
- [Probe editor](https://github.com/grafana/synthetic-monitoring-app/blob/main/src/page/EditProbe/EditProbe.tsx): probe management page · `src/page/EditProbe/EditProbe.tsx`
- [Probe API mappings](https://github.com/grafana/synthetic-monitoring-app/blob/main/src/data/probeAPIServerMappings.json): BYOC mapping data · `src/data/probeAPIServerMappings.json`
- [Data hooks](https://github.com/grafana/synthetic-monitoring-app/blob/main/src/data/useChecks.ts): control-plane data access · Centralizes check, probe, folder, setup, alert, log, secret, and limit operations. · `src/data/useChecks.ts`
- [Secrets Manager client](https://github.com/grafana/synthetic-monitoring-app/blob/main/src/data/clients/SecretsManagerClient/SecretsManagerClient.ts): secret API client · `src/data/clients/SecretsManagerClient/SecretsManagerClient.ts`

### Results and operations

- [Scenes dashboards](https://github.com/grafana/synthetic-monitoring-app/blob/main/src/scenes/HTTP/HttpDashboard.tsx): results dashboards · Composes protocol-specific availability, latency, traffic, and path views. · `src/scenes/HTTP/HttpDashboard.tsx`
- [Dashboard container](https://github.com/grafana/synthetic-monitoring-app/blob/main/src/scenes/Common/DashboardContainer.tsx): Scenes shell · `src/scenes/Common/DashboardContainer.tsx`
- [Mimir metrics queries](https://github.com/grafana/synthetic-monitoring-app/blob/main/src/features/queryDatasources/queryMimir.ts): metrics datasource access · `src/features/queryDatasources/queryMimir.ts`
- [Loki log parser](https://github.com/grafana/synthetic-monitoring-app/blob/main/src/features/parseLokiLogs/parseLokiLogs.ts): log normalization · `src/features/parseLokiLogs/parseLokiLogs.ts`
- [Timepoint Explorer](https://github.com/grafana/synthetic-monitoring-app/blob/main/src/scenes/components/TimepointExplorer/TimepointExplorer.tsx): execution investigation UI · `src/scenes/components/TimepointExplorer/TimepointExplorer.tsx`
- [Check alerts](https://github.com/grafana/synthetic-monitoring-app/blob/main/src/components/CheckForm/AlertsPerCheck/AlertsPerCheck.tsx): alert configuration UI · `src/components/CheckForm/AlertsPerCheck/AlertsPerCheck.tsx`
- [Terraform renderer](https://github.com/grafana/synthetic-monitoring-app/blob/main/src/components/TerraformConfig/hcl/terraformRenderer.ts): HCL export · `src/components/TerraformConfig/hcl/terraformRenderer.ts`
- [Faro telemetry](https://github.com/grafana/synthetic-monitoring-app/blob/main/src/faro.ts): browser telemetry · `src/faro.ts`

## Connections

- Grafana runtime → Plugin entry: loads
- Plugin manifest → Plugin entry: declares
- Plugin entry → Datasource module: integrates
- Plugin entry → App initializer: starts
- App initializer → Initialized router: when initialized
- App initializer → Setup router: when setup required
- Initialized router → Check list: routes to
- Initialized router → New check: routes to
- Initialized router → Probe editor: routes to
- Initialized router → Scenes dashboards: routes to
- New check → Checkster: uses
- Checkster → Check schema: validates with
- API-to-form transform → Checkster: hydrates form
- Checkster → Form-to-payload transform: produces values
- Check list → Data hooks: reads and mutates through
- Probe editor → Data hooks: manages through
- Data hooks → Synthetic Monitoring APIs: calls
- Form-to-payload transform → Synthetic Monitoring APIs: submits configuration
- Probe editor → Probe API mappings: uses
- Secrets Manager client → Synthetic Monitoring APIs: protects values via
- Scenes dashboards → Dashboard container: renders in
- Scenes dashboards → Mimir metrics queries: queries measurements
- Scenes dashboards → Loki log parser: loads normalized logs
- Scenes dashboards → Timepoint Explorer: drills into
- Check alerts → Synthetic Monitoring APIs: configures
- Terraform renderer → Form-to-payload transform: exports check configuration
- Plugin entry → Faro telemetry: reports telemetry