Decentralized Mesh Network Peer

Decentralized Mesh Network Peer: Resilient Architecture

The Krill Platform is designed as a resilient peer-to-peer network swarm of servers. Each server in the mesh network connects to other servers, known as Peers, to share data and resources. This decentralized architecture enhances reliability, scalability, and fault tolerance, ensuring that the network remains operational even if individual servers go offline.

Overview

Peers represent the connections between Krill servers on your local network. Unlike External Servers that require manual configuration, Peers are automatically discovered through beacon broadcasting. This creates a self-organizing mesh where servers find and connect to each other without user intervention.

Key Features

• Auto-Discovery: Servers automatically discover peers on local network
• Beacon Broadcasting: UDP beacon system for server announcement
• Decentralized Architecture: No single point of failure
• Data Synchronization: Share node states across the mesh
• Workload Distribution: Distribute processing across servers
• Fault Tolerance: Network continues if servers go offline
• Self-Healing: Automatic reconnection when servers return
• Real-Time Updates: WebSocket-based state synchronization

Mesh Network Architecture

graph TD
    subgraph "Local Network Mesh"
        A[Krill Server A] <-->|Peer Connection| B[Krill Server B]
        B <-->|Peer Connection| C[Krill Server C]
        A <-->|Peer Connection| C
        A <-->|Peer Connection| D[Krill Server D]
        C <-->|Peer Connection| D
    end
    
    E[Client App] -->|Connect| A
    E -->|Connect| B
    E -->|Connect| C
    E -->|Connect| D
    
    F[Beacon UDP] -.->|Discovery| A
    F -.->|Discovery| B
    F -.->|Discovery| C
    F -.->|Discovery| D

How Peer Discovery Works

The peer discovery process is fully automated:

1. Beacon Broadcast: Each server broadcasts UDP beacons on the local network
2. Beacon Reception: Other servers receive and process beacon messages
3. Handshake Initiation: Servers initiate WebSocket connections
4. Trust Establishment: Servers authenticate using API keys
5. Session Creation: PeerSessionManager tracks active sessions
6. State Synchronization: Nodes and states are synchronized across peers
7. Heartbeat Monitoring: Regular heartbeats maintain connection health
8. Auto-Reconnect: Lost connections are automatically re-established

Peer Communication Flow

sequenceDiagram
    participant A as Server A
    participant B as Server B
    
    A->>B: UDP Beacon (announce presence)
    B->>A: UDP Beacon (acknowledge)
    A->>B: WebSocket Connect
    B->>A: Authentication Challenge
    A->>B: API Key Auth
    B->>A: Session Established
    A->>B: Node State Sync
    B->>A: Node State Sync
    
    loop Heartbeat
        A->>B: Ping
        B->>A: Pong
    end

Peer Metadata

Each peer connection maintains metadata about the remote server:

Field	Description
name	Server hostname
port	Server communication port
model	Hardware model (Raspberry Pi, etc.)
version	Krill Server version
os	Operating system
platform	Platform type (LINUX, WINDOWS, MAC)
serverSettingsData	Server configuration data

Use Cases

• Home Automation: Multiple Raspberry Pi servers throughout the house
• Lab Monitoring: Distributed sensors across a facility
• Redundancy: Multiple servers for critical automation
• Scalability: Add servers as your needs grow
• Load Distribution: Spread data collection across devices
• Geographic Distribution: Servers in different rooms/areas
• Edge Computing: Process data close to sensors

Benefits of Mesh Architecture

Reliability:

• No single point of failure
• Network continues if servers go offline
• Automatic reconnection when servers return

Scalability:

• Add servers without reconfiguration
• Linear scaling with additional nodes
• No central bottleneck

Performance:

• Local processing reduces latency
• Distributed workload
• Efficient resource utilization

Simplicity:

• Zero configuration for basic mesh
• Auto-discovery eliminates manual setup
• Self-organizing network

Fault Tolerance

When a server goes offline:

graph TD
    A[Server Offline Detected] --> B[Mark Peer as Disconnected]
    B --> C[Remove from Active Sessions]
    C --> D[Continue with Remaining Peers]
    D --> E{Server Returns?}
    E -->|Yes| F[Beacon Detected]
    F --> G[Re-establish Connection]
    G --> H[Sync State Changes]
    E -->|No| I[Wait for Beacon]
    I --> E

Cross-Server Data Flow

Peers enable powerful cross-server automation:

Example: Distributed Temperature Monitoring

Server A (Living Room)
  └─> Temperature Data Point
      └─> Updates synced to peers

Server B (Bedroom)  
  └─> Receives temp update from Server A
      └─> Trigger: High Threshold
          └─> Executor: Control local AC

Server C (Central)
  └─> Compute: Average all room temperatures
      └─> OutgoingWebHook: Dashboard update

Integration with TargetingNodeMetaData

Executors with TargetingNodeMetaData can target Data Points on any peer:

• Calculation: Read from Server A, write to Server B
• Compute: Aggregate data from multiple servers
• Logic Gates: Inputs from different servers

Session Management

The PeerSessionManager handles all peer connections:

• Session Tracking: Maintains list of active sessions
• TTL Cleanup: Removes expired/inactive sessions
• Connection Health: Monitors heartbeats and connection state
• Reconnection: Handles automatic reconnection logic

Best Practices

• Network Stability: Use reliable local network infrastructure
• Consistent Versions: Keep all servers on same Krill version
• API Key Security: Configure secure API keys for server authentication
• Resource Planning: Consider CPU/memory across distributed load
• Monitoring: Monitor peer connection health
• Backup Strategy: Plan for server maintenance windows

Comparison: Peer vs External Server

Feature	Peer	External Server
Discovery	Automatic (beacon)	Manual configuration
Network	Local network only	Any network/internet
Latency	Very low	Variable (network dependent)
Setup	Zero configuration	Requires address/API key
Trust	Beacon handshake	API key authentication

Troubleshooting

Issue	Cause	Solution
No peers discovered	Firewall blocking UDP	Open beacon port
Intermittent connections	Network congestion	Check network health
Sync delays	High latency	Verify network performance
Authentication failures	Mismatched API keys	Verify API key configuration

Network Requirements

• UDP Port: Open for beacon broadcasts (discovery)
• TCP Port: Open for WebSocket connections (data)
• Same Subnet: Servers should be on same network subnet for discovery
• Low Latency: Local network recommended for real-time sync

The Decentralized Mesh Network architecture is the foundation of Krill’s resilient, scalable automation platform, enabling multiple servers to work together as a unified system.