From 641157202e92523e5848203e5fe3d19f90438dee Mon Sep 17 00:00:00 2001
From: DjeAvd <djelal.avdil@master.hes-so.ch>
Date: Wed, 29 Apr 2026 12:47:49 +0100
Subject: [PATCH] docs(gateway): update UML diagrams following review feedback
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Fix class diagram: use aggregation (o--) for BleakScanner and MQTTClient
- Split sequence diagram into separate files for clarity
- Add sequence_startup.puml for gateway initialization
- Add sequence_data_collection.puml with error handling
- Use collections for BLE broadcaster to reflect multiplicity
- Remove loop construct — gateway reacts to packets, ignores intervals
- Add discard of unknown UUID packets
- Add handling of invalid sensor values
---
 doc_resources/gateway/class_diagram.puml      |  4 +--
 .../gateway/sequence_data_collection.puml     | 27 +++++++++++++++++
 doc_resources/gateway/sequence_diagram.puml   | 30 -------------------
 doc_resources/gateway/sequence_startup.puml   | 13 ++++++++
 4 files changed, 42 insertions(+), 32 deletions(-)
 create mode 100644 doc_resources/gateway/sequence_data_collection.puml
 delete mode 100644 doc_resources/gateway/sequence_diagram.puml
 create mode 100644 doc_resources/gateway/sequence_startup.puml

diff --git a/doc_resources/gateway/class_diagram.puml b/doc_resources/gateway/class_diagram.puml
index 3501363..484dd9e 100644
--- a/doc_resources/gateway/class_diagram.puml
+++ b/doc_resources/gateway/class_diagram.puml
@@ -31,7 +31,7 @@ class MQTTClient {
     + username_pw_set()
 }
 
-Gateway --> BleakScanner : uses
-Gateway --> MQTTClient : uses
+Gateway o-- BleakScanner
+Gateway o-- MQTTClient
 
 @enduml
diff --git a/doc_resources/gateway/sequence_data_collection.puml b/doc_resources/gateway/sequence_data_collection.puml
new file mode 100644
index 0000000..da9ba9d
--- /dev/null
+++ b/doc_resources/gateway/sequence_data_collection.puml
@@ -0,0 +1,27 @@
+@startuml
+skinparam sequenceMessageAlign center
+
+collections "BLE broadcaster" as thingy
+participant "Gateway\n(Raspberry Pi)" as gw
+participant "MQTT Broker\n(RabbitMQ)" as broker
+participant "Database\n(InfluxDB)" as db
+
+== Data collection ==
+thingy -> gw : BLE advertising packet
+
+alt UUID does not match ef680100
+    gw -> gw : discard packet
+else UUID matches
+    gw -> gw : extract raw payload
+    gw -> gw : decode_payload()
+    
+    alt unknown key or value out of range
+        gw -> gw : discard invalid value\nlog warning
+    else valid payload
+        gw -> gw : add UTC timestamp
+        gw -> broker : publish JSON\n{gateway_id}/{mac}/update
+        broker -> db : store measurement
+    end
+end
+
+@enduml
diff --git a/doc_resources/gateway/sequence_diagram.puml b/doc_resources/gateway/sequence_diagram.puml
deleted file mode 100644
index bac4ec4..0000000
--- a/doc_resources/gateway/sequence_diagram.puml
+++ /dev/null
@@ -1,30 +0,0 @@
-@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
diff --git a/doc_resources/gateway/sequence_startup.puml b/doc_resources/gateway/sequence_startup.puml
new file mode 100644
index 0000000..036ecc3
--- /dev/null
+++ b/doc_resources/gateway/sequence_startup.puml
@@ -0,0 +1,13 @@
+@startuml
+skinparam sequenceMessageAlign center
+
+participant "Gateway\n(Raspberry Pi)" as gw
+participant "MQTT Broker\n(RabbitMQ)" as broker
+
+== Startup ==
+gw -> gw : load config.json
+gw -> broker : connect (MQTTS, TLS, auth)
+broker --> gw : connected
+gw -> gw : start BLE scan
+
+@enduml