# martin-ger/esp32_nat_router architecture

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

- Interactive diagram: https://gitdiagram.com/martin-ger/esp32_nat_router
- Repository: https://github.com/martin-ger/esp32_nat_router

## Overview

ESP32 NAT Router is firmware that provides a WiFi access point and routes its clients through a WiFi or Ethernet uplink, optionally through WireGuard. The principal workflow is client traffic entering the AP, being filtered and NAT-routed, then forwarded to the uplink; administrators configure that behavior through the web UI or CLI. The graph also preserves documented management, monitoring, and device-status capabilities. Source excerpts are partial, so uncertain internal wiring is omitted; some feature nodes and relationships reflect README documentation rather than sampled implementations.

Main entry points: [`main/esp32_nat_router.c`](https://github.com/martin-ger/esp32_nat_router/blob/master/main/esp32_nat_router.c) (Router firmware), [`components/http_server/http_server.c`](https://github.com/martin-ger/esp32_nat_router/blob/master/components/http_server/http_server.c) (Web interface), [`main/netif_hooks.c`](https://github.com/martin-ger/esp32_nat_router/blob/master/main/netif_hooks.c) (Interface hooks), [`components/mqtt_ha/mqtt_ha.c`](https://github.com/martin-ger/esp32_nat_router/blob/master/components/mqtt_ha/mqtt_ha.c) (MQTT Home Assistant)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_routing["Routing and uplinks"]
  node_router["Router firmware<br/>[esp32_nat_router.c]"]
  node_netif["Interface hooks<br/>[netif_hooks.c]"]
  node_dhcp["DHCP service<br/>[dhcpserver.c]"]
  node_reservations["DHCP reservations<br/>[dhcp_manager.c]"]
  node_vpn["WireGuard manager<br/>[vpn_manager.c]"]
end

subgraph group_management["Configuration and access"]
  node_web["Web interface<br/>[http_server.c]"]
  node_web_pages["Web pages<br/>[pages.h]"]
  node_cli["Serial CLI<br/>[cmd_router.c]"]
  node_remote_cli["Remote console<br/>[remote_console.c]"]
  node_mcp["MCP bridge"]
end

subgraph group_security["Traffic controls"]
  node_acl["Firewall ACL<br/>[acl.c]"]
  node_portmap["Port forwarding<br/>[portmap.c]"]
end

subgraph group_monitoring["Monitoring and status"]
  node_pcap["Packet capture<br/>[pcap_capture.c]"]
  node_stats["Client statistics<br/>[client_stats.h]"]
  node_oled["OLED display<br/>[oled_display.c]"]
  node_led["LED status<br/>[led_strip_status.c]"]
end

subgraph group_integrations["External integrations"]
  node_mqtt["MQTT Home Assistant<br/>[mqtt_ha.c]"]
  node_syslog["Syslog client<br/>[syslog_client.c]"]
end

node_admin(("Administrator"))
node_clients(("AP clients"))
node_uplink(("WiFi / Ethernet uplink"))
node_ha(("Home Assistant"))
node_broker(("MQTT broker"))
node_syslog_server(("Syslog server"))
node_wireshark(("Capture consumer"))

node_clients -->|"request leases"| node_dhcp
node_dhcp -->|"look up reservations"| node_reservations
node_clients -->|"send traffic"| node_netif
node_netif -->|"filter packets"| node_acl
node_netif -->|"apply mappings"| node_portmap
node_router -->|"initialize hooks"| node_netif
node_router -->|"manage tunnel"| node_vpn
node_router -->|"forward routed traffic"| node_uplink
node_admin -->|"configure"| node_web
node_web -->|"serve pages"| node_web_pages
node_admin -->|"enter commands"| node_cli
node_admin -->|"connect remotely"| node_remote_cli
node_admin -.->|"control by MCP"| node_mcp
node_web -->|"manage rules"| node_acl
node_web -->|"manage mappings"| node_portmap
node_web -->|"configure VPN"| node_vpn
node_netif -->|"capture packets"| node_pcap
node_pcap -->|"stream capture"| node_wireshark
node_router -.->|"collect client stats"| node_stats
node_router -.->|"show status"| node_oled
node_router -.->|"signal status"| node_led
node_mqtt -->|"publish telemetry"| node_broker
node_mqtt -->|"provide discovery"| node_ha
node_syslog -->|"send log messages"| node_syslog_server

click node_router "https://github.com/martin-ger/esp32_nat_router/blob/master/main/esp32_nat_router.c"
click node_netif "https://github.com/martin-ger/esp32_nat_router/blob/master/main/netif_hooks.c"
click node_dhcp "https://github.com/martin-ger/esp32_nat_router/blob/master/components/dhcpserver/dhcpserver.c"
click node_reservations "https://github.com/martin-ger/esp32_nat_router/blob/master/main/dhcp_manager.c"
click node_vpn "https://github.com/martin-ger/esp32_nat_router/blob/master/main/vpn_manager.c"
click node_web "https://github.com/martin-ger/esp32_nat_router/blob/master/components/http_server/http_server.c"
click node_web_pages "https://github.com/martin-ger/esp32_nat_router/blob/master/components/http_server/pages.h"
click node_cli "https://github.com/martin-ger/esp32_nat_router/blob/master/components/cmd_router/cmd_router.c"
click node_remote_cli "https://github.com/martin-ger/esp32_nat_router/blob/master/components/remote_console/remote_console.c"
click node_acl "https://github.com/martin-ger/esp32_nat_router/blob/master/components/acl/acl.c"
click node_portmap "https://github.com/martin-ger/esp32_nat_router/blob/master/main/portmap.c"
click node_pcap "https://github.com/martin-ger/esp32_nat_router/blob/master/components/pcap_capture/pcap_capture.c"
click node_stats "https://github.com/martin-ger/esp32_nat_router/blob/master/include/client_stats.h"
click node_oled "https://github.com/martin-ger/esp32_nat_router/blob/master/components/oled_display/oled_display.c"
click node_led "https://github.com/martin-ger/esp32_nat_router/blob/master/main/led_strip_status.c"
click node_mqtt "https://github.com/martin-ger/esp32_nat_router/blob/master/components/mqtt_ha/mqtt_ha.c"
click node_syslog "https://github.com/martin-ger/esp32_nat_router/blob/master/components/syslog/syslog_client.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_router,node_netif,node_dhcp,node_reservations,node_vpn,node_clients toneBlue
class node_web,node_web_pages,node_cli,node_remote_cli,node_mcp toneAmber
class node_acl,node_portmap,node_syslog_server toneMint
class node_pcap,node_stats,node_oled,node_led toneRose
class node_mqtt,node_syslog,node_admin,node_uplink,node_ha,node_broker,node_wireshark toneIndigo
```

## Components

### Routing and uplinks

- [Router firmware](https://github.com/martin-ger/esp32_nat_router/blob/master/main/esp32_nat_router.c): `main/esp32_nat_router.c`
- [Interface hooks](https://github.com/martin-ger/esp32_nat_router/blob/master/main/netif_hooks.c): `main/netif_hooks.c`
- [DHCP service](https://github.com/martin-ger/esp32_nat_router/blob/master/components/dhcpserver/dhcpserver.c): `components/dhcpserver/dhcpserver.c`
- [DHCP reservations](https://github.com/martin-ger/esp32_nat_router/blob/master/main/dhcp_manager.c): `main/dhcp_manager.c`
- [WireGuard manager](https://github.com/martin-ger/esp32_nat_router/blob/master/main/vpn_manager.c): `main/vpn_manager.c`

### Configuration and access

- [Web interface](https://github.com/martin-ger/esp32_nat_router/blob/master/components/http_server/http_server.c): `components/http_server/http_server.c`
- [Web pages](https://github.com/martin-ger/esp32_nat_router/blob/master/components/http_server/pages.h): `components/http_server/pages.h`
- [Serial CLI](https://github.com/martin-ger/esp32_nat_router/blob/master/components/cmd_router/cmd_router.c): `components/cmd_router/cmd_router.c`
- [Remote console](https://github.com/martin-ger/esp32_nat_router/blob/master/components/remote_console/remote_console.c): `components/remote_console/remote_console.c`
- **MCP bridge**

### Traffic controls

- [Firewall ACL](https://github.com/martin-ger/esp32_nat_router/blob/master/components/acl/acl.c): `components/acl/acl.c`
- [Port forwarding](https://github.com/martin-ger/esp32_nat_router/blob/master/main/portmap.c): `main/portmap.c`

### Monitoring and status

- [Packet capture](https://github.com/martin-ger/esp32_nat_router/blob/master/components/pcap_capture/pcap_capture.c): `components/pcap_capture/pcap_capture.c`
- [Client statistics](https://github.com/martin-ger/esp32_nat_router/blob/master/include/client_stats.h): `include/client_stats.h`
- [OLED display](https://github.com/martin-ger/esp32_nat_router/blob/master/components/oled_display/oled_display.c): `components/oled_display/oled_display.c`
- [LED status](https://github.com/martin-ger/esp32_nat_router/blob/master/main/led_strip_status.c): `main/led_strip_status.c`

### External integrations

- [MQTT Home Assistant](https://github.com/martin-ger/esp32_nat_router/blob/master/components/mqtt_ha/mqtt_ha.c): `components/mqtt_ha/mqtt_ha.c`
- [Syslog client](https://github.com/martin-ger/esp32_nat_router/blob/master/components/syslog/syslog_client.c): `components/syslog/syslog_client.c`

### Other components

- **Administrator**
- **AP clients**
- **WiFi / Ethernet uplink**
- **Home Assistant**
- **MQTT broker**
- **Syslog server**
- **Capture consumer**

## Connections

- AP clients → DHCP service: request leases
- DHCP service → DHCP reservations: look up reservations
- AP clients → Interface hooks: send traffic
- Interface hooks → Firewall ACL: filter packets
- Interface hooks → Port forwarding: apply mappings
- Router firmware → Interface hooks: initialize hooks
- Router firmware → WireGuard manager: manage tunnel
- Router firmware → WiFi / Ethernet uplink: forward routed traffic
- Administrator → Web interface: configure
- Web interface → Web pages: serve pages
- Administrator → Serial CLI: enter commands
- Administrator → Remote console: connect remotely
- Administrator → MCP bridge: control by MCP
- Web interface → Firewall ACL: manage rules
- Web interface → Port forwarding: manage mappings
- Web interface → WireGuard manager: configure VPN
- Interface hooks → Packet capture: capture packets
- Packet capture → Capture consumer: stream capture
- Router firmware → Client statistics: collect client stats
- Router firmware → OLED display: show status
- Router firmware → LED status: signal status
- MQTT Home Assistant → MQTT broker: publish telemetry
- MQTT Home Assistant → Home Assistant: provide discovery
- Syslog client → Syslog server: send log messages