From 0d09c5900c10bbc39fe99a646311e415ecce6eb9 Mon Sep 17 00:00:00 2001
From: 0x1d <admin@dcentral.systems>
Date: Sun, 19 Oct 2025 14:04:37 +0200
Subject: [PATCH] docs: update

---
 docs/Architecture.md | 59 ++++++++++++++++++++++++++++++--------------
 1 file changed, 41 insertions(+), 18 deletions(-)

diff --git a/docs/Architecture.md b/docs/Architecture.md
index 427176e..57f61d8 100644
--- a/docs/Architecture.md
+++ b/docs/Architecture.md
@@ -42,16 +42,14 @@ The cluster uses a UDP-based discovery protocol for automatic node detection:
 
 ### Discovery Process
 
-1. **Discovery Broadcast**: Nodes periodically send UDP packets on port `udp_port` (default 4210)
-2. **Response Handling**: Nodes respond with `CLUSTER_RESPONSE:<hostname>`
-3. **Member Management**: Discovered nodes are added/updated in the cluster
-4. **Node Info via UDP**: Heartbeat triggers peers to send `CLUSTER_NODE_INFO:<hostname>:<json>`
+1. **Discovery Broadcast**: Nodes periodically send heartbeat messages on port `udp_port` (default 4210)
+2. **Response Handling**: Nodes respond with node update information containing their current state
+3. **Member Management**: Discovered nodes are added/updated in the cluster with current information
+4. **Node Synchronization**: Periodic broadcasts ensure all nodes maintain current cluster state
 
 ### Protocol Details
 
 - **UDP Port**: 4210 (configurable via `Config.udp_port`)
-- **Discovery Message**: `CLUSTER_DISCOVERY`
-- **Response Message**: `CLUSTER_RESPONSE`
 - **Heartbeat Message**: `CLUSTER_HEARTBEAT:hostname`
 - **Node Update Message**: `NODE_UPDATE:hostname:{json}`
 - **Broadcast Address**: 255.255.255.255
@@ -64,30 +62,55 @@ The cluster uses a UDP-based discovery protocol for automatic node detection:
   - Sender: each node, broadcast to 255.255.255.255:`udp_port` on interval
   - Purpose: announce presence, prompt peers for node info, and keep liveness
 - **Node Update**: `NODE_UPDATE:hostname:{json}`
-  - Sender: node receiving a heartbeat; unicast to heartbeat sender IP
+  - Sender: node responding to heartbeat or broadcasting current state
   - JSON fields: hostname, ip, uptime, optional labels
-  - Purpose: provide minimal node information in response to heartbeat
+  - Purpose: provide current node information for cluster synchronization
 
-### Heartbeat Flow
+### Discovery Flow
 
-1. **A node broadcasts** `CLUSTER_HEARTBEAT:hostname`
-2. **Each receiver responds** with `NODE_UPDATE:hostname:{json}` to the heartbeat sender IP
+1. **A node broadcasts** `CLUSTER_HEARTBEAT:hostname` to announce its presence
+2. **Each receiver responds** with `NODE_UPDATE:hostname:{json}` containing current node state
 3. **The sender**:
-   - Ensures the node exists or creates it with `hostname` and sender IP
+   - Ensures the responding node exists or creates it with current IP and information
    - Parses JSON and updates node info, `status = ACTIVE`, `lastSeen = now`
-   - Sets `latency = now - lastHeartbeatSentAt` (per-node, measured at heartbeat origin)
+   - Calculates `latency = now - lastHeartbeatSentAt` for network performance monitoring
 
-### Node Update Broadcasting
+### Node Synchronization
 
-1. **Periodic broadcast**: Each node broadcasts `NODE_UPDATE:hostname:{json}` every 5 seconds
+1. **Event-driven broadcasts**: Nodes broadcast `NODE_UPDATE:hostname:{json}` when node information changes
 2. **All receivers**: Update their memberlist entry for the broadcasting node
-3. **Purpose**: Ensures all nodes have current information about each other
+3. **Purpose**: Ensures all nodes maintain current cluster state and configuration
+
+### Sequence Diagram
+
+```mermaid
+sequenceDiagram
+    participant N1 as Node A (esp-node1)
+    participant N2 as Node B (esp-node2)
+
+    Note over N1,N2: Discovery via heartbeat broadcast
+    N1->>+N2: CLUSTER_HEARTBEAT:esp-node1
+
+    Note over N2: Node B responds with its current state
+    N2->>+N1: NODE_UPDATE:esp-node1:{"hostname":"esp-node2","uptime":12345,"labels":{"role":"sensor"}}
+
+    Note over N1: Process NODE_UPDATE response
+    N1-->>N1: Update memberlist for Node B
+    N1-->>N1: Set Node B status = ACTIVE
+    N1-->>N1: Calculate latency for Node B
+
+    Note over N1,N2: Event-driven node synchronization
+    N1->>+N2: NODE_UPDATE:esp-node1:{"hostname":"esp-node1","uptime":12346,"labels":{"role":"controller"}}
+
+    Note over N2: Update memberlist with latest information
+    N2-->>N2: Update Node A info, maintain ACTIVE status
+```
 
 ### Listener Behavior
 
 The `cluster_listen` task parses one UDP packet per run and dispatches by prefix to:
-- **Heartbeat** → add/update node and send `NODE_UPDATE` JSON response
-- **Node Update** → update node information and status
+- **Heartbeat** → add/update responding node and send `NODE_UPDATE` response
+- **Node Update** → update node information and trigger memberlist logging
 
 ### Timing and Intervals