# amatikhasan/iotbridgesystem architecture

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

- Interactive diagram: https://gitdiagram.com/amatikhasan/iotbridgesystem
- Repository: https://github.com/amatikhasan/iotbridgesystem

## Overview

1. **Overall shape**
   - This repo is a small IoT control-and-monitoring system built around three runtime pieces: a local **MQTT broker** (Mosquitto), a Python **bridge** service, and a Python **device simulator**.
   - The architecture is a hub-and-spoke setup: MQTT is the internal message bus, and Telegram is the human interface.

2. **`bridge.py` is the integration layer**
   - The bridge is the central orchestrator.
   - It connects outward to the **Telegram Bot API** and inward to the **MQTT broker**.
   - Its job is to translate Telegram commands into MQTT control messages, and translate MQTT sensor/status messages into Telegram alerts and updates.

3. **`simulator.py` is the device-side producer/consumer**
   - The simulator represents smart-home devices and sensors.
   - It publishes synthetic sensor telemetry into MQTT and listens for control commands from the bridge.
   - This lets the system demonstrate both telemetry ingestion and remote actuation without real hardware.

4. **MQTT is the internal boundary**
   - MQTT is the main decoupling point between the bridge and devices.
   - The bridge does not directly talk to the simulator; both communicate through the broker.
   - This makes the system extensible to additional devices or sensors without changing the Telegram-facing logic.

5. **Alerting is event-driven with thresholds**
   - The bridge watches incoming sensor topics and emits Telegram alerts when readings cross configured conditions:
     - temperature > 30°C
     - humidity > 70%
     - CO2 > 1000 ppm
     - motion detection
   - This is a one-way notification path from MQTT events to Telegram messages.

6. **Command/control path is bidirectional**
   - Telegram buttons drive control actions such as **Lights ON/OFF** and **Status Check**.
   - Those actions are converted into MQTT commands so the simulator/device side can react.
   - Status updates then flow back the other way through MQTT into Telegram, closing the loop.

7. **Debouncing prevents alert spam**
   - The bridge includes time-based suppression logic so the same topic won’t trigger repeated Telegram alerts too frequently.
   - This is important architecture-wise because it protects the human notification channel from noisy sensor streams.

8. **Mosquitto is run as a local infrastructure service**
   - `docker-compose.yml` provisions an **Eclipse Mosquitto** broker.
   - The `mosquitto/` directory holds broker configuration, data, and logs, which makes the MQTT layer a managed local dependency rather than an external cloud service.
   - The README indicates anonymous access on port `1883`, so the broker is intended for local development/demo use.

9. **Configuration and secrets are environment-driven**
   - Telegram credentials are provided via `.env` variables: bot token and chat ID.
   - That keeps the Telegram integration separate from code and allows the bridge to be deployed or tested in different accounts without code changes.

10. **Runtime boundaries**
   - **Python application boundary:** `bridge.py` and `simulator.py`
   - **Messaging boundary:** MQTT broker
   - **External SaaS boundary:** Telegram
   - **Infrastructure boundary:** Docker Compose-managed Mosquitto
   - These are the main boxes and arrows to capture in an architecture diagram.

11. **Operational flow**
   - Start Mosquitto with Docker Compose.
   - Run the bridge so it can subscribe/publish on MQTT and maintain the Telegram bot session.
   - Run the simulator to generate telemetry and respond to control messages.
   - The resulting system behaves like a small closed-loop IoT demo with human-in-the-loop control.

12. **What is not present**
   - There is no evidence of a database-backed application layer, web frontend, or cloud-hosted backend.
   - Persistence is limited to broker state/logs inside the Mosquitto directory, while the core application state appears to live in memory inside the Python processes.

