# crabston/grav-plugin-umami-analytics architecture

> Architecture diagram of the GitHub repository crabston/grav-plugin-umami-analytics, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/crabston/grav-plugin-umami-analytics
- Repository: https://github.com/crabston/grav-plugin-umami-analytics

## Overview

This Grav plugin adds Umami tracking to public sites, optionally proxying tracker scripts and tracking requests through the site, and provides an optional Admin2 analytics dashboard. The public workflow runs through plugin configuration and asset injection; proxy requests are handled separately from the dashboard’s server-side API requests. The dashboard workflow runs from the Admin2 page through a registered API route to the controller, which fetches and caches Umami data for display. Proxy details beyond the sampled request handling are supported by the README; unsampled source is not treated as inspected.

Main entry points: [`classes/Api/DashboardController.php`](https://github.com/crabston/grav-plugin-umami-analytics/blob/main/classes/Api/DashboardController.php) (Dashboard Controller), [`umami-analytics.php`](https://github.com/crabston/grav-plugin-umami-analytics/blob/main/umami-analytics.php) (Tracking Setup), [`admin-next/pages/umami-analytics.js`](https://github.com/crabston/grav-plugin-umami-analytics/blob/main/admin-next/pages/umami-analytics.js) (Dashboard Page), [`umami-analytics.yaml`](https://github.com/crabston/grav-plugin-umami-analytics/blob/main/umami-analytics.yaml) (Plugin Settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_tracking["Site Tracking"]
  node_plugin["Tracking Setup"]
end

subgraph group_proxy["Same-Origin Proxy"]
  node_scriptproxy["Script Proxy"]
  node_eventproxy["Event Proxy"]
end

subgraph group_dashboard["Admin Dashboard"]
  node_adminpage["Dashboard Page<br/>[umami-analytics.js]"]
  node_route["Dashboard Route"]
  node_controller["Dashboard Controller"]
end

subgraph group_platform["Plugin Configuration"]
  node_config["Plugin Settings"]
  node_cache[("Grav Cache")]
end

node_visitor(("Site Visitor"))
node_grav["Grav Site"]
node_umami["Umami Service"]
node_admin(("Admin User"))

node_grav -->|"loads plugin"| node_plugin
node_config -->|"configures"| node_plugin
node_plugin -->|"adds tracker"| node_grav
node_visitor -->|"uses tracker"| node_umami
node_plugin -->|"serves script"| node_scriptproxy
node_scriptproxy -->|"fetches script"| node_umami
node_visitor -->|"sends events"| node_eventproxy
node_eventproxy -->|"forwards requests"| node_umami
node_admin -->|"opens dashboard"| node_adminpage
node_adminpage -->|"fetches dashboard"| node_route
node_route -->|"dispatches to"| node_controller
node_controller -->|"requests analytics"| node_umami
node_controller -->|"reads and writes"| node_cache
node_controller -->|"returns dashboard data"| node_adminpage

click node_plugin "https://github.com/crabston/grav-plugin-umami-analytics/blob/main/umami-analytics.php"
click node_config "https://github.com/crabston/grav-plugin-umami-analytics/blob/main/umami-analytics.yaml"
click node_scriptproxy "https://github.com/crabston/grav-plugin-umami-analytics/blob/main/umami-analytics.php"
click node_eventproxy "https://github.com/crabston/grav-plugin-umami-analytics/blob/main/umami-analytics.php"
click node_adminpage "https://github.com/crabston/grav-plugin-umami-analytics/blob/main/admin-next/pages/umami-analytics.js"
click node_route "https://github.com/crabston/grav-plugin-umami-analytics/blob/main/umami-analytics.php"
click node_controller "https://github.com/crabston/grav-plugin-umami-analytics/blob/main/classes/Api/DashboardController.php"

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,node_admin toneBlue
class node_scriptproxy,node_eventproxy toneAmber
class node_adminpage,node_route,node_controller toneMint
class node_config,node_cache toneRose
class node_visitor,node_grav,node_umami toneIndigo
```

## Components

### Site Tracking

- [Tracking Setup](https://github.com/crabston/grav-plugin-umami-analytics/blob/main/umami-analytics.php): `umami-analytics.php`

### Same-Origin Proxy

- [Script Proxy](https://github.com/crabston/grav-plugin-umami-analytics/blob/main/umami-analytics.php): `umami-analytics.php`
- [Event Proxy](https://github.com/crabston/grav-plugin-umami-analytics/blob/main/umami-analytics.php): `umami-analytics.php`

### Admin Dashboard

- [Dashboard Page](https://github.com/crabston/grav-plugin-umami-analytics/blob/main/admin-next/pages/umami-analytics.js): `admin-next/pages/umami-analytics.js`
- [Dashboard Route](https://github.com/crabston/grav-plugin-umami-analytics/blob/main/umami-analytics.php): `umami-analytics.php`
- [Dashboard Controller](https://github.com/crabston/grav-plugin-umami-analytics/blob/main/classes/Api/DashboardController.php): `classes/Api/DashboardController.php`

### Plugin Configuration

- [Plugin Settings](https://github.com/crabston/grav-plugin-umami-analytics/blob/main/umami-analytics.yaml): `umami-analytics.yaml`
- **Grav Cache**

### Other components

- **Site Visitor**
- **Grav Site**
- **Umami Service**
- **Admin User**

## Connections

- Grav Site → Tracking Setup: loads plugin (evidence: `umami-analytics.php`)
- Plugin Settings → Tracking Setup: configures (evidence: `umami-analytics.php`)
- Tracking Setup → Grav Site: adds tracker (evidence: `umami-analytics.php`)
- Site Visitor → Umami Service: uses tracker (evidence: `README.md`)
- Tracking Setup → Script Proxy: serves script (evidence: `README.md`)
- Script Proxy → Umami Service: fetches script (evidence: `README.md`)
- Site Visitor → Event Proxy: sends events (evidence: `README.md`)
- Event Proxy → Umami Service: forwards requests (evidence: `umami-analytics.php`)
- Admin User → Dashboard Page: opens dashboard (evidence: `README.md`)
- Dashboard Page → Dashboard Route: fetches dashboard (evidence: `admin-next/pages/umami-analytics.js`)
- Dashboard Route → Dashboard Controller: dispatches to (evidence: `umami-analytics.php`)
- Dashboard Controller → Umami Service: requests analytics (evidence: `classes/Api/DashboardController.php`)
- Dashboard Controller → Grav Cache: reads and writes (evidence: `classes/Api/DashboardController.php`)
- Dashboard Controller → Dashboard Page: returns dashboard data (evidence: `classes/Api/DashboardController.php`)
