# aman3214/fruit_monitor architecture

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

- Interactive diagram: https://gitdiagram.com/aman3214/fruit_monitor
- Repository: https://github.com/aman3214/fruit_monitor

## Overview

1. **System shape**
   This repository is a three-runtime IoT pipeline: an embedded/edge producer, a Python AI inference service, and a Node.js dashboard. A central **MQTT broker** is the main integration point between them.

2. **Root orchestrator**
   `main.py` is the process launcher. It starts the dashboard, AI processor, and mock/test data generator as separate subprocesses, so the repo behaves like one system even though the pieces run in different runtimes and directories.

3. **Edge data source**
   The hardware boundary is the **ESP32-CAM firmware** in `hardware/esp32_cam_firmware.ino`. It represents the real device that captures fruit images and sensor readings, then publishes them over MQTT. The root also includes `mock_esp32.py` and `test/test_output.py` for hardware-free simulation of that same data source.

4. **Message backbone**
   MQTT on port 1883 is the primary transport for telemetry and image payloads. It decouples the hardware/simulator from both downstream consumers: the AI engine and the dashboard.

5. **AI inference service**
   `ai_engine/ai_processor.py` is the core analytics service. It subscribes to MQTT, decodes incoming image data, and runs TensorFlow/Keras inference using `fruit_model.h5`. This service is the decision-making boundary where raw sensor/image streams become freshness/spoilage predictions.

6. **Model runtime artifacts**
   `ai_engine/fruit_model.h5` is the deployed inference artifact, while `ai_engine/env_requirements.txt` defines the Python runtime needed to execute it. This makes the inference service a separate deployable from the training code.

7. **Dashboard backend**
   `dashboard/server.js` is a Node.js bridge between MQTT and the browser UI. It receives live system data from MQTT and forwards it to clients over **Socket.io**, so the frontend can update in real time without speaking MQTT directly.

8. **Dashboard frontend**
   `dashboard/public/` contains the browser-facing presentation layer: `index.html`, `script.js`, and `style.css`. This layer is purely visualization and interaction; it depends on the backend websocket stream rather than talking to the hardware or AI service itself.

9. **Offline training pipeline**
   `fruit_trainer/` is the model-development subsystem. It contains the dataset layout, dataset reorganization scripts, and `train_model.py` that produces the `.h5` model consumed by the AI engine. The `FRUIT-16K` folder indicates the source dataset used to derive the training/validation splits.

10. **Data lifecycle**
    The end-to-end flow is: **ESP32-CAM or mock publisher → MQTT broker → AI processor for inference → dashboard for live display**. The model lifecycle is separate: **training dataset → trainer scripts → `fruit_model.h5` → AI engine**.

11. **Persistence and reporting**
    `logs/spoilage_report.json` suggests the system also emits structured output for later review or audit, likely summarizing spoilage events or inference results. This is an important boundary between live streaming and stored reporting.

12. **Testing and validation**
    `test/test_images` and the various `test_output` scripts provide a simulation and validation path for the pipeline without physical hardware. That makes the repository support both real-device operation and local demo/debug workflows.

13. **Key architectural separation**
    The repo is intentionally split by responsibility: embedded acquisition, ML inference, web presentation, and model training. The important diagram edges are the MQTT broker, the Socket.io bridge to browsers, and the handoff from training artifacts to the deployed AI engine.

