This document outlines how an edge device registers itself against the control plane, maintains its persistent socket layer, and parses commands.
sequenceDiagram
participant Device as Edge Device
participant Agent as Device Agent
participant Controller as Go Controller (K8s)
participant Auth as Registration Service
participant DeviceService as API Data Store (Lambda/DB)
participant DB as Database
%% Initial Setup and Registration
Note over Device,Agent: Device Registration Phase
Device->>Agent: Install agent
Agent->>Agent: Generate device identifier
Agent->>Controller: Initial connection with registration token
Controller->>Auth: Validate registration token
Auth->>DB: Check token validity
DB-->>Auth: Token valid
Auth-->>Controller: Token validation success
Controller->>DeviceService: Register device
DeviceService->>DB: Store device information
DB-->>DeviceService: Device registered
DeviceService-->>Controller: Registration confirmed
Controller-->>Agent: Registration successful + Device credentials
Agent->>Agent: Store device credentials securely
%% Regular Connection Lifecycle
Note over Agent,Controller: Connection Maintenance Phase
Agent->>Controller: Establish WebSocket connection
Controller->>Auth: Authenticate device credentials
Auth-->>Controller: Authentication successful
Controller->>DeviceService: Update device status (online)
DeviceService->>DB: Record connection time & status
Controller-->>Agent: Connection established
%% Heartbeat and Status Updates
loop Every 30 seconds
Agent->>Controller: Heartbeat signal
Controller->>Controller: Retain state in Redis/Memory
end
%% System Information Updates
loop Every 5 minutes
Agent->>Agent: Collect system metrics
Agent->>Controller: Send system information
Controller->>DeviceService: Batch update device metrics
DeviceService->>DB: Store metrics history
end
%% Command Channel
Note over Agent,Controller: Command Processing Phase
Controller->>Agent: Send command (e.g., deploy application)
Agent->>Agent: Process command
Agent->>Controller: Acknowledge command receipt
Agent->>Agent: Execute command
Agent->>Controller: Report command results
Controller->>DeviceService: Update command status
DeviceService->>DB: Record command execution
%% Connection Issues
Note over Agent,Controller: Connection Recovery Phase
rect rgb(255, 245, 245)
Agent--xController: Connection lost
Agent->>Agent: Enter reconnection state
loop Exponential backoff
Agent->>Controller: Attempt reconnection
end
Agent->>Controller: Reconnection successful
Controller->>DeviceService: Update device status
DeviceService->>DB: Record reconnection
Controller-->>Agent: Connection re-established
end
%% Graceful Disconnection
Note over Agent,Controller: Disconnection Phase
Agent->>Controller: Signal controlled shutdown
Controller->>DeviceService: Update device status (offline)
DeviceService->>DB: Record graceful disconnect
Controller-->>Agent: Acknowledge shutdown
Agent->>Agent: Terminate processes