docs: add architecture documentation for config caching optimization (#3026)

Author: nikw9944

CHANGELOG.md

@@ -8,6 +8,9 @@ All notable changes to this project will be documented in this file.
 
 ### Changes
 
+- Device agents
+  - Reduce agent CPU usage by continuing to fetch the full config every 5 seconds but only applying when it has changed or after 60s timeout
+
 ## [v0.14.0](https://github.com/malbeclabs/doublezero/compare/client/v0.13.0...client/v0.14.0) - 2026-03-24
 
 ### Breaking

controlplane/controller/README.md

@@ -2,6 +2,61 @@
 
 The controller generates device configurations from Solana smart contract state and serves them to agents running on network devices via gRPC.
 
+## Architecture
+
+### Agent-Controller Communication Flow
+
+The controller provides a gRPC endpoint (GetConfig) that returns both the configuration and its hash. The agent polls the controller every 5 seconds, but only applies the configuration to the EOS device when it has changed (based on hash comparison) or after a 60-second timeout.
+
+The design includes an optimization to reduce EOS device CPU usage:
+- Applying configuration to an Arista EOS device causes the EOS ConfigAgent process CPU to spike
+- The agent computes a SHA256 hash of the received config and only applies it when:
+  1. The hash differs from the last applied configuration, OR
+  2. 60 seconds have elapsed since the last application (as a safety measure)
+
+Here's how the agent uses the endpoint:
+
+```
+┌─────────┐                  ┌────────────┐                 ┌────────────┐                  ┌─────────┐
+│  Agent  │                  │ Controller │                 │ Controller │                  │   EOS   │
+│  main() │                  │ GetConfig()│                 │  Config    │                  │ Device  │
+│         │                  │   (gRPC)   │                 │  Generator │                  │         │
+└────┬────┘                  └─────┬──────┘                 └─────┬──────┘                  └────┬────┘
+     │                             │                              │                              │
+     │ Every 5s:                   │                              │                              │
+     │                             │                              │                              │
+     │ GetBgpNeighbors()           │                              │                              │
+     ├──────────────────────────────────────────────────────────────────────────────────────────►│
+     │◄──────────────────────────────────────────────────────────────────────────────────────────┤
+     │ [peer IPs]                  │                              │                              │
+     │                             │                              │                              │
+     │ GetConfigFromServer()       │                              │                              │
+     ├────────────────────────────►│                              │                              │
+     │                             │ processConfigRequest()       │                              │
+     │                             ├─────────────────────────────►│                              │
+     │                             │                              │ generateConfig()             │
+     │                             │                              │  • deduplicateTunnels()      │
+     │                             │                              │  • renderConfig()            │
+     │                             │                              │    (~50KB config text)       │
+     │                             │                              │  • compute SHA256 hash       │
+     │                             │◄─────────────────────────────┤                              │
+     │                             │ [config string + hash]       │                              │
+     │◄────────────────────────────┤                              │                              │
+     │ ConfigResponse              │                              │                              │
+     │ {config: "...", hash: "..."}│                              │                              │
+     │                             │                              │                              │
+     │ Compare hash with cached    │                              │                              │
+     │ If changed OR 60s elapsed:  │                              │                              │
+     │   AddConfigToDevice(config) │                              │                              │
+     ├──────────────────────────────────────────────────────────────────────────────────────────►│
+```
+
+**Key Benefits:**
+- **CPU**: EOS device only processes config when it actually changes (or every 60s as safety)
+- **Responsiveness**: Still checks for changes every 5 seconds
+- **Simplicity**: Single endpoint, agent handles caching logic
+- **Safety**: Full config application every 60s ensures eventual consistency
+
 ## Configuration
 
 ### ClickHouse Integration