metrico/grafana-flow

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.