# rootmax84/redbox-telemetry architecture

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

- Interactive diagram: https://gitdiagram.com/rootmax84/redbox-telemetry
- Repository: https://github.com/rootmax84/redbox-telemetry

## Overview

RedBox Telemetry receives vehicle logs, stores them by user and session, then serves a browser experience for exploring, charting, searching, and managing telemetry. The documented fast path queues uploads in Redis for a worker to persist; without Redis, uploads are processed inline. Authentication, quotas, session operations, remote controls, exports, and monitoring form important supporting capabilities. Some feature endpoints are listed only in the tree, so their connections are shown only where the README or excerpts establish them.

Main entry points: [`web/src/templates/index/page.php`](https://github.com/rootmax84/redbox-telemetry/blob/main/web/src/templates/index/page.php) (Dashboard view), [`web/src/db.php`](https://github.com/rootmax84/redbox-telemetry/blob/main/web/src/db.php) (Database access), [`web/ul.php`](https://github.com/rootmax84/redbox-telemetry/blob/main/web/ul.php) (Upload endpoint), [`web/worker.php`](https://github.com/rootmax84/redbox-telemetry/blob/main/web/worker.php) (Stream worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Telemetry ingestion"]
  node_upload["Upload endpoint<br/>[ul.php]"]
  node_processor["Upload processor"]
  node_redis["Redis streams<br/>[redis.php]"]
  node_worker["Stream worker<br/>[worker.php]"]
end

subgraph group_web["Browser experience"]
  node_dashboard["Telemetry dashboard<br/>[index.php]"]
  node_dashboard_view["Dashboard view<br/>[page.php]"]
  node_charts["Charts and map<br/>[plot-data.php]"]
  node_filters["Session filters<br/>[filters.php]"]
  node_translations["Localization<br/>[translations.php]"]
end

subgraph group_data["Identity and data"]
  node_db["Database access<br/>[db.php]"]
  node_mariadb[("Telemetry database")]
  node_auth["Authentication<br/>[auth_functions.php]"]
  node_auth_gate["Login gate<br/>[auth_user.php]"]
  node_cache["Cache layer<br/>[cache.php]"]
  node_quota["User quotas<br/>[db_limits.php]"]
  node_session_list["Session retrieval<br/>[get_sessions.php]"]
end

subgraph group_operations["Operations"]
  node_sessions["Session operations<br/>[del_sessions.php]"]
  node_heavy_tasks["Background tasks<br/>[heavy_tasks.php]"]
  node_admin["Admin panel<br/>[admin.php]"]
  node_imports["Log imports<br/>[import_redlog.php]"]
  node_exports["Session export<br/>[export.php]"]
  node_search["Telemetry search"]
end

subgraph group_integrations["Integrations"]
  node_sharing["Session sharing<br/>[share.php]"]
  node_remote["Remote controls<br/>[remote.php]"]
  node_stream["Live streaming<br/>[stream.php]"]
  node_metrics_api["Latest metrics API<br/>[url.php]"]
  node_exporter["Prometheus exporter<br/>[api_exporter.py]"]
end

node_devices(("Vehicle devices"))
node_browser(("Browser user"))
node_prometheus(("Prometheus / Grafana"))

node_devices -->|"submit logs"| node_upload
node_upload -->|"enqueue upload"| node_redis
node_redis -->|"deliver stream"| node_worker
node_worker -->|"process upload"| node_processor
node_processor -->|"persist telemetry"| node_mariadb
node_upload -.->|"inline fallback"| node_processor
node_browser -->|"sign in"| node_auth_gate
node_auth_gate -->|"authenticate"| node_auth
node_browser -->|"open telemetry"| node_dashboard
node_dashboard -.->|"render page"| node_dashboard_view
node_dashboard_view -->|"include chart"| node_charts
node_dashboard_view -->|"include filters"| node_filters
node_dashboard -.->|"load sessions"| node_session_list
node_db -->|"initialize cache"| node_cache
node_db -->|"connect Redis"| node_redis
node_db -.->|"query database"| node_mariadb
node_quota -->|"check usage"| node_session_list
node_sessions -->|"queue deletion"| node_heavy_tasks
node_worker -->|"consume tasks"| node_heavy_tasks
node_browser -->|"import logs"| node_imports
node_browser -->|"export sessions"| node_exports
node_browser -->|"search telemetry"| node_search
node_browser -->|"share sessions"| node_sharing
node_browser -->|"control settings"| node_remote
node_browser -->|"view live data"| node_stream
node_browser -->|"fetch latest metrics"| node_metrics_api
node_exporter -.->|"fetch metrics"| node_metrics_api
node_exporter -.->|"expose metrics"| node_prometheus
node_dashboard_view -.->|"localize interface"| node_translations

click node_upload "https://github.com/rootmax84/redbox-telemetry/blob/main/web/ul.php"
click node_processor "https://github.com/rootmax84/redbox-telemetry/blob/main/web/src/upload_processor.php"
click node_redis "https://github.com/rootmax84/redbox-telemetry/blob/main/web/src/redis.php"
click node_worker "https://github.com/rootmax84/redbox-telemetry/blob/main/web/worker.php"
click node_db "https://github.com/rootmax84/redbox-telemetry/blob/main/web/src/db.php"
click node_auth "https://github.com/rootmax84/redbox-telemetry/blob/main/web/src/auth_functions.php"
click node_auth_gate "https://github.com/rootmax84/redbox-telemetry/blob/main/web/src/auth_user.php"
click node_cache "https://github.com/rootmax84/redbox-telemetry/blob/main/web/src/cache.php"
click node_quota "https://github.com/rootmax84/redbox-telemetry/blob/main/web/src/db_limits.php"
click node_session_list "https://github.com/rootmax84/redbox-telemetry/blob/main/web/src/get_sessions.php"
click node_dashboard "https://github.com/rootmax84/redbox-telemetry/blob/main/web/src/pages/index.php"
click node_dashboard_view "https://github.com/rootmax84/redbox-telemetry/blob/main/web/src/templates/index/page.php"
click node_charts "https://github.com/rootmax84/redbox-telemetry/blob/main/web/src/templates/index/partials/plot-data.php"
click node_filters "https://github.com/rootmax84/redbox-telemetry/blob/main/web/src/templates/index/partials/filters.php"
click node_sessions "https://github.com/rootmax84/redbox-telemetry/blob/main/web/del_sessions.php"
click node_heavy_tasks "https://github.com/rootmax84/redbox-telemetry/blob/main/web/src/heavy_tasks.php"
click node_admin "https://github.com/rootmax84/redbox-telemetry/blob/main/web/src/templates/index/partials/admin.php"
click node_imports "https://github.com/rootmax84/redbox-telemetry/blob/main/web/import_redlog.php"
click node_exports "https://github.com/rootmax84/redbox-telemetry/blob/main/web/export.php"
click node_search "https://github.com/rootmax84/redbox-telemetry/blob/main/web/search_processor.php"
click node_sharing "https://github.com/rootmax84/redbox-telemetry/blob/main/web/share.php"
click node_remote "https://github.com/rootmax84/redbox-telemetry/blob/main/web/remote.php"
click node_stream "https://github.com/rootmax84/redbox-telemetry/blob/main/web/stream.php"
click node_metrics_api "https://github.com/rootmax84/redbox-telemetry/blob/main/web/url.php"
click node_exporter "https://github.com/rootmax84/redbox-telemetry/blob/main/prometheus/api_exporter.py"
click node_translations "https://github.com/rootmax84/redbox-telemetry/blob/main/web/translations.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_upload,node_processor,node_redis,node_worker,node_browser toneBlue
class node_dashboard,node_dashboard_view,node_charts,node_filters,node_translations toneAmber
class node_db,node_mariadb,node_auth,node_auth_gate,node_cache,node_quota,node_session_list toneMint
class node_sessions,node_heavy_tasks,node_admin,node_imports,node_exports,node_search toneRose
class node_sharing,node_remote,node_stream,node_metrics_api,node_exporter,node_devices,node_prometheus toneIndigo
```

## Components

### Telemetry ingestion

- [Upload endpoint](https://github.com/rootmax84/redbox-telemetry/blob/main/web/ul.php): `web/ul.php`
- [Upload processor](https://github.com/rootmax84/redbox-telemetry/blob/main/web/src/upload_processor.php): `web/src/upload_processor.php`
- [Redis streams](https://github.com/rootmax84/redbox-telemetry/blob/main/web/src/redis.php): `web/src/redis.php`
- [Stream worker](https://github.com/rootmax84/redbox-telemetry/blob/main/web/worker.php): `web/worker.php`

### Browser experience

- [Telemetry dashboard](https://github.com/rootmax84/redbox-telemetry/blob/main/web/src/pages/index.php): `web/src/pages/index.php`
- [Dashboard view](https://github.com/rootmax84/redbox-telemetry/blob/main/web/src/templates/index/page.php): `web/src/templates/index/page.php`
- [Charts and map](https://github.com/rootmax84/redbox-telemetry/blob/main/web/src/templates/index/partials/plot-data.php): `web/src/templates/index/partials/plot-data.php`
- [Session filters](https://github.com/rootmax84/redbox-telemetry/blob/main/web/src/templates/index/partials/filters.php): `web/src/templates/index/partials/filters.php`
- [Localization](https://github.com/rootmax84/redbox-telemetry/blob/main/web/translations.php): `web/translations.php`

### Identity and data

- [Database access](https://github.com/rootmax84/redbox-telemetry/blob/main/web/src/db.php): `web/src/db.php`
- **Telemetry database**
- [Authentication](https://github.com/rootmax84/redbox-telemetry/blob/main/web/src/auth_functions.php): `web/src/auth_functions.php`
- [Login gate](https://github.com/rootmax84/redbox-telemetry/blob/main/web/src/auth_user.php): `web/src/auth_user.php`
- [Cache layer](https://github.com/rootmax84/redbox-telemetry/blob/main/web/src/cache.php): `web/src/cache.php`
- [User quotas](https://github.com/rootmax84/redbox-telemetry/blob/main/web/src/db_limits.php): `web/src/db_limits.php`
- [Session retrieval](https://github.com/rootmax84/redbox-telemetry/blob/main/web/src/get_sessions.php): `web/src/get_sessions.php`

### Operations

- [Session operations](https://github.com/rootmax84/redbox-telemetry/blob/main/web/del_sessions.php): `web/del_sessions.php`
- [Background tasks](https://github.com/rootmax84/redbox-telemetry/blob/main/web/src/heavy_tasks.php): `web/src/heavy_tasks.php`
- [Admin panel](https://github.com/rootmax84/redbox-telemetry/blob/main/web/src/templates/index/partials/admin.php): `web/src/templates/index/partials/admin.php`
- [Log imports](https://github.com/rootmax84/redbox-telemetry/blob/main/web/import_redlog.php): `web/import_redlog.php`
- [Session export](https://github.com/rootmax84/redbox-telemetry/blob/main/web/export.php): `web/export.php`
- [Telemetry search](https://github.com/rootmax84/redbox-telemetry/blob/main/web/search_processor.php): `web/search_processor.php`

### Integrations

- [Session sharing](https://github.com/rootmax84/redbox-telemetry/blob/main/web/share.php): `web/share.php`
- [Remote controls](https://github.com/rootmax84/redbox-telemetry/blob/main/web/remote.php): `web/remote.php`
- [Live streaming](https://github.com/rootmax84/redbox-telemetry/blob/main/web/stream.php): `web/stream.php`
- [Latest metrics API](https://github.com/rootmax84/redbox-telemetry/blob/main/web/url.php): `web/url.php`
- [Prometheus exporter](https://github.com/rootmax84/redbox-telemetry/blob/main/prometheus/api_exporter.py): `prometheus/api_exporter.py`

### Other components

- **Vehicle devices**
- **Browser user**
- **Prometheus / Grafana**

## Connections

- Vehicle devices → Upload endpoint: submit logs
- Upload endpoint → Redis streams: enqueue upload
- Redis streams → Stream worker: deliver stream (evidence: `web/worker.php`)
- Stream worker → Upload processor: process upload (evidence: `web/worker.php`)
- Upload processor → Telemetry database: persist telemetry
- Upload endpoint → Upload processor: inline fallback
- Browser user → Login gate: sign in (evidence: `web/src/auth_user.php`)
- Login gate → Authentication: authenticate (evidence: `web/src/auth_user.php`)
- Browser user → Telemetry dashboard: open telemetry
- Telemetry dashboard → Dashboard view: render page (evidence: `web/src/pages/index.php`)
- Dashboard view → Charts and map: include chart (evidence: `web/src/templates/index/page.php`)
- Dashboard view → Session filters: include filters (evidence: `web/src/templates/index/page.php`)
- Telemetry dashboard → Session retrieval: load sessions
- Database access → Cache layer: initialize cache (evidence: `web/src/db.php`)
- Database access → Redis streams: connect Redis (evidence: `web/src/db.php`)
- Database access → Telemetry database: query database
- User quotas → Session retrieval: check usage (evidence: `web/src/db_limits.php`)
- Session operations → Background tasks: queue deletion (evidence: `web/src/heavy_tasks.php`)
- Stream worker → Background tasks: consume tasks (evidence: `web/worker.php`)
- Browser user → Log imports: import logs
- Browser user → Session export: export sessions
- Browser user → Telemetry search: search telemetry
- Browser user → Session sharing: share sessions
- Browser user → Remote controls: control settings
- Browser user → Live streaming: view live data
- Browser user → Latest metrics API: fetch latest metrics
- Prometheus exporter → Latest metrics API: fetch metrics
- Prometheus exporter → Prometheus / Grafana: expose metrics
- Dashboard view → Localization: localize interface
