# metrico/grafana-flow architecture

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

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

## Overview

1. **What this repository is**
   - The repo is centered on a **Grafana 10+ panel plugin** called **grafana-flow**.
   - Its main job is to take query results from Grafana and render them as an interactive **flow diagram / transaction flow view**.
   - The codebase also contains an **Angular workspace (`ngx-flow/`)** that appears to be a companion implementation/demo/legacy build path alongside the main Grafana plugin.

2. **Main application boundary**
   - The primary production boundary is the **root `src/` tree**, which is the Grafana plugin implementation.
   - It is a **frontend-only plugin**: it runs inside Grafana’s panel runtime and uses Grafana plugin APIs rather than owning its own backend service.
   - The plugin is declared via `src/plugin.json` and wired through `src/module.ts`.

3. **Data flow into the plugin**
   - Grafana sends **data frames / query results** into the panel.
   - Those results are transformed by helper code under `src/helpers/dataProcessors/` into a list of flow items:
     - parsing fields
     - filtering items
     - sorting/formatting items
   - The resulting normalized data becomes the model consumed by the visualization and modal/detail views.

4. **Visualization and interaction layer**
   - The main UI is split into focused components under `src/components/`:
     - `FlowPanel.tsx` is the top-level panel renderer.
     - `FlowModal/` handles detailed drill-down for a selected flow item.
     - `FilterPanel/` provides user filtering and collapse/menu controls.
     - `CopyText/` handles copy-to-clipboard style interaction.
     - `PluginSettings/` provides Grafana editor controls for panel configuration.
   - This separation suggests a clear architecture: **panel rendering**, **selection/drill-down**, **filtering**, and **configuration** are handled independently.

5. **Domain model and packet logic**
   - The plugin includes domain-specific packet helpers in `src/helpers/packets/`:
     - Ethernet
     - IP
     - TCP
     - UDP
   - This indicates the visualization is not just generic charting; it can interpret and present **network/message flow semantics**.
   - Supporting utilities such as `hash`, `uuid`, and `labelFormatter` suggest stable identity, grouping, and human-readable labeling of flow elements.

6. **Export and persistence helpers**
   - `src/helpers/exporters/` contains exporters for:
     - **text**
     - **pcap**
   - That means the plugin can convert displayed flow data into external formats for analysis or archival.
   - `saveAs.ts` and date filename helpers support client-side file generation/download, so exporting is handled entirely in the browser/plugin layer.

7. **Plugin settings architecture**
   - The panel exposes Grafana configuration via custom editors in `src/components/PluginSettings/`.
   - `MultiSelectEditor` and `TemplateEditor` imply the plugin allows users to tune field mappings, labels, or template-driven behavior.
   - This is important for the diagram because the plugin is partly **schema/config-driven**, not hardcoded to one data shape.

8. **Angular subproject (`ngx-flow/`)**
   - `ngx-flow/` is a separate Angular workspace with:
     - a library package under `projects/ngx-flow`
     - an application/demo under `src/app`
     - an `elements` project for building custom elements/web components
   - The library contains its own flow UI (`tab-flow`, `transaction-filter`, `ngx-flow.service`, `message-details.service`) and model types.
   - Architecturally, this is a **parallel UI stack** to the React/Grafana plugin, likely used for standalone rendering or older integration paths.

9. **Build and packaging**
   - The root plugin uses **TypeScript + React** with custom webpack configuration under `.config/webpack/`.
   - The Angular workspace has its own Angular CLI/ng-package setup and custom build scripts (`buildElements.sh`, `compileElements.js`, `elements-webpack.config.js`).
   - This repo therefore has **two build systems**: one for the Grafana plugin and one for the Angular workspace.

10. **Testing and verification**
   - There is **Jest** setup for unit-style testing and **Cypress** smoke testing under `cypress/integration/01-smoke.spec.ts`.
   - The presence of both suggests the repository validates:
     - core data transformation logic
     - UI behavior in-browser
   - Mock files and test setup live at the repo root and under `.config/`, showing shared test infrastructure.

11. **Deployment/runtime support**
   - `docker-compose.yaml`, root Docker/config files, and `.github/workflows/` indicate the project supports **containerized local development** and **CI/CD release automation**.
   - The README also documents installation as an **unsigned Grafana plugin**, which is a key operational constraint for deployment.

12. **Grafana provisioning**
   - `provisioning/datasources/` and `provisioning/dashboards/` provide preset Grafana environment assets.
   - This means the repo is designed not just as a plugin package, but also as a **reproducible Grafana test/demo environment**.

