# 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