Main entry points: [`docker-compose.yml`](https://github.com/amatikhasan/iotbridgesystem/blob/main/docker-compose.yml) (MQTT Broker), [`bridge.py`](https://github.com/amatikhasan/iotbridgesystem/blob/main/bridge.py) (Bridge), [`simulator.py`](https://github.com/amatikhasan/iotbridgesystem/blob/main/simulator.py) (Simulator), [`mosquitto/config/mosquitto.conf`](https://github.com/amatikhasan/iotbridgesystem/blob/main/mosquitto/config/mosquitto.conf) (Broker Config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_bridge["Bridge<br/>python orchestrator<br/>[bridge.py]"]
  node_simulator["Simulator<br/>python device sim<br/>[simulator.py]"]
end

subgraph group_messaging["Messaging"]
  node_broker[("MQTT Broker<br/>mosquitto broker<br/>[docker-compose.yml]")]
  node_telemetry(("Telemetry<br/>mqtt sensor flow"))
  node_commands(("Commands<br/>mqtt control flow"))
end

subgraph group_external["External"]
  node_alerts(("Alerts<br/>telegram notification flow"))
  node_telegram(("Telegram Bot<br/>saas interface"))
end

subgraph group_infra["Infrastructure"]
  node_compose["Compose Stack<br/>docker infra<br/>[docker-compose.yml]"]
  node_mosqconf["Broker Config<br/>mosquitto config<br/>[mosquitto.conf]"]
  node_mosqstate[("Broker State<br/>mosquitto data<br/>[mosquitto.db]")]
  node_mosqlog["Broker Logs<br/>mosquitto logs<br/>[mosquitto.log]"]
end

node_telegram -->|"commands"| node_bridge
node_bridge -->|"alerts"| node_telegram
node_bridge -->|"publish/subscribe"| node_broker
node_simulator -->|"telemetry"| node_broker
node_broker -->|"control"| node_simulator
node_broker -->|"events"| node_bridge
node_bridge -->|"emit"| node_commands
node_telemetry -->|"input"| node_bridge
node_bridge -->|"raise"| node_alerts
node_compose -->|"run"| node_broker
node_mosqconf -->|"configure"| node_broker
node_broker -->|"persist"| node_mosqstate
node_broker -->|"log"| node_mosqlog

click node_bridge "https://github.com/amatikhasan/iotbridgesystem/blob/main/bridge.py"
click node_simulator "https://github.com/amatikhasan/iotbridgesystem/blob/main/simulator.py"
click node_broker "https://github.com/amatikhasan/iotbridgesystem/blob/main/docker-compose.yml"
click node_compose "https://github.com/amatikhasan/iotbridgesystem/blob/main/docker-compose.yml"
click node_mosqconf "https://github.com/amatikhasan/iotbridgesystem/blob/main/mosquitto/config/mosquitto.conf"
click node_mosqstate "https://github.com/amatikhasan/iotbridgesystem/blob/main/mosquitto/data/mosquitto.db"
click node_mosqlog "https://github.com/amatikhasan/iotbridgesystem/blob/main/mosquitto/log/mosquitto.log"

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_bridge,node_simulator toneBlue
class node_broker,node_telemetry,node_commands toneAmber
class node_alerts,node_telegram toneMint
class node_compose,node_mosqconf,node_mosqstate,node_mosqlog toneRose
```

## Components

### Application

Python runtime components that implement the IoT demo logic

- [Bridge](https://github.com/amatikhasan/iotbridgesystem/blob/main/bridge.py): python orchestrator · Translates Telegram commands into MQTT control messages and MQTT events into Telegram alerts · `bridge.py`
- [Simulator](https://github.com/amatikhasan/iotbridgesystem/blob/main/simulator.py): python device sim · Produces synthetic telemetry and reacts to MQTT control commands · `simulator.py`

### Messaging

Internal broker boundary and topic exchange

- [MQTT Broker](https://github.com/amatikhasan/iotbridgesystem/blob/main/docker-compose.yml): mosquitto broker · Local message bus that decouples the bridge from devices · `docker-compose.yml`
- **Telemetry**: mqtt sensor flow · Sensor readings and device status published by the simulator
- **Commands**: mqtt control flow · Control messages and status checks sent from the bridge to devices

### External

Human-facing SaaS integration

- **Alerts**: telegram notification flow · Threshold-based notifications raised by the bridge from incoming MQTT events
- **Telegram Bot**: saas interface · Human control and notification channel for the system

### Infrastructure

Local broker deployment and persisted broker artifacts

- [Compose Stack](https://github.com/amatikhasan/iotbridgesystem/blob/main/docker-compose.yml): docker infra · Runs the local Mosquitto broker as a managed development service · `docker-compose.yml`
- [Broker Config](https://github.com/amatikhasan/iotbridgesystem/blob/main/mosquitto/config/mosquitto.conf): mosquitto config · Mosquitto runtime configuration used by the local broker · `mosquitto/config/mosquitto.conf`
- [Broker State](https://github.com/amatikhasan/iotbridgesystem/blob/main/mosquitto/data/mosquitto.db): mosquitto data · Persisted broker database/state used by the local Mosquitto service · `mosquitto/data/mosquitto.db`
- [Broker Logs](https://github.com/amatikhasan/iotbridgesystem/blob/main/mosquitto/log/mosquitto.log): mosquitto logs · Operational log output from the local broker · `mosquitto/log/mosquitto.log`

## Connections

- Telegram Bot → Bridge: commands · User actions and bot interactions reach the bridge
- Bridge → Telegram Bot: alerts · Threshold breaches and status updates are sent back to Telegram
- Bridge → MQTT Broker: publish/subscribe · Bridge exchanges MQTT messages through the broker
- Simulator → MQTT Broker: telemetry · Simulator publishes sensor data into MQTT
- MQTT Broker → Simulator: control · Simulator receives commands routed through MQTT
- MQTT Broker → Bridge: events · Bridge consumes sensor and status events from MQTT
- Bridge → Commands: emit · Control actions are translated into MQTT commands
- Telemetry → Bridge: input · Incoming sensor readings are evaluated for alerting
- Bridge → Alerts: raise · Alert conditions create Telegram notifications
- Compose Stack → MQTT Broker: run · Docker Compose provisions the Mosquitto broker service
- Broker Config → MQTT Broker: configure · Broker behavior is defined by Mosquitto configuration
- MQTT Broker → Broker State: persist · Broker state is stored locally for the development stack
- MQTT Broker → Broker Logs: log · Broker activity is written to local log files