# crazydw4rf/smart-aquarium architecture

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

- Interactive diagram: https://gitdiagram.com/crazydw4rf/smart-aquarium
- Repository: https://github.com/crazydw4rf/smart-aquarium

## Overview

Smart Aquarium combines ESP32/ESP8266 sensing and relay control with three alternative remote interfaces: Telegram commands, an MQTT/WebSocket dashboard, and a ThingSpeak dashboard. The primary workflow is to sample temperature and water level, publish or expose readings, accept lamp/pump commands, and drive relays. The graph separates the firmware modes and web backends; excerpts are partial, so uncertain internal wiring is omitted.

Main entry points: [`src/main_telegram.cpp`](https://github.com/crazydw4rf/smart-aquarium/blob/main/src/main_telegram.cpp) (Telegram firmware), [`web/mqtt/server.js`](https://github.com/crazydw4rf/smart-aquarium/blob/main/web/mqtt/server.js) (MQTT web server), [`src/main_mqtt.cpp`](https://github.com/crazydw4rf/smart-aquarium/blob/main/src/main_mqtt.cpp) (MQTT firmware), [`src/main_thingspeak.cpp`](https://github.com/crazydw4rf/smart-aquarium/blob/main/src/main_thingspeak.cpp) (ThingSpeak firmware)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_firmware["Aquarium firmware"]
  node_telegram_firmware["Telegram firmware<br/>[main_telegram.cpp]"]
  node_mqtt_firmware["MQTT firmware<br/>[main_mqtt.cpp]"]
  node_ts_firmware["ThingSpeak firmware"]
end

subgraph group_telegram["Telegram control"]
  node_command_router["Command router<br/>[CommandRouter.cpp]"]
  node_telek_client["Telegram client<br/>[Telek.cpp]"]
end

subgraph group_mqtt["MQTT dashboard"]
  node_mqtt_server["MQTT web server<br/>[server.js]"]
  node_mqtt_ui["MQTT dashboard UI<br/>[script.js]"]
end

subgraph group_thingspeak["ThingSpeak dashboard"]
  node_ts_server["ThingSpeak web server<br/>[server.js]"]
  node_ts_ui["ThingSpeak dashboard UI<br/>[script.js]"]
end

node_sensor(("Aquarium sensors"))
node_relay["Lamp and pump relays"]
node_telegram_user(("Telegram user"))
node_browser_mqtt(("Dashboard visitor"))
node_browser_ts(("Dashboard visitor"))
node_mqtt_broker{{"MQTT broker"}}
node_telegram_api{{"Telegram API"}}
node_thingspeak_cloud[("ThingSpeak cloud")]

node_sensor -->|"sample readings"| node_telegram_firmware
node_telegram_firmware -->|"drive relays"| node_relay
node_telegram_firmware -->|"dispatch commands"| node_command_router
node_command_router -->|"invoke handlers"| node_telegram_firmware
node_telegram_firmware -->|"send and poll"| node_telek_client
node_telegram_user -->|"send commands"| node_telegram_api
node_telek_client -->|"HTTPS requests"| node_telegram_api
node_telegram_api -->|"updates and replies"| node_telek_client
node_sensor -->|"sample readings"| node_mqtt_firmware
node_mqtt_firmware -->|"drive relays"| node_relay
node_mqtt_firmware -->|"publish and subscribe"| node_mqtt_broker
node_mqtt_server -->|"subscribe and publish"| node_mqtt_broker
node_mqtt_broker -->|"deliver messages"| node_mqtt_server
node_browser_mqtt -->|"view and control"| node_mqtt_ui
node_mqtt_ui -->|"WebSocket messages"| node_mqtt_server
node_mqtt_server -->|"sensor updates"| node_mqtt_ui
node_sensor -->|"sample readings"| node_ts_firmware
node_ts_firmware -->|"drive relays"| node_relay
node_ts_firmware -->|"publish and read fields"| node_thingspeak_cloud
node_ts_server -->|"fetch status and write control"| node_thingspeak_cloud
node_browser_ts -->|"view and control"| node_ts_ui
node_ts_ui -->|"HTTP requests"| node_ts_server
node_ts_server -->|"status responses"| node_ts_ui

click node_telegram_firmware "https://github.com/crazydw4rf/smart-aquarium/blob/main/src/main_telegram.cpp"
click node_mqtt_firmware "https://github.com/crazydw4rf/smart-aquarium/blob/main/src/main_mqtt.cpp"
click node_ts_firmware "https://github.com/crazydw4rf/smart-aquarium/blob/main/src/main_thingspeak.cpp"
click node_command_router "https://github.com/crazydw4rf/smart-aquarium/blob/main/lib/Telek/CommandRouter.cpp"
click node_telek_client "https://github.com/crazydw4rf/smart-aquarium/blob/main/lib/Telek/Telek.cpp"
click node_mqtt_server "https://github.com/crazydw4rf/smart-aquarium/blob/main/web/mqtt/server.js"
click node_mqtt_ui "https://github.com/crazydw4rf/smart-aquarium/blob/main/web/mqtt/public/script.js"
click node_ts_server "https://github.com/crazydw4rf/smart-aquarium/blob/main/web/thingspeak/server.js"
click node_ts_ui "https://github.com/crazydw4rf/smart-aquarium/blob/main/web/thingspeak/public/script.js"

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_telegram_firmware,node_mqtt_firmware,node_ts_firmware,node_telegram_user toneBlue
class node_command_router,node_telek_client,node_thingspeak_cloud toneAmber
class node_mqtt_server,node_mqtt_ui,node_telegram_api toneMint
class node_ts_server,node_ts_ui toneRose
class node_sensor,node_relay,node_browser_mqtt,node_browser_ts,node_mqtt_broker toneIndigo
```

## Components

### Aquarium firmware

- [Telegram firmware](https://github.com/crazydw4rf/smart-aquarium/blob/main/src/main_telegram.cpp): `src/main_telegram.cpp`
- [MQTT firmware](https://github.com/crazydw4rf/smart-aquarium/blob/main/src/main_mqtt.cpp): `src/main_mqtt.cpp`
- [ThingSpeak firmware](https://github.com/crazydw4rf/smart-aquarium/blob/main/src/main_thingspeak.cpp): `src/main_thingspeak.cpp`

### Telegram control

- [Command router](https://github.com/crazydw4rf/smart-aquarium/blob/main/lib/Telek/CommandRouter.cpp): `lib/Telek/CommandRouter.cpp`
- [Telegram client](https://github.com/crazydw4rf/smart-aquarium/blob/main/lib/Telek/Telek.cpp): `lib/Telek/Telek.cpp`

### MQTT dashboard

- [MQTT web server](https://github.com/crazydw4rf/smart-aquarium/blob/main/web/mqtt/server.js): `web/mqtt/server.js`
- [MQTT dashboard UI](https://github.com/crazydw4rf/smart-aquarium/blob/main/web/mqtt/public/script.js): `web/mqtt/public/script.js`

### ThingSpeak dashboard

- [ThingSpeak web server](https://github.com/crazydw4rf/smart-aquarium/blob/main/web/thingspeak/server.js): `web/thingspeak/server.js`
- [ThingSpeak dashboard UI](https://github.com/crazydw4rf/smart-aquarium/blob/main/web/thingspeak/public/script.js): `web/thingspeak/public/script.js`

### Other components

- **Aquarium sensors**
- **Lamp and pump relays**
- **Telegram user**
- **Dashboard visitor**
- **Dashboard visitor**
- **MQTT broker**
- **Telegram API**
- **ThingSpeak cloud**

## Connections

- Aquarium sensors → Telegram firmware: sample readings
- Telegram firmware → Lamp and pump relays: drive relays
- Telegram firmware → Command router: dispatch commands
- Command router → Telegram firmware: invoke handlers
- Telegram firmware → Telegram client: send and poll
- Telegram user → Telegram API: send commands
- Telegram client → Telegram API: HTTPS requests
- Telegram API → Telegram client: updates and replies
- Aquarium sensors → MQTT firmware: sample readings
- MQTT firmware → Lamp and pump relays: drive relays
- MQTT firmware → MQTT broker: publish and subscribe
- MQTT web server → MQTT broker: subscribe and publish
- MQTT broker → MQTT web server: deliver messages
- Dashboard visitor → MQTT dashboard UI: view and control
- MQTT dashboard UI → MQTT web server: WebSocket messages
- MQTT web server → MQTT dashboard UI: sensor updates
- Aquarium sensors → ThingSpeak firmware: sample readings
- ThingSpeak firmware → Lamp and pump relays: drive relays
- ThingSpeak firmware → ThingSpeak cloud: publish and read fields
- ThingSpeak web server → ThingSpeak cloud: fetch status and write control
- Dashboard visitor → ThingSpeak dashboard UI: view and control
- ThingSpeak dashboard UI → ThingSpeak web server: HTTP requests
- ThingSpeak web server → ThingSpeak dashboard UI: status responses