From d96968f1237724678055c3cbb9b88c649269358b Mon Sep 17 00:00:00 2001
From: DjeAvd <djelal.avdil@master.hes-so.ch>
Date: Tue, 28 Apr 2026 20:56:00 +0100
Subject: [PATCH] docs(gateway): add PlantUML class and sequence diagrams
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Class diagram shows Gateway structure with attributes, constants

and methods, and its dependencies on BleakScanner and MQTTClient.

Sequence diagram shows the full data flow from BLE advertising

to MQTT publication, including startup, data collection and

node failure scenarios.

Assisted-by: Claude:claude-sonnet-4-6 — PlantUML syntax
---
 doc_resources/gateway/class_diagram.puml    | 37 +++++++++++++++++++++
 doc_resources/gateway/sequence_diagram.puml | 30 +++++++++++++++++
 2 files changed, 67 insertions(+)
 create mode 100644 doc_resources/gateway/class_diagram.puml
 create mode 100644 doc_resources/gateway/sequence_diagram.puml

diff --git a/doc_resources/gateway/class_diagram.puml b/doc_resources/gateway/class_diagram.puml
new file mode 100644
index 0000000..3501363
--- /dev/null
+++ b/doc_resources/gateway/class_diagram.puml
@@ -0,0 +1,37 @@
+@startuml
+skinparam linestyle ortho
+
+class Gateway {
+    - gateway_id: str
+    - mqtt_broker: str
+    - mqtt_port: int
+    - service_uuid: str
+    - mqttc: MQTTClient
+    --
+    + KEY_WINDOW: 0x01
+    + KEY_HUMIDITY: 0x02
+    + KEY_TEMP: 0x03
+    + KEY_CO2: 0x04
+    --
+    + decode_payload(data: bytes): dict
+    + publish(mac: str, data: dict)
+    + on_device_found(device, adv_data)
+    + run()
+}
+
+class BleakScanner {
+    + start()
+    + stop()
+}
+
+class MQTTClient {
+    + connect()
+    + publish()
+    + tls_set()
+    + username_pw_set()
+}
+
+Gateway --> BleakScanner : uses
+Gateway --> MQTTClient : uses
+
+@enduml
diff --git a/doc_resources/gateway/sequence_diagram.puml b/doc_resources/gateway/sequence_diagram.puml
new file mode 100644
index 0000000..bac4ec4
--- /dev/null
+++ b/doc_resources/gateway/sequence_diagram.puml
@@ -0,0 +1,30 @@
+@startuml
+skinparam sequenceMessageAlign center
+
+participant "Thingy:52" as thingy
+participant "Gateway\n(Raspberry Pi)" as gw
+participant "MQTT Broker\n(RabbitMQ)" as broker
+participant "Database\n(InfluxDB)" as db
+
+== Startup ==
+gw -> gw : load config.json
+gw -> broker : connect (MQTTS, TLS, auth)
+broker --> gw : connected
+gw -> gw : start BLE scan
+
+== Data collection ==
+loop every 2 min to 6 hours
+    thingy -> thingy : read sensors
+    thingy -> gw : BLE advertising packet\n(key/value payload)
+    gw -> gw : filter on UUID ef680100
+    gw -> gw : decode_payload()\n0x02 humidity\n0x03 temperature\n0x04 CO2
+    gw -> gw : add UTC timestamp
+    gw -> broker : publish JSON\n{gateway_id}/{mac}/update
+    broker -> db : store measurement
+end
+
+== Node failure ==
+thingy ->x gw : no advertising for > 6h
+gw -> broker : node considered dead\n(missing from next publish)
+
+@enduml