# intimaria/okarina architecture

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

- Interactive diagram: https://gitdiagram.com/intimaria/okarina
- Repository: https://github.com/intimaria/okarina

## Overview

OKARINA is an environmental telemetry platform: ESP32 sensor nodes and a Tuya meter publish readings over MQTT, Telegraf ingests them into InfluxDB, and Grafana and a lightweight web view expose results. Ansible provisions the server and stack. The README documents the main deployment and telemetry links; the query and Tuya publisher excerpts additionally show their direct runtime interactions. Other links reflect documented configuration, not inspected implementation details.

Main entry points: [`mosquitto/mosquitto.conf`](https://github.com/intimaria/okarina/blob/main/mosquitto/mosquitto.conf) (MQTT broker), [`docker-compose.yml`](https://github.com/intimaria/okarina/blob/main/docker-compose.yml) (InfluxDB), [`web/latest-json/query.py`](https://github.com/intimaria/okarina/blob/main/web/latest-json/query.py) (Latest data query), [`telegraf/telegraf.conf`](https://github.com/intimaria/okarina/blob/main/telegraf/telegraf.conf) (Telegraf ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sensing["Sensors and publishers"]
  node_sensor_fleet["ESP32 sensor nodes"]
  node_tuya_meter["Tuya meter publisher<br/>[publisher.py]"]
end

subgraph group_ingestion["Telemetry ingestion"]
  node_broker["MQTT broker<br/>[mosquitto.conf]"]
  node_telegraf["Telegraf ingestion<br/>[telegraf.conf]"]
  node_influx[("InfluxDB<br/>[docker-compose.yml]")]
end

subgraph group_views["Monitoring views"]
  node_latest_query["Latest data query<br/>[query.py]"]
  node_latest_file["Latest JSON file<br/>[query.py]"]
  node_web_site["Web pages<br/>[index.html]"]
  node_grafana["Grafana dashboards"]
  node_grafana_source["Grafana datasource<br/>[influxdb.yaml]"]
end

subgraph group_operations["Deployment and access"]
  node_ansible["Ansible provisioning<br/>[playbook.yml]"]
  node_stack["Container stack<br/>[docker-compose.yml]"]
  node_tunnel["Cloudflare Tunnel<br/>[docker-compose.yml]"]
end

node_visitor(("Dashboard visitor"))

node_sensor_fleet -->|"publishes telemetry"| node_broker
node_tuya_meter -->|"publishes telemetry"| node_broker
node_broker -->|"feeds MQTT"| node_telegraf
node_telegraf -->|"writes readings"| node_influx
node_latest_query -->|"queries readings"| node_influx
node_latest_query -->|"writes JSON"| node_latest_file
node_web_site -->|"reads JSON"| node_latest_file
node_grafana_source -->|"configures datasource"| node_influx
node_visitor -->|"views dashboards"| node_grafana
node_ansible -->|"provisions stack"| node_stack
node_visitor -->|"accesses Grafana"| node_tunnel
node_tunnel -->|"routes traffic"| node_grafana

click node_sensor_fleet "https://github.com/intimaria/okarina/tree/main/firmware"
click node_tuya_meter "https://github.com/intimaria/okarina/blob/main/tuya-publisher/publisher.py"
click node_broker "https://github.com/intimaria/okarina/blob/main/mosquitto/mosquitto.conf"
click node_telegraf "https://github.com/intimaria/okarina/blob/main/telegraf/telegraf.conf"
click node_influx "https://github.com/intimaria/okarina/blob/main/docker-compose.yml"
click node_latest_query "https://github.com/intimaria/okarina/blob/main/web/latest-json/query.py"
click node_latest_file "https://github.com/intimaria/okarina/blob/main/web/latest-json/query.py"
click node_web_site "https://github.com/intimaria/okarina/blob/main/web/site/index.html"
click node_grafana "https://github.com/intimaria/okarina/tree/main/grafana/provisioning/dashboards"
click node_grafana_source "https://github.com/intimaria/okarina/blob/main/grafana/provisioning/datasources/influxdb.yaml"
click node_ansible "https://github.com/intimaria/okarina/blob/main/ansible/playbook.yml"
click node_stack "https://github.com/intimaria/okarina/blob/main/docker-compose.yml"
click node_tunnel "https://github.com/intimaria/okarina/blob/main/docker-compose.yml"

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_sensor_fleet,node_tuya_meter toneBlue
class node_broker,node_telegraf,node_influx toneAmber
class node_latest_query,node_latest_file,node_web_site,node_grafana,node_grafana_source toneMint
class node_ansible,node_stack,node_tunnel toneRose
class node_visitor toneIndigo
```

## Components

### Sensors and publishers

- [ESP32 sensor nodes](https://github.com/intimaria/okarina/tree/main/firmware): `firmware`
- [Tuya meter publisher](https://github.com/intimaria/okarina/blob/main/tuya-publisher/publisher.py): `tuya-publisher/publisher.py`

### Telemetry ingestion

- [MQTT broker](https://github.com/intimaria/okarina/blob/main/mosquitto/mosquitto.conf): `mosquitto/mosquitto.conf`
- [Telegraf ingestion](https://github.com/intimaria/okarina/blob/main/telegraf/telegraf.conf): `telegraf/telegraf.conf`
- [InfluxDB](https://github.com/intimaria/okarina/blob/main/docker-compose.yml): `docker-compose.yml`

### Monitoring views

- [Latest data query](https://github.com/intimaria/okarina/blob/main/web/latest-json/query.py): `web/latest-json/query.py`
- [Latest JSON file](https://github.com/intimaria/okarina/blob/main/web/latest-json/query.py): `web/latest-json/query.py`
- [Web pages](https://github.com/intimaria/okarina/blob/main/web/site/index.html): `web/site/index.html`
- [Grafana dashboards](https://github.com/intimaria/okarina/tree/main/grafana/provisioning/dashboards): `grafana/provisioning/dashboards`
- [Grafana datasource](https://github.com/intimaria/okarina/blob/main/grafana/provisioning/datasources/influxdb.yaml): `grafana/provisioning/datasources/influxdb.yaml`

### Deployment and access

- [Ansible provisioning](https://github.com/intimaria/okarina/blob/main/ansible/playbook.yml): `ansible/playbook.yml`
- [Container stack](https://github.com/intimaria/okarina/blob/main/docker-compose.yml): `docker-compose.yml`
- [Cloudflare Tunnel](https://github.com/intimaria/okarina/blob/main/docker-compose.yml): `docker-compose.yml`

### Other components

- **Dashboard visitor**

## Connections

- ESP32 sensor nodes → MQTT broker: publishes telemetry (evidence: `README.md`)
- Tuya meter publisher → MQTT broker: publishes telemetry (evidence: `tuya-publisher/publisher.py`)
- MQTT broker → Telegraf ingestion: feeds MQTT (evidence: `README.md`)
- Telegraf ingestion → InfluxDB: writes readings (evidence: `README.md`)
- Latest data query → InfluxDB: queries readings (evidence: `web/latest-json/query.py`)
- Latest data query → Latest JSON file: writes JSON (evidence: `web/latest-json/query.py`)
- Web pages → Latest JSON file: reads JSON (evidence: `web/latest-json/query.py`)
- Grafana datasource → InfluxDB: configures datasource (evidence: `README.md`)
- Dashboard visitor → Grafana dashboards: views dashboards (evidence: `README.md`)
- Ansible provisioning → Container stack: provisions stack (evidence: `README.md`)
- Dashboard visitor → Cloudflare Tunnel: accesses Grafana (evidence: `README.md`)
- Cloudflare Tunnel → Grafana dashboards: routes traffic (evidence: `README.md`)
