# markkyrollos/tameer architecture

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

- Interactive diagram: https://gitdiagram.com/markkyrollos/tameer
- Repository: https://github.com/markkyrollos/tameer

## Overview

Tameer is an IoT agricultural monitoring and control product: field devices send sensor readings through MQTT, the backend validates and stores them, evaluates automation rules, and returns actuator commands; farmers and engineers view readings and control status in a bilingual PWA. The backend also exposes camera, voice, and debug routes, while a separate TameerML service provides image diagnosis and sensor/image fusion inference. The README and sampled source establish the MQTT, storage, automation, and PWA flows; wiring for several unsampled routes is left unspecified.

Main entry points: [`backend/services/mqtt_service.py`](https://github.com/markkyrollos/tameer/blob/main/backend/services/mqtt_service.py) (MQTT ingestion), [`backend/main.py`](https://github.com/markkyrollos/tameer/blob/main/backend/main.py) (FastAPI application), [`backend/services/influx_service.py`](https://github.com/markkyrollos/tameer/blob/main/backend/services/influx_service.py) (InfluxDB access), [`tameer-pwa/src/App.tsx`](https://github.com/markkyrollos/tameer/blob/main/tameer-pwa/src/App.tsx) (PWA routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_field["Field and brokers"]
  node_field_nodes(("ESP32 nodes"))
  node_hivemq["HiveMQ broker"]
end

subgraph group_backend["Backend processing"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_schemas["Payload validation<br/>[schemas.py]"]
  node_mqtt["MQTT ingestion<br/>[mqtt_service.py]"]
  node_automation["Automation rules<br/>[automation.py]"]
  node_sensor_api["Sensor API<br/>[sensors.py]"]
  node_automation_api["Automation API<br/>[automation.py]"]
  node_camera_api["Camera API<br/>[camera.py]"]
  node_voice_api["Voice API<br/>[voice.py]"]
  node_debug_api["Debug dashboard<br/>[debug.py]"]
  node_debug_bus["Debug event bus<br/>[debug_bus.py]"]
end

subgraph group_storage["Persistence and inference"]
  node_influx_service["InfluxDB access<br/>[influx_service.py]"]
  node_influx[("InfluxDB")]
  node_ml_service["ML client<br/>[ml_service.py]"]
  node_ml_app["TameerML inference<br/>[app.py]"]
end

subgraph group_frontend["PWA experience"]
  node_pwa_app["PWA routes<br/>[App.tsx]"]
  node_farmer_view["Farmer dashboard<br/>[FarmerView.tsx]"]
  node_engineer_view["Engineer dashboard<br/>[EngineerView.tsx]"]
  node_plant_health["Plant health view"]
  node_hooks["Data hooks"]
  node_api_client["API client"]
end

node_farmers(("Farmers and engineers"))

node_field_nodes -->|"publish readings"| node_hivemq
node_hivemq -->|"deliver readings"| node_mqtt
node_mqtt -->|"validate payloads"| node_schemas
node_mqtt -->|"write readings"| node_influx_service
node_mqtt -->|"evaluate readings"| node_automation
node_automation -->|"publish commands"| node_mqtt
node_mqtt -->|"publish commands"| node_hivemq
node_hivemq -->|"deliver commands"| node_field_nodes
node_mqtt -->|"emit events"| node_debug_bus
node_influx_service -->|"emit write status"| node_debug_bus
node_influx_service -->|"read and write"| node_influx
node_api_app -->|"start and stop"| node_mqtt
node_api_app -->|"register routes"| node_sensor_api
node_api_app -->|"register routes"| node_automation_api
node_api_app -->|"register routes"| node_camera_api
node_api_app -->|"register routes"| node_voice_api
node_api_app -->|"register routes"| node_debug_api
node_sensor_api -->|"query readings"| node_influx_service
node_automation_api -->|"query events"| node_influx_service
node_automation_api -->|"send overrides"| node_mqtt
node_debug_api -->|"stream events"| node_debug_bus
node_debug_api -->|"query debug data"| node_influx_service
node_camera_api -->|"record image data"| node_influx_service
node_ml_service -.->|"request inference"| node_ml_app
node_farmers -->|"use dashboard"| node_pwa_app
node_pwa_app -->|"render view"| node_farmer_view
node_pwa_app -->|"render view"| node_engineer_view
node_pwa_app -->|"render view"| node_plant_health
node_farmer_view -->|"load dashboard data"| node_hooks
node_engineer_view -->|"load readings and events"| node_hooks
node_plant_health -->|"load health data"| node_hooks
node_hooks -->|"request data"| node_api_client
node_api_client -->|"call REST API"| node_api_app

click node_api_app "https://github.com/markkyrollos/tameer/blob/main/backend/main.py"
click node_schemas "https://github.com/markkyrollos/tameer/blob/main/backend/models/schemas.py"
click node_mqtt "https://github.com/markkyrollos/tameer/blob/main/backend/services/mqtt_service.py"
click node_automation "https://github.com/markkyrollos/tameer/blob/main/backend/services/automation.py"
click node_sensor_api "https://github.com/markkyrollos/tameer/blob/main/backend/routers/sensors.py"
click node_automation_api "https://github.com/markkyrollos/tameer/blob/main/backend/routers/automation.py"
click node_camera_api "https://github.com/markkyrollos/tameer/blob/main/backend/routers/camera.py"
click node_voice_api "https://github.com/markkyrollos/tameer/blob/main/backend/routers/voice.py"
click node_debug_api "https://github.com/markkyrollos/tameer/blob/main/backend/routers/debug.py"
click node_debug_bus "https://github.com/markkyrollos/tameer/blob/main/backend/services/debug_bus.py"
click node_influx_service "https://github.com/markkyrollos/tameer/blob/main/backend/services/influx_service.py"
click node_ml_service "https://github.com/markkyrollos/tameer/blob/main/backend/services/ml_service.py"
click node_ml_app "https://github.com/markkyrollos/tameer/blob/main/TameerML-main/app.py"
click node_pwa_app "https://github.com/markkyrollos/tameer/blob/main/tameer-pwa/src/App.tsx"
click node_farmer_view "https://github.com/markkyrollos/tameer/blob/main/tameer-pwa/src/pages/FarmerView.tsx"
click node_engineer_view "https://github.com/markkyrollos/tameer/blob/main/tameer-pwa/src/pages/EngineerView.tsx"
click node_plant_health "https://github.com/markkyrollos/tameer/blob/main/tameer-pwa/src/pages/PlantHealthView.tsx"
click node_hooks "https://github.com/markkyrollos/tameer/tree/main/tameer-pwa/src/hooks"
click node_api_client "https://github.com/markkyrollos/tameer/tree/main/tameer-pwa/src/api"

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_field_nodes,node_hivemq toneBlue
class node_api_app,node_schemas,node_mqtt,node_automation,node_sensor_api,node_automation_api,node_camera_api,node_voice_api,node_debug_api,node_debug_bus toneAmber
class node_influx_service,node_influx,node_ml_service,node_ml_app toneMint
class node_pwa_app,node_farmer_view,node_engineer_view,node_plant_health,node_hooks,node_api_client toneRose
class node_farmers toneIndigo
```

## Components

### Field and brokers

- **ESP32 nodes**
- **HiveMQ broker**

### Backend processing

- [FastAPI application](https://github.com/markkyrollos/tameer/blob/main/backend/main.py): `backend/main.py`
- [Payload validation](https://github.com/markkyrollos/tameer/blob/main/backend/models/schemas.py): `backend/models/schemas.py`
- [MQTT ingestion](https://github.com/markkyrollos/tameer/blob/main/backend/services/mqtt_service.py): `backend/services/mqtt_service.py`
- [Automation rules](https://github.com/markkyrollos/tameer/blob/main/backend/services/automation.py): `backend/services/automation.py`
- [Sensor API](https://github.com/markkyrollos/tameer/blob/main/backend/routers/sensors.py): `backend/routers/sensors.py`
- [Automation API](https://github.com/markkyrollos/tameer/blob/main/backend/routers/automation.py): `backend/routers/automation.py`
- [Camera API](https://github.com/markkyrollos/tameer/blob/main/backend/routers/camera.py): `backend/routers/camera.py`
- [Voice API](https://github.com/markkyrollos/tameer/blob/main/backend/routers/voice.py): `backend/routers/voice.py`
- [Debug dashboard](https://github.com/markkyrollos/tameer/blob/main/backend/routers/debug.py): `backend/routers/debug.py`
- [Debug event bus](https://github.com/markkyrollos/tameer/blob/main/backend/services/debug_bus.py): `backend/services/debug_bus.py`

### Persistence and inference

- [InfluxDB access](https://github.com/markkyrollos/tameer/blob/main/backend/services/influx_service.py): `backend/services/influx_service.py`
- **InfluxDB**
- [ML client](https://github.com/markkyrollos/tameer/blob/main/backend/services/ml_service.py): `backend/services/ml_service.py`
- [TameerML inference](https://github.com/markkyrollos/tameer/blob/main/TameerML-main/app.py): `TameerML-main/app.py`

### PWA experience

- [PWA routes](https://github.com/markkyrollos/tameer/blob/main/tameer-pwa/src/App.tsx): `tameer-pwa/src/App.tsx`
- [Farmer dashboard](https://github.com/markkyrollos/tameer/blob/main/tameer-pwa/src/pages/FarmerView.tsx): `tameer-pwa/src/pages/FarmerView.tsx`
- [Engineer dashboard](https://github.com/markkyrollos/tameer/blob/main/tameer-pwa/src/pages/EngineerView.tsx): `tameer-pwa/src/pages/EngineerView.tsx`
- [Plant health view](https://github.com/markkyrollos/tameer/blob/main/tameer-pwa/src/pages/PlantHealthView.tsx): `tameer-pwa/src/pages/PlantHealthView.tsx`
- [Data hooks](https://github.com/markkyrollos/tameer/tree/main/tameer-pwa/src/hooks): `tameer-pwa/src/hooks`
- [API client](https://github.com/markkyrollos/tameer/tree/main/tameer-pwa/src/api): `tameer-pwa/src/api`

### Other components

- **Farmers and engineers**

## Connections

- ESP32 nodes → HiveMQ broker: publish readings
- HiveMQ broker → MQTT ingestion: deliver readings
- MQTT ingestion → Payload validation: validate payloads
- MQTT ingestion → InfluxDB access: write readings
- MQTT ingestion → Automation rules: evaluate readings
- Automation rules → MQTT ingestion: publish commands
- MQTT ingestion → HiveMQ broker: publish commands
- HiveMQ broker → ESP32 nodes: deliver commands
- MQTT ingestion → Debug event bus: emit events
- InfluxDB access → Debug event bus: emit write status
- InfluxDB access → InfluxDB: read and write
- FastAPI application → MQTT ingestion: start and stop
- FastAPI application → Sensor API: register routes
- FastAPI application → Automation API: register routes
- FastAPI application → Camera API: register routes
- FastAPI application → Voice API: register routes
- FastAPI application → Debug dashboard: register routes
- Sensor API → InfluxDB access: query readings
- Automation API → InfluxDB access: query events
- Automation API → MQTT ingestion: send overrides
- Debug dashboard → Debug event bus: stream events
- Debug dashboard → InfluxDB access: query debug data
- Camera API → InfluxDB access: record image data
- ML client → TameerML inference: request inference
- Farmers and engineers → PWA routes: use dashboard
- PWA routes → Farmer dashboard: render view
- PWA routes → Engineer dashboard: render view
- PWA routes → Plant health view: render view
- Farmer dashboard → Data hooks: load dashboard data
- Engineer dashboard → Data hooks: load readings and events
- Plant health view → Data hooks: load health data
- Data hooks → API client: request data
- API client → FastAPI application: call REST API