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,58 @@
+# iOS Agent — Architecture Reference
+
+**Status**: ARCHITECTURE ONLY (no code)
+**Location**: `reference/ios-agent/` (NOT a submodule)
+**Mirror**: Android Agent (`apps/android-agent/`)
+
+## Overview
+
+This directory contains the architecture design for an iOS WireGuard agent that mirrors the Android agent's architecture, UI design, colors, and heartbeat flow.
+
+## Why `reference/` not `apps/`?
+
+If iOS agent is implemented in the future, it will be added as `apps/ios-agent/`. This `reference/` directory stores the architecture docs separately to avoid conflicts.
+
+## Purpose
+
+- Document the iOS agent architecture (mirrors Android)
+- Define UI design specs (colors, layout, components)
+- API contract (shared with server-core)
+- Track implementation status and TODOs
+
+## Architecture Mirror: Android → iOS
+
+| Android Component | iOS Equivalent | Notes |
+|-------------------|----------------|-------|
+| `AgentService.kt` | `PacketTunnelProvider` | Foreground service → NetworkExtension |
+| `TunnelManager.kt` | `WireGuardAdapter` | VPNService → NEPacketTunnelProvider |
+| `Heartbeat.kt` | `HeartbeatService` | HTTP loop (same) |
+| `Provisioning.kt` | `ProvisioningService` | HTTP provisioning (same) |
+| `ConfigStorage.kt` | `KeychainStorage` | SharedPreferences → Keychain |
+| `Encryptor.kt` | `CryptoManager` | JCE → CryptoKit |
+| `MainActivity.kt` | `ContentView` | Activity → SwiftUI |
+| `SettingsActivity.kt` | `SettingsView` | Activity → SwiftUI |
+| `BootReceiver.kt` | `BGAppRefreshTask` | Boot broadcast → Background Tasks |
+| `LogBuffer.kt` | `LogStore` | In-memory → CoreData |
+
+## Files
+
+| File | Description |
+|------|-------------|
+| `docs/DESIGN.md` | Technical design + UI specs |
+| `docs/ARCHITECTURE.md` | Module architecture |
+| `docs/API_COMPAT.md` | Server API contract |
+| `docs/UI_DESIGN.md` | UI design specs (colors, layout) |
+
+## Quick Start
+
+When implementing:
+
+1. Create Xcode project: `ios-agent`
+2. Add NetworkExtension capability
+3. Use `wireguard-apple` library for WireGuard
+4. Follow architecture in `docs/ARCHITECTURE.md`
+5. Match UI design in `docs/UI_DESIGN.md`
+
+## License
+
+Proprietary - NexusGuard