docs: add ESP32 and iOS agent architecture reference

- reference/esp32-agent/: DESIGN, HARDWARE, API_COMPAT, ARCHITECTURE, README - reference/ios-agent/: DESIGN, API_COMPAT, UI_DESIGN, ARCHITECTURE, README - Both mirror Android agent architecture, UI design, and heartbeat flow - Architecture-only (no code) — avoids submodule conflicts Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
2026-07-06 14:20:10 +07:00
parent 4af46dadad
commit 84689b208e
10 changed files with 3565 additions and 0 deletions
@@ -0,0 +1,103 @@
+# ESP32 Agent — Architecture Reference
+
+**Status**: ARCHITECTURE ONLY (no code)
+**Location**: `reference/esp32-agent/` (NOT a submodule)
+
+## Overview
+
+This directory contains the architecture design and documentation for the ESP32-based WireGuard agent. It is **NOT a git submodule** — it is an architecture reference for future implementation.
+
+## Why `reference/` not `apps/`?
+
+If ESP32 agent is implemented as a submodule in the future, it will be added to `apps/device-agent-embedded/`. This `reference/` directory stores the architecture docs separately to avoid conflicts.
+
+## Purpose
+
+- Document the ESP32 agent architecture
+- Define the API contract (shared with server-core)
+- Hardware reference for LW840X module
+- Track implementation status and TODOs
+
+## When to Implement
+
+When ready to build the ESP32 agent:
+
+1. Create a new repo: `nexus-agent-embedded`
+2. Add as submodule: `apps/device-agent-embedded/`
+3. Use ESP-IDF v5.2+ toolchain
+4. Follow the architecture in `docs/DESIGN.md`
+
+## Files
+
+| File | Description |
+|------|-------------|
+| `docs/DESIGN.md` | Technical design document (full architecture) |
+| `docs/HARDWARE.md` | ESP32/LW840X hardware reference |
+| `docs/API_COMPAT.md` | Server API contract (shared protocol) |
+| `docs/ARCHITECTURE.md` | Module architecture + implementation status |
+
+## Architecture Summary
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    ESP32 (FreeRTOS)                      │
+├─────────────────────────────────────────────────────────┤
+│  Application Layer                                      │
+│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐  │
+│  │ provision│ │ heartbeat│ │  tunnel  │ │  config  │  │
+│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘  │
+│       │             │            │             │         │
+│  ┌────┴─────────────┴────────────┴─────────────┴────┐  │
+│  │                   crypto.c                       │  │
+│  │           AES-256-GCM decrypt (mbedtls)          │  │
+│  └──────────────────────────────────────────────────┘  │
+├─────────────────────────────────────────────────────────┤
+│  Network Stack (lwIP)                                  │
+│  ┌──────────────────────────────────────────────────┐  │
+│  │              WireGuard (lwIP socket API)         │  │
+│  └──────────────────────────────────────────────────┘  │
+├─────────────────────────────────────────────────────────┤
+│  Hardware Layer                                         │
+│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐  │
+│  │   WiFi   │ │   NVS    │ │   UART   │ │   GPIO   │  │
+│  └──────────┘ └──────────┘ └──────────┘ └──────────┘  │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Implementation Status
+
+| Module | Status | Notes |
+|--------|--------|-------|
+| `tunnel.c` | ❌ STUB | Needs `wireguard-esp32` component integration |
+| `heartbeat.c` | ✅ Real | HTTP loop working, config sync TODO |
+| `provision.c` | ✅ Real | HTTP provisioning working |
+| `crypto.c` | ✅ Real | mbedtls AES-256-GCM |
+| `config.c` | ✅ Real | NVS storage |
+| `wifi.c` | ✅ Real | WiFi STA management |
+
+## Dependencies
+
+- **ESP-IDF**: v5.2+
+- **mbedtls**: AES-256-GCM, SHA-256 (built-in)
+- **lwIP**: TCP/IP stack (built-in)
+- **FreeRTOS**: RTOS (built-in)
+- **wireguard-esp32**: WireGuard tunnel library (NOT YET INTEGRATED)
+
+## API Contract (Shared with Server)
+
+```
+POST /api/v1/provision   → { token, hwid } → { encrypted_config }
+POST /api/v1/heartbeat   → { device_id, tunnel_up, last_handshake } → { config sync }
+```
+
+See `docs/API_COMPAT.md` for full specification.
+
+## Related
+
+- [Server Core API](../../server-core/docs/)
+- [Device Agent (Go)](../../apps/device-agent/)
+- [Android Agent](../../apps/android-agent/)
+
+## License
+
+Proprietary - NexusGuard