# jeyms-what/smart-aquarium-iot architecture

> Architecture diagram of the GitHub repository jeyms-what/smart-aquarium-iot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jeyms-what/smart-aquarium-iot
- Repository: https://github.com/jeyms-what/smart-aquarium-iot

## Overview

Smart Aquarium IoT is an in-development aquarium monitoring and equipment-control system spanning a Flutter app, Node.js API, MQTT, PostgreSQL, and ESP32 firmware. The current implemented workflow exposes latest telemetry to the app, which also maintains local telemetry history; the backend ingests device messages and publishes commands, but publication does not establish physical execution. The README documents the broader intended device-to-app path, while sampled firmware is only a safe bootstrap. Unsampled mobile feature wiring and hardware integrations are not inferred.

Main entry points: [`backend/src/server.js`](https://github.com/jeyms-what/smart-aquarium-iot/blob/main/backend/src/server.js) (REST API), [`backend/src/mqtt.js`](https://github.com/jeyms-what/smart-aquarium-iot/blob/main/backend/src/mqtt.js) (MQTT ingestion and commands), [`infra/mosquitto/mosquitto.conf`](https://github.com/jeyms-what/smart-aquarium-iot/blob/main/infra/mosquitto/mosquitto.conf) (MQTT broker), [`backend/src/config.js`](https://github.com/jeyms-what/smart-aquarium-iot/blob/main/backend/src/config.js) (Backend configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mobile["Mobile application"]
  node_mobile_app["Flutter app<br/>[app.dart]"]
  node_dashboard["Dashboard"]
  node_control["Equipment control"]
  node_history["Telemetry history"]
  node_settings["Settings"]
  node_monitoring["Monitoring controller"]
  node_mobile_repo["Aquarium repository"]
  node_api_client["Telemetry API client"]
  node_telemetry_store[("Local telemetry store")]
  node_telemetry_model["Telemetry model"]
end

subgraph group_backend["Backend services"]
  node_api_server["REST API<br/>[server.js]"]
  node_auth["Bearer authentication<br/>[auth.js]"]
  node_validation["Message validation<br/>[validation.js]"]
  node_mqtt_ingest["MQTT ingestion and commands<br/>[mqtt.js]"]
  node_configuration["Backend configuration<br/>[config.js]"]
end

subgraph group_device["Device firmware"]
  node_firmware["ESP32 bootstrap<br/>[main.c]"]
end

subgraph group_infra["Messaging and storage"]
  node_mqtt_broker["MQTT broker<br/>[mosquitto.conf]"]
  node_postgres[("PostgreSQL<br/>[001_init.sql]")]
end

node_aquarium_user(("Aquarium user"))
node_device_sensors(("Aquarium sensors"))

node_aquarium_user -->|"uses"| node_mobile_app
node_mobile_repo -.->|"requests telemetry"| node_api_client
node_api_client -->|"fetches latest"| node_api_server
node_history -->|"reads history"| node_telemetry_store
node_api_server -->|"authenticates"| node_auth
node_api_server -->|"validates requests"| node_validation
node_api_server -->|"publishes commands"| node_mqtt_ingest
node_api_server -->|"queries and records"| node_postgres
node_mqtt_ingest -->|"validates messages"| node_validation
node_mqtt_ingest -->|"stores events and readings"| node_postgres
node_mqtt_ingest -->|"subscribes and publishes"| node_mqtt_broker
node_device_sensors -.->|"provide readings"| node_firmware
node_firmware -.->|"sends device messages"| node_mqtt_broker
node_mqtt_broker -->|"forwards messages"| node_mqtt_ingest
node_configuration -->|"configures service"| node_api_server
node_configuration -->|"configures connection"| node_mqtt_ingest

click node_mobile_app "https://github.com/jeyms-what/smart-aquarium-iot/blob/main/mobile/lib/app.dart"
click node_dashboard "https://github.com/jeyms-what/smart-aquarium-iot/blob/main/mobile/lib/features/dashboard/dashboard_screen.dart"
click node_control "https://github.com/jeyms-what/smart-aquarium-iot/blob/main/mobile/lib/features/control/control_screen.dart"
click node_history "https://github.com/jeyms-what/smart-aquarium-iot/blob/main/mobile/lib/features/history/history_screen.dart"
click node_settings "https://github.com/jeyms-what/smart-aquarium-iot/blob/main/mobile/lib/features/settings/settings_screen.dart"
click node_monitoring "https://github.com/jeyms-what/smart-aquarium-iot/blob/main/mobile/lib/features/monitoring/monitoring_controller.dart"
click node_mobile_repo "https://github.com/jeyms-what/smart-aquarium-iot/blob/main/mobile/lib/data/repositories/aquarium_repository.dart"
click node_api_client "https://github.com/jeyms-what/smart-aquarium-iot/blob/main/mobile/lib/data/remote/telemetry_api_client.dart"
click node_telemetry_store "https://github.com/jeyms-what/smart-aquarium-iot/blob/main/mobile/lib/data/local/telemetry_store.dart"
click node_telemetry_model "https://github.com/jeyms-what/smart-aquarium-iot/blob/main/mobile/lib/data/models/telemetry_reading.dart"
click node_api_server "https://github.com/jeyms-what/smart-aquarium-iot/blob/main/backend/src/server.js"
click node_auth "https://github.com/jeyms-what/smart-aquarium-iot/blob/main/backend/src/auth.js"
click node_validation "https://github.com/jeyms-what/smart-aquarium-iot/blob/main/backend/src/validation.js"
click node_mqtt_ingest "https://github.com/jeyms-what/smart-aquarium-iot/blob/main/backend/src/mqtt.js"
click node_configuration "https://github.com/jeyms-what/smart-aquarium-iot/blob/main/backend/src/config.js"
click node_firmware "https://github.com/jeyms-what/smart-aquarium-iot/blob/main/firmware/main/main.c"
click node_mqtt_broker "https://github.com/jeyms-what/smart-aquarium-iot/blob/main/infra/mosquitto/mosquitto.conf"
click node_postgres "https://github.com/jeyms-what/smart-aquarium-iot/blob/main/backend/migrations/001_init.sql"

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_mobile_app,node_dashboard,node_control,node_history,node_settings,node_monitoring,node_mobile_repo,node_api_client,node_telemetry_store,node_telemetry_model,node_aquarium_user toneBlue
class node_api_server,node_auth,node_validation,node_mqtt_ingest,node_configuration toneAmber
class node_firmware toneMint
class node_mqtt_broker,node_postgres toneRose
class node_device_sensors toneIndigo
```

## Components

### Mobile application

- [Flutter app](https://github.com/jeyms-what/smart-aquarium-iot/blob/main/mobile/lib/app.dart): `mobile/lib/app.dart`
- [Dashboard](https://github.com/jeyms-what/smart-aquarium-iot/blob/main/mobile/lib/features/dashboard/dashboard_screen.dart): `mobile/lib/features/dashboard/dashboard_screen.dart`
- [Equipment control](https://github.com/jeyms-what/smart-aquarium-iot/blob/main/mobile/lib/features/control/control_screen.dart): `mobile/lib/features/control/control_screen.dart`
- [Telemetry history](https://github.com/jeyms-what/smart-aquarium-iot/blob/main/mobile/lib/features/history/history_screen.dart): `mobile/lib/features/history/history_screen.dart`
- [Settings](https://github.com/jeyms-what/smart-aquarium-iot/blob/main/mobile/lib/features/settings/settings_screen.dart): `mobile/lib/features/settings/settings_screen.dart`
- [Monitoring controller](https://github.com/jeyms-what/smart-aquarium-iot/blob/main/mobile/lib/features/monitoring/monitoring_controller.dart): `mobile/lib/features/monitoring/monitoring_controller.dart`
- [Aquarium repository](https://github.com/jeyms-what/smart-aquarium-iot/blob/main/mobile/lib/data/repositories/aquarium_repository.dart): `mobile/lib/data/repositories/aquarium_repository.dart`
- [Telemetry API client](https://github.com/jeyms-what/smart-aquarium-iot/blob/main/mobile/lib/data/remote/telemetry_api_client.dart): `mobile/lib/data/remote/telemetry_api_client.dart`
- [Local telemetry store](https://github.com/jeyms-what/smart-aquarium-iot/blob/main/mobile/lib/data/local/telemetry_store.dart): `mobile/lib/data/local/telemetry_store.dart`
- [Telemetry model](https://github.com/jeyms-what/smart-aquarium-iot/blob/main/mobile/lib/data/models/telemetry_reading.dart): `mobile/lib/data/models/telemetry_reading.dart`

### Backend services

- [REST API](https://github.com/jeyms-what/smart-aquarium-iot/blob/main/backend/src/server.js): `backend/src/server.js`
- [Bearer authentication](https://github.com/jeyms-what/smart-aquarium-iot/blob/main/backend/src/auth.js): `backend/src/auth.js`
- [Message validation](https://github.com/jeyms-what/smart-aquarium-iot/blob/main/backend/src/validation.js): `backend/src/validation.js`
- [MQTT ingestion and commands](https://github.com/jeyms-what/smart-aquarium-iot/blob/main/backend/src/mqtt.js): `backend/src/mqtt.js`
- [Backend configuration](https://github.com/jeyms-what/smart-aquarium-iot/blob/main/backend/src/config.js): `backend/src/config.js`

### Device firmware

- [ESP32 bootstrap](https://github.com/jeyms-what/smart-aquarium-iot/blob/main/firmware/main/main.c): `firmware/main/main.c`

### Messaging and storage

- [MQTT broker](https://github.com/jeyms-what/smart-aquarium-iot/blob/main/infra/mosquitto/mosquitto.conf): `infra/mosquitto/mosquitto.conf`
- [PostgreSQL](https://github.com/jeyms-what/smart-aquarium-iot/blob/main/backend/migrations/001_init.sql): `backend/migrations/001_init.sql`

### Other components

- **Aquarium user**
- **Aquarium sensors**

## Connections

- Aquarium user → Flutter app: uses (evidence: `README.md`)
- Aquarium repository → Telemetry API client: requests telemetry
- Telemetry API client → REST API: fetches latest (evidence: `README.md`)
- Telemetry history → Local telemetry store: reads history (evidence: `README.md`)
- REST API → Bearer authentication: authenticates (evidence: `backend/src/server.js`)
- REST API → Message validation: validates requests (evidence: `backend/src/server.js`)
- REST API → MQTT ingestion and commands: publishes commands (evidence: `backend/src/server.js`)
- REST API → PostgreSQL: queries and records (evidence: `backend/src/server.js`)
- MQTT ingestion and commands → Message validation: validates messages (evidence: `backend/src/mqtt.js`)
- MQTT ingestion and commands → PostgreSQL: stores events and readings (evidence: `backend/src/mqtt.js`)
- MQTT ingestion and commands → MQTT broker: subscribes and publishes (evidence: `README.md`)
- Aquarium sensors → ESP32 bootstrap: provide readings (evidence: `README.md`)
- ESP32 bootstrap → MQTT broker: sends device messages (evidence: `README.md`)
- MQTT broker → MQTT ingestion and commands: forwards messages (evidence: `README.md`)
- Backend configuration → REST API: configures service (evidence: `backend/src/server.js`)
- Backend configuration → MQTT ingestion and commands: configures connection (evidence: `backend/src/mqtt.js`)