# 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