# camm2325/microlink architecture

> Architecture diagram of the GitHub repository camm2325/microlink, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/camm2325/microlink
- Repository: https://github.com/camm2325/microlink

## Overview

MicroLink is an asynchronous Tailscale client for ESP32, with WiFi and cellular connectivity. An application initializes and starts the client; coordination registers it with the control plane and obtains peer information, while the WireGuard manager provisions peers and handles DISCO path discovery. Network I/O, DERP relaying, and WireGuard transport provide connectivity to tailnet peers. Separate capabilities include cellular failover, runtime HTTP configuration, cached peers, STUN discovery, and TCP/UDP APIs. The README documents task responsibilities; some implementation links are omitted where sampled source does not establish them.

Main entry points: [`components/microlink/src/microlink.c`](https://github.com/camm2325/microlink/blob/main/components/microlink/src/microlink.c) (Client runtime), [`components/microlink/src/ml_coord.c`](https://github.com/camm2325/microlink/blob/main/components/microlink/src/ml_coord.c) (Control coordination), [`components/microlink/include/microlink.h`](https://github.com/camm2325/microlink/blob/main/components/microlink/include/microlink.h) (Client API), [`components/microlink/src/ml_wg_mgr.c`](https://github.com/camm2325/microlink/blob/main/components/microlink/src/ml_wg_mgr.c) (Peer and DISCO manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client and Coordination"]
  node_public_api["Client API<br/>[microlink.h]"]
  node_client_runtime["Client runtime<br/>[microlink.c]"]
  node_coordination["Control coordination<br/>[ml_coord.c]"]
  node_h2["HTTP/2 transport<br/>[ml_h2.c]"]
  node_tcp_api["TCP socket API<br/>[ml_tcp.c]"]
  node_udp_api["UDP socket API<br/>[ml_udp.c]"]
end

subgraph group_connectivity["Network Connectivity"]
  node_derp_client["DERP relay client<br/>[ml_derp.c]"]
  node_stun["STUN discovery<br/>[ml_stun.c]"]
  node_network_io["Network I/O<br/>[ml_net_io.c]"]
  node_network_switch["Network failover<br/>[ml_net_switch.c]"]
  node_cellular["Cellular PPP<br/>[ml_cellular.c]"]
  node_at_socket["AT socket bridge<br/>[ml_at_socket.c]"]
end

subgraph group_tunnel["WireGuard Tunnel"]
  node_wireguard_manager["Peer and DISCO manager<br/>[ml_wg_mgr.c]"]
  node_wireguard_interface["WireGuard lwIP interface<br/>[wireguardif.c]"]
  node_wireguard_engine["WireGuard protocol<br/>[wireguard.c]"]
  node_crypto["WireGuard cryptography<br/>[crypto.c]"]
end

subgraph group_management["Configuration and State"]
  node_config_server["HTTP config server<br/>[ml_config_httpd.c]"]
  node_config_ui["Config web UI<br/>[ml_config_html.h]"]
  node_peer_cache[("NVS peer cache<br/>[ml_peer_nvs.c]")]
end

node_application(("ESP32 application"))
node_control_plane(("Tailscale control plane"))
node_derp_service(("DERP relay service"))
node_wifi_cellular(("WiFi and cellular"))
node_tailnet_peers(("Tailnet peers"))
node_config_storage[("NVS settings")]

node_application -->|"uses"| node_public_api
node_public_api -.->|"starts client"| node_client_runtime
node_client_runtime -->|"runs task"| node_coordination
node_coordination -->|"registers and polls"| node_control_plane
node_coordination -.->|"uses HTTP/2"| node_h2
node_coordination -->|"sends peer updates"| node_wireguard_manager
node_client_runtime -->|"runs task"| node_derp_client
node_derp_client -->|"relays traffic"| node_derp_service
node_client_runtime -->|"runs task"| node_network_io
node_client_runtime -->|"runs task"| node_wireguard_manager
node_network_switch -->|"selects network"| node_wifi_cellular
node_network_switch -->|"fails over"| node_cellular
node_network_switch -->|"uses fallback"| node_at_socket
node_wireguard_manager -->|"provisions peers"| node_wireguard_interface
node_wireguard_interface -->|"uses protocol"| node_wireguard_engine
node_wireguard_engine -->|"uses cryptography"| node_crypto
node_wireguard_manager -->|"discovers paths"| node_tailnet_peers
node_stun -.->|"discovers endpoints"| node_control_plane
node_public_api -->|"offers TCP"| node_tcp_api
node_public_api -->|"offers UDP"| node_udp_api
node_config_server -->|"serves UI"| node_config_ui
node_config_server -->|"persists settings"| node_config_storage
node_coordination -.->|"loads cached peers"| node_peer_cache

click node_public_api "https://github.com/camm2325/microlink/blob/main/components/microlink/include/microlink.h"
click node_client_runtime "https://github.com/camm2325/microlink/blob/main/components/microlink/src/microlink.c"
click node_coordination "https://github.com/camm2325/microlink/blob/main/components/microlink/src/ml_coord.c"
click node_h2 "https://github.com/camm2325/microlink/blob/main/components/microlink/src/ml_h2.c"
click node_derp_client "https://github.com/camm2325/microlink/blob/main/components/microlink/src/ml_derp.c"
click node_stun "https://github.com/camm2325/microlink/blob/main/components/microlink/src/ml_stun.c"
click node_network_io "https://github.com/camm2325/microlink/blob/main/components/microlink/src/ml_net_io.c"
click node_network_switch "https://github.com/camm2325/microlink/blob/main/components/microlink/src/ml_net_switch.c"
click node_cellular "https://github.com/camm2325/microlink/blob/main/components/microlink/src/ml_cellular.c"
click node_at_socket "https://github.com/camm2325/microlink/blob/main/components/microlink/src/ml_at_socket.c"
click node_wireguard_manager "https://github.com/camm2325/microlink/blob/main/components/microlink/src/ml_wg_mgr.c"
click node_wireguard_interface "https://github.com/camm2325/microlink/blob/main/components/microlink/components/wireguard_lwip/src/wireguardif.c"
click node_wireguard_engine "https://github.com/camm2325/microlink/blob/main/components/microlink/components/wireguard_lwip/src/wireguard.c"
click node_crypto "https://github.com/camm2325/microlink/blob/main/components/microlink/components/wireguard_lwip/src/crypto.c"
click node_config_server "https://github.com/camm2325/microlink/blob/main/components/microlink/src/ml_config_httpd.c"
click node_config_ui "https://github.com/camm2325/microlink/blob/main/components/microlink/src/ml_config_html.h"
click node_peer_cache "https://github.com/camm2325/microlink/blob/main/components/microlink/src/ml_peer_nvs.c"
click node_tcp_api "https://github.com/camm2325/microlink/blob/main/components/microlink/src/ml_tcp.c"
click node_udp_api "https://github.com/camm2325/microlink/blob/main/components/microlink/src/ml_udp.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_public_api,node_client_runtime,node_coordination,node_h2,node_tcp_api,node_udp_api toneBlue
class node_derp_client,node_stun,node_network_io,node_network_switch,node_cellular,node_at_socket,node_config_storage toneAmber
class node_wireguard_manager,node_wireguard_interface,node_wireguard_engine,node_crypto toneMint
class node_config_server,node_config_ui,node_peer_cache toneRose
class node_application,node_control_plane,node_derp_service,node_wifi_cellular,node_tailnet_peers toneIndigo
```

## Components

### Client and Coordination

- [Client API](https://github.com/camm2325/microlink/blob/main/components/microlink/include/microlink.h): `components/microlink/include/microlink.h`
- [Client runtime](https://github.com/camm2325/microlink/blob/main/components/microlink/src/microlink.c): `components/microlink/src/microlink.c`
- [Control coordination](https://github.com/camm2325/microlink/blob/main/components/microlink/src/ml_coord.c): `components/microlink/src/ml_coord.c`
- [HTTP/2 transport](https://github.com/camm2325/microlink/blob/main/components/microlink/src/ml_h2.c): `components/microlink/src/ml_h2.c`
- [TCP socket API](https://github.com/camm2325/microlink/blob/main/components/microlink/src/ml_tcp.c): `components/microlink/src/ml_tcp.c`
- [UDP socket API](https://github.com/camm2325/microlink/blob/main/components/microlink/src/ml_udp.c): `components/microlink/src/ml_udp.c`

### Network Connectivity

- [DERP relay client](https://github.com/camm2325/microlink/blob/main/components/microlink/src/ml_derp.c): `components/microlink/src/ml_derp.c`
- [STUN discovery](https://github.com/camm2325/microlink/blob/main/components/microlink/src/ml_stun.c): `components/microlink/src/ml_stun.c`
- [Network I/O](https://github.com/camm2325/microlink/blob/main/components/microlink/src/ml_net_io.c): `components/microlink/src/ml_net_io.c`
- [Network failover](https://github.com/camm2325/microlink/blob/main/components/microlink/src/ml_net_switch.c): `components/microlink/src/ml_net_switch.c`
- [Cellular PPP](https://github.com/camm2325/microlink/blob/main/components/microlink/src/ml_cellular.c): `components/microlink/src/ml_cellular.c`
- [AT socket bridge](https://github.com/camm2325/microlink/blob/main/components/microlink/src/ml_at_socket.c): `components/microlink/src/ml_at_socket.c`

### WireGuard Tunnel

- [Peer and DISCO manager](https://github.com/camm2325/microlink/blob/main/components/microlink/src/ml_wg_mgr.c): `components/microlink/src/ml_wg_mgr.c`
- [WireGuard lwIP interface](https://github.com/camm2325/microlink/blob/main/components/microlink/components/wireguard_lwip/src/wireguardif.c): `components/microlink/components/wireguard_lwip/src/wireguardif.c`
- [WireGuard protocol](https://github.com/camm2325/microlink/blob/main/components/microlink/components/wireguard_lwip/src/wireguard.c): `components/microlink/components/wireguard_lwip/src/wireguard.c`
- [WireGuard cryptography](https://github.com/camm2325/microlink/blob/main/components/microlink/components/wireguard_lwip/src/crypto.c): `components/microlink/components/wireguard_lwip/src/crypto.c`

### Configuration and State

- [HTTP config server](https://github.com/camm2325/microlink/blob/main/components/microlink/src/ml_config_httpd.c): `components/microlink/src/ml_config_httpd.c`
- [Config web UI](https://github.com/camm2325/microlink/blob/main/components/microlink/src/ml_config_html.h): `components/microlink/src/ml_config_html.h`
- [NVS peer cache](https://github.com/camm2325/microlink/blob/main/components/microlink/src/ml_peer_nvs.c): `components/microlink/src/ml_peer_nvs.c`

### Other components

- **ESP32 application**
- **Tailscale control plane**
- **DERP relay service**
- **WiFi and cellular**
- **Tailnet peers**
- **NVS settings**

## Connections

- ESP32 application → Client API: uses (evidence: `components/microlink/include/microlink.h`)
- Client API → Client runtime: starts client
- Client runtime → Control coordination: runs task
- Control coordination → Tailscale control plane: registers and polls (evidence: `components/microlink/src/ml_coord.c`)
- Control coordination → HTTP/2 transport: uses HTTP/2
- Control coordination → Peer and DISCO manager: sends peer updates (evidence: `components/microlink/src/ml_wg_mgr.c`)
- Client runtime → DERP relay client: runs task
- DERP relay client → DERP relay service: relays traffic
- Client runtime → Network I/O: runs task
- Client runtime → Peer and DISCO manager: runs task
- Network failover → WiFi and cellular: selects network
- Network failover → Cellular PPP: fails over (evidence: `components/microlink/src/ml_net_switch.c`)
- Network failover → AT socket bridge: uses fallback (evidence: `components/microlink/src/ml_net_switch.c`)
- Peer and DISCO manager → WireGuard lwIP interface: provisions peers (evidence: `components/microlink/src/ml_wg_mgr.c`)
- WireGuard lwIP interface → WireGuard protocol: uses protocol (evidence: `components/microlink/components/wireguard_lwip/src/wireguardif.c`)
- WireGuard protocol → WireGuard cryptography: uses cryptography (evidence: `components/microlink/components/wireguard_lwip/src/wireguard.c`)
- Peer and DISCO manager → Tailnet peers: discovers paths
- STUN discovery → Tailscale control plane: discovers endpoints
- Client API → TCP socket API: offers TCP (evidence: `components/microlink/include/microlink.h`)
- Client API → UDP socket API: offers UDP (evidence: `components/microlink/include/microlink.h`)
- HTTP config server → Config web UI: serves UI
- HTTP config server → NVS settings: persists settings
- Control coordination → NVS peer cache: loads cached peers