Main entry points: [`ai_engine/ai_processor.py`](https://github.com/aman3214/fruit_monitor/blob/main/ai_engine/ai_processor.py) (AI processor), [`main.py`](https://github.com/aman3214/fruit_monitor/blob/main/main.py) (Main), [`mock_esp32.py`](https://github.com/aman3214/fruit_monitor/blob/main/mock_esp32.py) (Mock ESP32), [`dashboard/server.js`](https://github.com/aman3214/fruit_monitor/blob/main/dashboard/server.js) (Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_orchestration["Orchestration"]
  node_main_py["Main<br/>launcher<br/>[main.py]"]
  node_mqtt_broker(("MQTT broker<br/>message bus"))
end

subgraph group_group_edge["Edge capture"]
  node_hardware_esp32_cam_firmware_ino["ESP32-CAM<br/>firmware"]
  node_mock_esp32_py["Mock ESP32<br/>simulator<br/>[mock_esp32.py]"]
  node_test_test_output_py["Test output<br/>validation<br/>[test_output.py]"]
end

subgraph group_group_ai["AI inference"]
  node_ai_engine_ai_processor_py["AI processor<br/>inference service<br/>[ai_processor.py]"]
  node_ai_engine_fruit_model_h5["Fruit model<br/>model artifact<br/>[fruit_model.h5]"]
  node_ai_engine_env_requirements_txt["Python deps<br/>runtime spec"]
end

subgraph group_group_dashboard["Dashboard"]
  node_dashboard_server_js["Server<br/>web bridge<br/>[server.js]"]
  node_dashboard_public_index_html["UI shell<br/>frontend<br/>[index.html]"]
  node_dashboard_public_script_js["Client script<br/>frontend logic<br/>[script.js]"]
  node_dashboard_public_style_css["Styles<br/>presentation<br/>[style.css]"]
end

subgraph group_group_training["Training"]
  node_fruit_trainer_fruit_16k[("FRUIT-16K<br/>source dataset")]
  node_fruit_trainer_dataset[("Split data<br/>dataset")]
  node_fruit_trainer_train_model_py["Train model<br/>trainer<br/>[train_model.py]"]
end

subgraph group_group_reporting["Reporting"]
  node_logs_spoilage_report_json["Spoilage report"]
end

node_main_py -->|"launches"| node_mock_esp32_py
node_main_py -->|"launches"| node_ai_engine_ai_processor_py
node_main_py -->|"launches"| node_dashboard_server_js
node_mock_esp32_py -->|"publishes"| node_mqtt_broker
node_hardware_esp32_cam_firmware_ino -->|"publishes"| node_mqtt_broker
node_mqtt_broker -->|"subscribes"| node_ai_engine_ai_processor_py
node_mqtt_broker -->|"streams"| node_dashboard_server_js
node_dashboard_server_js -->|"socket.io"| node_dashboard_public_script_js
node_dashboard_public_index_html -->|"loads"| node_dashboard_public_script_js
node_dashboard_public_script_js -->|"uses"| node_dashboard_public_style_css
node_fruit_trainer_fruit_16k -->|"organizes"| node_fruit_trainer_dataset
node_fruit_trainer_dataset -->|"trains"| node_fruit_trainer_train_model_py
node_fruit_trainer_train_model_py -->|"exports"| node_ai_engine_fruit_model_h5
node_ai_engine_fruit_model_h5 -->|"loads"| node_ai_engine_ai_processor_py
node_ai_engine_env_requirements_txt -->|"supports"| node_ai_engine_ai_processor_py
node_ai_engine_ai_processor_py -->|"writes"| node_logs_spoilage_report_json
node_test_test_output_py -.->|"validates"| node_mock_esp32_py

click node_main_py "https://github.com/aman3214/fruit_monitor/blob/main/main.py"
click node_hardware_esp32_cam_firmware_ino "https://github.com/aman3214/fruit_monitor/blob/main/hardware/esp32_cam_firmware.ino"
click node_mock_esp32_py "https://github.com/aman3214/fruit_monitor/blob/main/mock_esp32.py"
click node_test_test_output_py "https://github.com/aman3214/fruit_monitor/blob/main/test/test_output.py"
click node_ai_engine_ai_processor_py "https://github.com/aman3214/fruit_monitor/blob/main/ai_engine/ai_processor.py"
click node_ai_engine_fruit_model_h5 "https://github.com/aman3214/fruit_monitor/blob/main/ai_engine/fruit_model.h5"
click node_ai_engine_env_requirements_txt "https://github.com/aman3214/fruit_monitor/blob/main/ai_engine/env_requirements.txt"
click node_dashboard_server_js "https://github.com/aman3214/fruit_monitor/blob/main/dashboard/server.js"
click node_dashboard_public_index_html "https://github.com/aman3214/fruit_monitor/blob/main/dashboard/public/index.html"
click node_dashboard_public_script_js "https://github.com/aman3214/fruit_monitor/blob/main/dashboard/public/script.js"
click node_dashboard_public_style_css "https://github.com/aman3214/fruit_monitor/blob/main/dashboard/public/style.css"
click node_fruit_trainer_fruit_16k "https://github.com/aman3214/fruit_monitor/tree/main/fruit_trainer/FRUIT-16K"
click node_fruit_trainer_dataset "https://github.com/aman3214/fruit_monitor/tree/main/fruit_trainer/dataset"
click node_fruit_trainer_train_model_py "https://github.com/aman3214/fruit_monitor/blob/main/fruit_trainer/train_model.py"
click node_logs_spoilage_report_json "https://github.com/aman3214/fruit_monitor/blob/main/logs/spoilage_report.json"

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_main_py,node_mqtt_broker toneBlue
class node_hardware_esp32_cam_firmware_ino,node_mock_esp32_py,node_test_test_output_py toneAmber
class node_ai_engine_ai_processor_py,node_ai_engine_fruit_model_h5,node_ai_engine_env_requirements_txt toneMint
class node_dashboard_server_js,node_dashboard_public_index_html,node_dashboard_public_script_js,node_dashboard_public_style_css toneRose
class node_fruit_trainer_fruit_16k,node_fruit_trainer_dataset,node_fruit_trainer_train_model_py toneIndigo
class node_logs_spoilage_report_json toneTeal
```

## Components

### Orchestration

Top-level launcher and shared runtime coordination

- [Main](https://github.com/aman3214/fruit_monitor/blob/main/main.py): launcher · Starts the dashboard, AI processor, and mock data generator as subprocesses · `main.py`
- **MQTT broker**: message bus · Central transport for telemetry and image payloads

### Edge capture

Physical and simulated fruit data sources

- [ESP32-CAM](https://github.com/aman3214/fruit_monitor/blob/main/hardware/esp32_cam_firmware.ino): firmware · Embedded producer that captures fruit data and publishes telemetry over MQTT · `hardware/esp32_cam_firmware.ino`
- [Mock ESP32](https://github.com/aman3214/fruit_monitor/blob/main/mock_esp32.py): simulator · Hardware-free publisher that mimics the edge device · `mock_esp32.py`
- [Test output](https://github.com/aman3214/fruit_monitor/blob/main/test/test_output.py): validation · Offline harness for generating or checking pipeline output · `test/test_output.py`

### AI inference

Python analytics and model runtime

- [AI processor](https://github.com/aman3214/fruit_monitor/blob/main/ai_engine/ai_processor.py): inference service · Subscribes to MQTT, decodes images, and runs freshness/spoilage prediction · `ai_engine/ai_processor.py`
- [Fruit model](https://github.com/aman3214/fruit_monitor/blob/main/ai_engine/fruit_model.h5): model artifact · Deployed Keras/TensorFlow inference model consumed by the AI processor · `ai_engine/fruit_model.h5`
- [Python deps](https://github.com/aman3214/fruit_monitor/blob/main/ai_engine/env_requirements.txt): runtime spec · Python dependency set for the inference service · `ai_engine/env_requirements.txt`

### Dashboard

Node.js live view and browser UI

- [Server](https://github.com/aman3214/fruit_monitor/blob/main/dashboard/server.js): web bridge · Bridges MQTT data to browser clients over Socket.io · `dashboard/server.js`
- [UI shell](https://github.com/aman3214/fruit_monitor/blob/main/dashboard/public/index.html): frontend · Browser entry page for the dashboard · `dashboard/public/index.html`
- [Client script](https://github.com/aman3214/fruit_monitor/blob/main/dashboard/public/script.js): frontend logic · Receives live updates and drives dashboard interaction · `dashboard/public/script.js`
- [Styles](https://github.com/aman3214/fruit_monitor/blob/main/dashboard/public/style.css): presentation · Visual styling for the browser dashboard · `dashboard/public/style.css`

### Training

Offline dataset preparation and model build

- [FRUIT-16K](https://github.com/aman3214/fruit_monitor/tree/main/fruit_trainer/FRUIT-16K): source dataset · Raw labeled fruit image corpus used for model development · `fruit_trainer/FRUIT-16K`
- [Split data](https://github.com/aman3214/fruit_monitor/tree/main/fruit_trainer/dataset): dataset · Prepared train and validation folders for fresh and spoiled fruit · `fruit_trainer/dataset`
- [Train model](https://github.com/aman3214/fruit_monitor/blob/main/fruit_trainer/train_model.py): trainer · Builds the fruit classification model used by inference · `fruit_trainer/train_model.py`

### Reporting

Persistent outputs and review artifacts

- [Spoilage report](https://github.com/aman3214/fruit_monitor/blob/main/logs/spoilage_report.json): report · Structured output for spoilage or inference review · `logs/spoilage_report.json`

## Connections

- Main → Mock ESP32: launches · Starts the simulator as part of the local system
- Main → AI processor: launches · Starts the inference service alongside the other components
- Main → Server: launches · Starts the dashboard backend process
- Mock ESP32 → MQTT broker: publishes · Emits simulated telemetry and image payloads
- ESP32-CAM → MQTT broker: publishes · Sends live device data to the message bus
- MQTT broker → AI processor: subscribes · Feeds telemetry and image streams into inference
- MQTT broker → Server: streams · Provides live system updates to the dashboard backend
- Server → Client script: socket.io · Pushes live updates to browser clients
- UI shell → Client script: loads · Hosts the dashboard client entry point
- Client script → Styles: uses · Applies dashboard presentation styles
- FRUIT-16K → Split data: organizes · Source images are curated into train and validation splits
- Split data → Train model: trains · Provides data for model fitting
- Train model → Fruit model: exports · Produces the deployed model artifact
- Fruit model → AI processor: loads · Inference service uses the trained model for predictions
- Python deps → AI processor: supports · Defines the Python runtime dependencies
- AI processor → Spoilage report: writes · Persists structured spoilage or inference results
- Test output → Mock ESP32: validates · Supports hardware-free pipeline checks