13. **How to draw the architecture**
   - A good diagram would show:
     - **Grafana panel host** on the left
     - the **React plugin UI** in the center
     - a **data transformation layer** between query results and rendering
     - side paths for **filtering, modal drill-down, settings, and export**
     - a separate, lower-priority box for the **Angular `ngx-flow` workspace**
     - and supporting boxes for **tests, build tooling, and Grafana provisioning**
   - The central flow is: **Grafana query data → normalize/parse/filter → render flow diagram → interact/filter/drill down/export**.

Main entry points: [`src/components/FlowPanel.tsx`](https://github.com/metrico/grafana-flow/blob/main/src/components/FlowPanel.tsx) (Flow panel), [`src/helpers/dataProcessors/index.ts`](https://github.com/metrico/grafana-flow/blob/main/src/helpers/dataProcessors/index.ts) (Data processors), [`src/helpers/dataProcessors/formatAndSortFlowItems.ts`](https://github.com/metrico/grafana-flow/blob/main/src/helpers/dataProcessors/formatAndSortFlowItems.ts) (Sort format), [`src/module.ts`](https://github.com/metrico/grafana-flow/blob/main/src/module.ts) (Module entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_root_plugin["Grafana plugin"]
  node_plugin_json["Plugin manifest<br/>plugin metadata<br/>[plugin.json]"]
  node_module_ts["Module entry<br/>plugin bootstrap<br/>[module.ts]"]
  node_flow_panel["Flow panel<br/>panel UI<br/>[FlowPanel.tsx]"]
  node_data_processors["Data processors<br/>transform pipeline<br/>[index.ts]"]
  node_parse_fields["Parse fields<br/>frame parsing"]
  node_filter_items["Filter items<br/>item filtering<br/>[filterFlowItems.ts]"]
  node_sort_format["Sort format<br/>item shaping"]
  node_flow_modal["Flow modal<br/>drill-down UI<br/>[FlowModal.tsx]"]
  node_parsed_view["Parsed view<br/>detail view<br/>[ParsedView.tsx]"]
  node_filter_panel["Filter panel<br/>filter UI<br/>[FilterPanel.tsx]"]
  node_copy_text["Copy text<br/>clipboard UI<br/>[CopyText.tsx]"]
  node_plugin_settings["Plugin settings<br/>editor controls<br/>[index.ts]"]
  node_exporters["Exporters<br/>export pipeline<br/>[index.ts]"]
  node_packets["Packet helpers<br/>domain logic<br/>[ethernetPacket.ts]"]
  node_root_utils["Shared utils<br/>support utils<br/>[hash.ts]"]
end

subgraph group_ngx_workspace["Angular workspace"]
  node_ngx_public_api["Library API<br/>angular library<br/>[public-api.ts]"]
  node_ngx_service["Flow service<br/>angular service"]
  node_ngx_component["Ngx component<br/>angular component"]
  node_tab_flow["Tab flow<br/>angular view"]
  node_txn_filter["Txn filter<br/>angular filter"]
  node_elements_build["Elements build<br/>web component build<br/>[main.ts]"]
end

subgraph group_tooling["Tooling"]
  node_web_webpack["Webpack config<br/>bundler config<br/>[webpack.config.ts]"]
  node_jest_setup["Jest setup<br/>test harness<br/>[jest-setup.js]"]
  node_cypress_smoke["Smoke test<br/>e2e test<br/>[01-smoke.spec.ts]"]
  node_ci_workflow["CI workflow<br/>ci pipeline<br/>[ci.yml]"]
  node_provisioning["Provisioning<br/>grafana assets<br/>[default.yaml]"]
end

node_grafana_host["Grafana host<br/>panel runtime"]

node_grafana_host -->|"loads"| node_plugin_json
node_plugin_json -->|"boots"| node_module_ts
node_module_ts -->|"renders"| node_flow_panel
node_grafana_host -->|"passes frames"| node_data_processors
node_data_processors -->|"parse"| node_parse_fields
node_data_processors -->|"filter"| node_filter_items
node_data_processors -->|"shape"| node_sort_format
node_parse_fields -->|"normalize"| node_sort_format
node_filter_items -->|"refine"| node_sort_format
node_sort_format -->|"feed"| node_flow_panel
node_flow_panel -->|"drill down"| node_flow_modal
node_flow_modal -->|"inspect"| node_parsed_view
node_flow_panel -->|"controls"| node_filter_panel
node_flow_panel -->|"copy"| node_copy_text
node_flow_panel -->|"configure"| node_plugin_settings
node_flow_panel -->|"export"| node_exporters
node_exporters -->|"write files"| node_root_utils
node_packets -->|"pcap format"| node_exporters
node_module_ts -.->|"uses"| node_packets
node_ngx_public_api -->|"exports"| node_ngx_component
node_ngx_public_api -->|"exports"| node_ngx_service
node_ngx_component -->|"hosts"| node_tab_flow
node_tab_flow -->|"filters"| node_txn_filter
node_ngx_service -->|"serves state"| node_tab_flow
node_elements_build -->|"packages"| node_ngx_public_api
node_web_webpack -->|"bundles"| node_flow_panel
node_jest_setup -.->|"tests"| node_data_processors
node_cypress_smoke -.->|"smokes"| node_flow_panel
node_ci_workflow -.->|"builds"| node_web_webpack
node_ci_workflow -.->|"verifies"| node_jest_setup
node_provisioning -->|"seeds"| node_grafana_host

click node_plugin_json "https://github.com/metrico/grafana-flow/blob/main/src/plugin.json"
click node_module_ts "https://github.com/metrico/grafana-flow/blob/main/src/module.ts"
click node_flow_panel "https://github.com/metrico/grafana-flow/blob/main/src/components/FlowPanel.tsx"
click node_data_processors "https://github.com/metrico/grafana-flow/blob/main/src/helpers/dataProcessors/index.ts"
click node_parse_fields "https://github.com/metrico/grafana-flow/blob/main/src/helpers/dataProcessors/parseDataIntoListOfFields.ts"
click node_filter_items "https://github.com/metrico/grafana-flow/blob/main/src/helpers/dataProcessors/filterFlowItems.ts"
click node_sort_format "https://github.com/metrico/grafana-flow/blob/main/src/helpers/dataProcessors/formatAndSortFlowItems.ts"
click node_flow_modal "https://github.com/metrico/grafana-flow/blob/main/src/components/FlowModal/FlowModal.tsx"
click node_parsed_view "https://github.com/metrico/grafana-flow/blob/main/src/components/FlowModal/ParsedView/ParsedView.tsx"
click node_filter_panel "https://github.com/metrico/grafana-flow/blob/main/src/components/FilterPanel/FilterPanel.tsx"
click node_copy_text "https://github.com/metrico/grafana-flow/blob/main/src/components/CopyText/CopyText.tsx"
click node_plugin_settings "https://github.com/metrico/grafana-flow/blob/main/src/components/PluginSettings/index.ts"
click node_exporters "https://github.com/metrico/grafana-flow/blob/main/src/helpers/exporters/index.ts"
click node_packets "https://github.com/metrico/grafana-flow/blob/main/src/helpers/packets/ethernetPacket.ts"
click node_root_utils "https://github.com/metrico/grafana-flow/blob/main/src/helpers/hash.ts"
click node_ngx_public_api "https://github.com/metrico/grafana-flow/blob/main/ngx-flow/projects/ngx-flow/src/public-api.ts"
click node_ngx_service "https://github.com/metrico/grafana-flow/blob/main/ngx-flow/projects/ngx-flow/src/lib/ngx-flow.service.ts"
click node_ngx_component "https://github.com/metrico/grafana-flow/blob/main/ngx-flow/projects/ngx-flow/src/lib/ngx-flow.component.ts"
click node_tab_flow "https://github.com/metrico/grafana-flow/blob/main/ngx-flow/projects/ngx-flow/src/tab-flow/tab-flow.component.ts"
click node_txn_filter "https://github.com/metrico/grafana-flow/blob/main/ngx-flow/projects/ngx-flow/src/transaction-filter/transaction-filter.component.ts"
click node_elements_build "https://github.com/metrico/grafana-flow/blob/main/ngx-flow/projects/elements/src/main.ts"
click node_web_webpack "https://github.com/metrico/grafana-flow/blob/main/.config/webpack/webpack.config.ts"
click node_jest_setup "https://github.com/metrico/grafana-flow/blob/main/.config/jest-setup.js"
click node_cypress_smoke "https://github.com/metrico/grafana-flow/blob/main/cypress/integration/01-smoke.spec.ts"
click node_ci_workflow "https://github.com/metrico/grafana-flow/blob/main/.github/workflows/ci.yml"
click node_provisioning "https://github.com/metrico/grafana-flow/blob/main/provisioning/dashboards/default.yaml"

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_plugin_json,node_module_ts,node_flow_panel,node_data_processors,node_parse_fields,node_filter_items,node_sort_format,node_flow_modal,node_parsed_view,node_filter_panel,node_copy_text,node_plugin_settings,node_exporters,node_packets,node_root_utils toneBlue
class node_ngx_public_api,node_ngx_service,node_ngx_component,node_tab_flow,node_txn_filter,node_elements_build toneAmber
class node_web_webpack,node_jest_setup,node_cypress_smoke,node_ci_workflow,node_provisioning toneMint
class node_grafana_host toneNeutral
```

## Components

### Grafana plugin

Main React/Grafana panel plugin runtime

- [Plugin manifest](https://github.com/metrico/grafana-flow/blob/main/src/plugin.json): plugin metadata · Declares the panel plugin to Grafana · `src/plugin.json`
- [Module entry](https://github.com/metrico/grafana-flow/blob/main/src/module.ts): plugin bootstrap · Registers the panel and wires plugin setup · `src/module.ts`
- [Flow panel](https://github.com/metrico/grafana-flow/blob/main/src/components/FlowPanel.tsx): panel UI · Top-level panel renderer for the flow diagram · `src/components/FlowPanel.tsx`
- [Data processors](https://github.com/metrico/grafana-flow/blob/main/src/helpers/dataProcessors/index.ts): transform pipeline · Normalizes Grafana frames into flow items · `src/helpers/dataProcessors/index.ts`
- [Parse fields](https://github.com/metrico/grafana-flow/blob/main/src/helpers/dataProcessors/parseDataIntoListOfFields.ts): frame parsing · Extracts fields from query results · `src/helpers/dataProcessors/parseDataIntoListOfFields.ts`
- [Filter items](https://github.com/metrico/grafana-flow/blob/main/src/helpers/dataProcessors/filterFlowItems.ts): item filtering · Applies item-level filtering before render · `src/helpers/dataProcessors/filterFlowItems.ts`
- [Sort format](https://github.com/metrico/grafana-flow/blob/main/src/helpers/dataProcessors/formatAndSortFlowItems.ts): item shaping · Formats and orders flow items for display · `src/helpers/dataProcessors/formatAndSortFlowItems.ts`
- [Flow modal](https://github.com/metrico/grafana-flow/blob/main/src/components/FlowModal/FlowModal.tsx): drill-down UI · Detailed view for a selected flow item · `src/components/FlowModal/FlowModal.tsx`
- [Parsed view](https://github.com/metrico/grafana-flow/blob/main/src/components/FlowModal/ParsedView/ParsedView.tsx): detail view · Structured breakdown of parsed data and fields · `src/components/FlowModal/ParsedView/ParsedView.tsx`
- [Filter panel](https://github.com/metrico/grafana-flow/blob/main/src/components/FilterPanel/FilterPanel.tsx): filter UI · User controls for filtering and collapsing flow views · `src/components/FilterPanel/FilterPanel.tsx`
- [Copy text](https://github.com/metrico/grafana-flow/blob/main/src/components/CopyText/CopyText.tsx): clipboard UI · Copy-to-clipboard interaction for displayed content · `src/components/CopyText/CopyText.tsx`
- [Plugin settings](https://github.com/metrico/grafana-flow/blob/main/src/components/PluginSettings/index.ts): editor controls · Grafana configuration editors for panel options · `src/components/PluginSettings/index.ts`
- [Exporters](https://github.com/metrico/grafana-flow/blob/main/src/helpers/exporters/index.ts): export pipeline · Converts flow data into text or PCAP outputs · `src/helpers/exporters/index.ts`
- [Packet helpers](https://github.com/metrico/grafana-flow/blob/main/src/helpers/packets/ethernetPacket.ts): domain logic · Ethernet, IP, TCP, and UDP helpers for network semantics · `src/helpers/packets/ethernetPacket.ts`
- [Shared utils](https://github.com/metrico/grafana-flow/blob/main/src/helpers/hash.ts): support utils · Hashing, UUIDs, labels, filenames, and save helpers · `src/helpers/hash.ts`

### Angular workspace

Standalone companion UI/build path

- [Library API](https://github.com/metrico/grafana-flow/blob/main/ngx-flow/projects/ngx-flow/src/public-api.ts): angular library · Exports the ngx-flow Angular package surface · `ngx-flow/projects/ngx-flow/src/public-api.ts`
- [Flow service](https://github.com/metrico/grafana-flow/blob/main/ngx-flow/projects/ngx-flow/src/lib/ngx-flow.service.ts): angular service · Central service for standalone Angular flow state · `ngx-flow/projects/ngx-flow/src/lib/ngx-flow.service.ts`
- [Ngx component](https://github.com/metrico/grafana-flow/blob/main/ngx-flow/projects/ngx-flow/src/lib/ngx-flow.component.ts): angular component · Library component wrapper for ngx-flow rendering · `ngx-flow/projects/ngx-flow/src/lib/ngx-flow.component.ts`
- [Tab flow](https://github.com/metrico/grafana-flow/blob/main/ngx-flow/projects/ngx-flow/src/tab-flow/tab-flow.component.ts): angular view · Standalone tabbed flow presentation · `ngx-flow/projects/ngx-flow/src/tab-flow/tab-flow.component.ts`
- [Txn filter](https://github.com/metrico/grafana-flow/blob/main/ngx-flow/projects/ngx-flow/src/transaction-filter/transaction-filter.component.ts): angular filter · Transaction filtering UI and logic · `ngx-flow/projects/ngx-flow/src/transaction-filter/transaction-filter.component.ts`
- [Elements build](https://github.com/metrico/grafana-flow/blob/main/ngx-flow/projects/elements/src/main.ts): web component build · Compiles Angular elements into distributable outputs · `ngx-flow/projects/elements/src/main.ts`

### Tooling

Build, test, CI, and provisioning support

- [Webpack config](https://github.com/metrico/grafana-flow/blob/main/.config/webpack/webpack.config.ts): bundler config · Custom webpack configuration for the Grafana plugin · `.config/webpack/webpack.config.ts`
- [Jest setup](https://github.com/metrico/grafana-flow/blob/main/.config/jest-setup.js): test harness · Shared Jest configuration and mocks · `.config/jest-setup.js`
- [Smoke test](https://github.com/metrico/grafana-flow/blob/main/cypress/integration/01-smoke.spec.ts): e2e test · Browser smoke coverage for the plugin UI · `cypress/integration/01-smoke.spec.ts`
- [CI workflow](https://github.com/metrico/grafana-flow/blob/main/.github/workflows/ci.yml): ci pipeline · Automated build and verification workflow · `.github/workflows/ci.yml`
- [Provisioning](https://github.com/metrico/grafana-flow/blob/main/provisioning/dashboards/default.yaml): grafana assets · Prebuilt datasources and dashboards for local Grafana · `provisioning/dashboards/default.yaml`

### Other components

- **Grafana host**: panel runtime · Grafana provides query results and panel lifecycle

## Connections

- Grafana host → Plugin manifest: loads · Grafana discovers the panel plugin from its manifest
- Plugin manifest → Module entry: boots · Plugin metadata points to the module entry
- Module entry → Flow panel: renders · Module registers the panel UI
- Grafana host → Data processors: passes frames · Query results arrive as Grafana data frames
- Data processors → Parse fields: parse · Extract fields from incoming query data
- Data processors → Filter items: filter · Drop items that do not match current criteria
- Data processors → Sort format: shape · Format and order flow items for rendering
- Parse fields → Sort format: normalize · Parsed fields feed downstream shaping
- Filter items → Sort format: refine · Filtering constrains the final displayed list
- Sort format → Flow panel: feed · Normalized items drive the main visualization
- Flow panel → Flow modal: drill down · Selecting an item opens the detail modal
- Flow modal → Parsed view: inspect · Modal exposes structured parsed content
- Flow panel → Filter panel: controls · Panel exposes filtering and collapse controls
- Flow panel → Copy text: copy · Rendered content can be copied to clipboard
- Flow panel → Plugin settings: configure · Editor controls tune panel behavior
- Flow panel → Exporters: export · Displayed flow data can be exported
- Exporters → Shared utils: write files · Export flows use filename and save helpers
- Packet helpers → Exporters: pcap format · Packet helpers support PCAP generation semantics
- Module entry → Packet helpers: uses · Plugin logic interprets network packet semantics
- Library API → Ngx component: exports · Library API exposes the main component
- Library API → Flow service: exports · Library API exposes the shared service
- Ngx component → Tab flow: hosts · Library component organizes the flow view
- Tab flow → Txn filter: filters · Standalone Angular UI includes transaction filtering
- Flow service → Tab flow: serves state · Shared service coordinates flow view data
- Elements build → Library API: packages · Elements build compiles the Angular flow library
- Webpack config → Flow panel: bundles · Webpack builds the React plugin bundle
- Jest setup → Data processors: tests · Unit test harness supports transformation logic
- Smoke test → Flow panel: smokes · E2E smoke tests exercise the panel UI
- CI workflow → Webpack config: builds · CI runs the plugin build pipeline
- CI workflow → Jest setup: verifies · CI executes unit test infrastructure
- Provisioning → Grafana host: seeds · Provisioned dashboards and datasources create a demo Grafana environment