# juliabonetto/ecoscamserver2 architecture

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

- Interactive diagram: https://gitdiagram.com/juliabonetto/ecoscamserver2
- Repository: https://github.com/juliabonetto/ecoscamserver2

## Overview

EcoS-cam is a FastAPI backend for a camera-equipped waste-sorting device. Its main workflow accepts a device image, classifies the waste, and supports device commands and manual selection; other documented endpoints manage device activation and bin-fill alerts. The excerpts show database access and model loading, but omit parts of the current server implementation, so uncertain internal calls are not drawn.

Main entry points: [`server.py`](https://github.com/juliabonetto/ecoscamserver2/blob/main/server.py) (Transient device state), [`keras_model.h5`](https://github.com/juliabonetto/ecoscamserver2/blob/main/keras_model.h5) (Classifier model), [`labels.txt`](https://github.com/juliabonetto/ecoscamserver2/blob/main/labels.txt) (Class labels)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_classification["Waste classification"]
  node_classify["Classify image<br/>[server.py]"]
  node_model["Classifier model<br/>[keras_model.h5]"]
  node_labels["Class labels<br/>[labels.txt]"]
end

subgraph group_device["Device management"]
  node_api["EcoS-cam API<br/>[server.py]"]
  node_register["Register device<br/>[server.py]"]
  node_enable["Enable device<br/>[server.py]"]
  node_disable["Disable device<br/>[server.py]"]
  node_device_status["Device status<br/>[server.py]"]
end

subgraph group_control["Sorting and alerts"]
  node_manual["Manual selection<br/>[server.py]"]
  node_tacho["Bin control<br/>[server.py]"]
  node_command["Device commands<br/>[server.py]"]
  node_fill_alert["Fill alerts<br/>[server.py]"]
  node_fill_clear["Clear fill alert<br/>[server.py]"]
end

subgraph group_storage["State and storage"]
  node_app_state[("Transient device state<br/>[server.py]")]
  node_mysql[("MySQL database")]
end

node_esp32(("ESP32 device"))
node_operator(("Device operator"))

node_esp32 -->|"sends image"| node_classify
node_classify -->|"loads model"| node_model
node_classify -->|"uses labels"| node_labels
node_classify -->|"checks device"| node_mysql
node_operator -->|"registers"| node_register
node_register -->|"creates device"| node_mysql
node_operator -->|"enables"| node_enable
node_enable -->|"updates device"| node_mysql
node_operator -->|"disables"| node_disable
node_disable -->|"updates device"| node_mysql
node_esp32 -->|"requests status"| node_device_status
node_device_status -->|"reads device"| node_mysql
node_operator -->|"selects category"| node_manual
node_manual -->|"reads classification"| node_app_state
node_manual -->|"updates state"| node_app_state
node_esp32 -->|"polls commands"| node_command
node_command -->|"checks device"| node_mysql
node_command -->|"reads commands"| node_app_state
node_esp32 -->|"sends control"| node_tacho
node_tacho -->|"updates state"| node_app_state
node_esp32 -->|"reports fill"| node_fill_alert
node_fill_alert -->|"checks device"| node_mysql
node_fill_alert -->|"updates alert"| node_app_state
node_operator -->|"clears alert"| node_fill_clear
node_fill_clear -->|"checks device"| node_mysql
node_fill_clear -->|"clears alert"| node_app_state

click node_api "https://github.com/juliabonetto/ecoscamserver2/blob/main/server.py"
click node_register "https://github.com/juliabonetto/ecoscamserver2/blob/main/server.py"
click node_enable "https://github.com/juliabonetto/ecoscamserver2/blob/main/server.py"
click node_disable "https://github.com/juliabonetto/ecoscamserver2/blob/main/server.py"
click node_device_status "https://github.com/juliabonetto/ecoscamserver2/blob/main/server.py"
click node_classify "https://github.com/juliabonetto/ecoscamserver2/blob/main/server.py"
click node_model "https://github.com/juliabonetto/ecoscamserver2/blob/main/keras_model.h5"
click node_labels "https://github.com/juliabonetto/ecoscamserver2/blob/main/labels.txt"
click node_manual "https://github.com/juliabonetto/ecoscamserver2/blob/main/server.py"
click node_tacho "https://github.com/juliabonetto/ecoscamserver2/blob/main/server.py"
click node_command "https://github.com/juliabonetto/ecoscamserver2/blob/main/server.py"
click node_fill_alert "https://github.com/juliabonetto/ecoscamserver2/blob/main/server.py"
click node_fill_clear "https://github.com/juliabonetto/ecoscamserver2/blob/main/server.py"
click node_app_state "https://github.com/juliabonetto/ecoscamserver2/blob/main/server.py"

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_classify,node_model,node_labels toneBlue
class node_api,node_register,node_enable,node_disable,node_device_status toneAmber
class node_manual,node_tacho,node_command,node_fill_alert,node_fill_clear toneMint
class node_app_state,node_mysql toneRose
class node_esp32,node_operator toneIndigo
```

## Components

### Waste classification

- [Classify image](https://github.com/juliabonetto/ecoscamserver2/blob/main/server.py): `server.py`
- [Classifier model](https://github.com/juliabonetto/ecoscamserver2/blob/main/keras_model.h5): `keras_model.h5`
- [Class labels](https://github.com/juliabonetto/ecoscamserver2/blob/main/labels.txt): `labels.txt`

### Device management

- [EcoS-cam API](https://github.com/juliabonetto/ecoscamserver2/blob/main/server.py): `server.py`
- [Register device](https://github.com/juliabonetto/ecoscamserver2/blob/main/server.py): `server.py`
- [Enable device](https://github.com/juliabonetto/ecoscamserver2/blob/main/server.py): `server.py`
- [Disable device](https://github.com/juliabonetto/ecoscamserver2/blob/main/server.py): `server.py`
- [Device status](https://github.com/juliabonetto/ecoscamserver2/blob/main/server.py): `server.py`

### Sorting and alerts

- [Manual selection](https://github.com/juliabonetto/ecoscamserver2/blob/main/server.py): `server.py`
- [Bin control](https://github.com/juliabonetto/ecoscamserver2/blob/main/server.py): `server.py`
- [Device commands](https://github.com/juliabonetto/ecoscamserver2/blob/main/server.py): `server.py`
- [Fill alerts](https://github.com/juliabonetto/ecoscamserver2/blob/main/server.py): `server.py`
- [Clear fill alert](https://github.com/juliabonetto/ecoscamserver2/blob/main/server.py): `server.py`

### State and storage

- [Transient device state](https://github.com/juliabonetto/ecoscamserver2/blob/main/server.py): `server.py`
- **MySQL database**

### Other components

- **ESP32 device**
- **Device operator**

## Connections

- ESP32 device → Classify image: sends image
- Classify image → Classifier model: loads model
- Classify image → Class labels: uses labels
- Classify image → MySQL database: checks device
- Device operator → Register device: registers
- Register device → MySQL database: creates device
- Device operator → Enable device: enables
- Enable device → MySQL database: updates device
- Device operator → Disable device: disables
- Disable device → MySQL database: updates device
- ESP32 device → Device status: requests status
- Device status → MySQL database: reads device
- Device operator → Manual selection: selects category
- Manual selection → Transient device state: reads classification
- Manual selection → Transient device state: updates state
- ESP32 device → Device commands: polls commands
- Device commands → MySQL database: checks device
- Device commands → Transient device state: reads commands
- ESP32 device → Bin control: sends control
- Bin control → Transient device state: updates state
- ESP32 device → Fill alerts: reports fill
- Fill alerts → MySQL database: checks device
- Fill alerts → Transient device state: updates alert
- Device operator → Clear fill alert: clears alert
- Clear fill alert → MySQL database: checks device
- Clear fill alert → Transient device state: clears alert