# s60sc/esp32_adblocker architecture

> Architecture diagram of the GitHub repository s60sc/esp32_adblocker, 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/s60sc/esp32_adblocker
- Repository: https://github.com/s60sc/esp32_adblocker

## Overview

ESP32_AdBlocker is an ESP32 DNS sinkhole with a browser-based control and monitoring interface. DNS clients send queries to the device; the DNS service checks the in-memory blocklist, returns sinkhole responses for matches, and resolves other names through upstream DNS. Operators configure networking and blocklist sources, reload or stop downloads, and manage custom allow/block entries through the web UI. The README also documents Ethernet/Wi-Fi modes, WebDAV, OTA, logging, and LED status. Some subsystem links are based on documented capabilities because their implementation was not sampled.

Main entry points: [`webServer.cpp`](https://github.com/s60sc/esp32_adblocker/blob/main/webServer.cpp) (HTTP and WebSocket), [`externalDNS.cpp`](https://github.com/s60sc/esp32_adblocker/blob/main/externalDNS.cpp) (DNS query service), [`appSpecific.cpp`](https://github.com/s60sc/esp32_adblocker/blob/main/appSpecific.cpp) (Blocklist download), [`ESP32_AdBlocker.ino`](https://github.com/s60sc/esp32_adblocker/blob/main/ESP32_AdBlocker.ino) (Application startup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dns["DNS service"]
  node_dnsservice["DNS query service<br/>[externalDNS.cpp]"]
end

subgraph group_blocks["Blocklist management"]
  node_blocklist["Blocklist lookup<br/>[appSpecific.cpp]"]
  node_download["Blocklist download<br/>[appSpecific.cpp]"]
  node_custom["Custom domains<br/>[appSpecific.cpp]"]
  node_blockstore[("Blocklist snapshots<br/>[appSpecific.cpp]")]
end

subgraph group_control["Web control"]
  node_webui["Control web UI<br/>[AdBlocker.htm]"]
  node_webjs["UI behavior<br/>[common.js]"]
  node_webserver["HTTP and WebSocket<br/>[webServer.cpp]"]
  node_config["Configuration<br/>[prefs.cpp]"]
  node_webdav["WebDAV access<br/>[webDav.cpp]"]
end

subgraph group_platform["Device services"]
  node_configstore[("Config and files<br/>[prefs.cpp]")]
  node_setup["First-run setup<br/>[setupAssist.cpp]"]
  node_network["Network services<br/>[utils.cpp]"]
  node_logging["Logging<br/>[utilsLog.cpp]"]
  node_firmware["Application startup"]
  node_led["Status LED<br/>[appSpecific.cpp]"]
end

node_client(("DNS client"))
node_upstream["Upstream DNS"]
node_blocksource["Blocklist source"]
node_browser(("Browser operator"))

node_client -->|"queries"| node_dnsservice
node_dnsservice -->|"checks domain"| node_blocklist
node_dnsservice -->|"resolves misses"| node_upstream
node_dnsservice -->|"DNS replies"| node_client
node_blocksource -->|"provides list"| node_download
node_download -->|"builds list"| node_blocklist
node_download -->|"saves snapshot"| node_blockstore
node_blocklist -->|"applies overrides"| node_custom
node_browser -->|"opens"| node_webui
node_webui -->|"loads scripts"| node_webjs
node_webjs -->|"requests status and actions"| node_webserver
node_webserver -->|"updates settings"| node_config
node_webserver -->|"controls reload"| node_download
node_webserver -->|"manages domains"| node_custom
node_webserver -->|"serves logs"| node_logging
node_webserver -->|"routes WebDAV"| node_webdav
node_config -->|"persists settings"| node_configstore
node_webdav -->|"reads and writes files"| node_configstore
node_setup -.->|"downloads web files"| node_configstore
node_setup -->|"uses connectivity"| node_network
node_firmware -->|"starts networking"| node_network
node_firmware -->|"starts DNS"| node_dnsservice
node_firmware -->|"loads settings"| node_config
node_firmware -->|"updates status"| node_led
node_download -->|"reports progress"| node_logging

click node_dnsservice "https://github.com/s60sc/esp32_adblocker/blob/main/externalDNS.cpp"
click node_blocklist "https://github.com/s60sc/esp32_adblocker/blob/main/appSpecific.cpp"
click node_download "https://github.com/s60sc/esp32_adblocker/blob/main/appSpecific.cpp"
click node_custom "https://github.com/s60sc/esp32_adblocker/blob/main/appSpecific.cpp"
click node_blockstore "https://github.com/s60sc/esp32_adblocker/blob/main/appSpecific.cpp"
click node_webui "https://github.com/s60sc/esp32_adblocker/blob/main/data/AdBlocker.htm"
click node_webjs "https://github.com/s60sc/esp32_adblocker/blob/main/data/common.js"
click node_webserver "https://github.com/s60sc/esp32_adblocker/blob/main/webServer.cpp"
click node_config "https://github.com/s60sc/esp32_adblocker/blob/main/prefs.cpp"
click node_configstore "https://github.com/s60sc/esp32_adblocker/blob/main/prefs.cpp"
click node_webdav "https://github.com/s60sc/esp32_adblocker/blob/main/webDav.cpp"
click node_setup "https://github.com/s60sc/esp32_adblocker/blob/main/setupAssist.cpp"
click node_network "https://github.com/s60sc/esp32_adblocker/blob/main/utils.cpp"
click node_logging "https://github.com/s60sc/esp32_adblocker/blob/main/utilsLog.cpp"
click node_firmware "https://github.com/s60sc/esp32_adblocker/blob/main/ESP32_AdBlocker.ino"
click node_led "https://github.com/s60sc/esp32_adblocker/blob/main/appSpecific.cpp"

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_dnsservice,node_client,node_browser toneBlue
class node_blocklist,node_download,node_custom,node_blockstore toneAmber
class node_webui,node_webjs,node_webserver,node_config,node_webdav toneMint
class node_configstore,node_setup,node_network,node_logging,node_firmware,node_led toneRose
class node_upstream,node_blocksource toneIndigo
```

## Components

### DNS service

- [DNS query service](https://github.com/s60sc/esp32_adblocker/blob/main/externalDNS.cpp): `externalDNS.cpp`

### Blocklist management

- [Blocklist lookup](https://github.com/s60sc/esp32_adblocker/blob/main/appSpecific.cpp): `appSpecific.cpp`
- [Blocklist download](https://github.com/s60sc/esp32_adblocker/blob/main/appSpecific.cpp): `appSpecific.cpp`
- [Custom domains](https://github.com/s60sc/esp32_adblocker/blob/main/appSpecific.cpp): `appSpecific.cpp`
- [Blocklist snapshots](https://github.com/s60sc/esp32_adblocker/blob/main/appSpecific.cpp): `appSpecific.cpp`

### Web control

- [Control web UI](https://github.com/s60sc/esp32_adblocker/blob/main/data/AdBlocker.htm): `data/AdBlocker.htm`
- [UI behavior](https://github.com/s60sc/esp32_adblocker/blob/main/data/common.js): `data/common.js`
- [HTTP and WebSocket](https://github.com/s60sc/esp32_adblocker/blob/main/webServer.cpp): `webServer.cpp`
- [Configuration](https://github.com/s60sc/esp32_adblocker/blob/main/prefs.cpp): `prefs.cpp`
- [WebDAV access](https://github.com/s60sc/esp32_adblocker/blob/main/webDav.cpp): `webDav.cpp`

### Device services

- [Config and files](https://github.com/s60sc/esp32_adblocker/blob/main/prefs.cpp): `prefs.cpp`
- [First-run setup](https://github.com/s60sc/esp32_adblocker/blob/main/setupAssist.cpp): `setupAssist.cpp`
- [Network services](https://github.com/s60sc/esp32_adblocker/blob/main/utils.cpp): `utils.cpp`
- [Logging](https://github.com/s60sc/esp32_adblocker/blob/main/utilsLog.cpp): `utilsLog.cpp`
- [Application startup](https://github.com/s60sc/esp32_adblocker/blob/main/ESP32_AdBlocker.ino): `ESP32_AdBlocker.ino`
- [Status LED](https://github.com/s60sc/esp32_adblocker/blob/main/appSpecific.cpp): `appSpecific.cpp`

### Other components

- **DNS client**
- **Upstream DNS**
- **Blocklist source**
- **Browser operator**

## Connections

- DNS client → DNS query service: queries
- DNS query service → Blocklist lookup: checks domain
- DNS query service → Upstream DNS: resolves misses
- DNS query service → DNS client: DNS replies
- Blocklist source → Blocklist download: provides list
- Blocklist download → Blocklist lookup: builds list
- Blocklist download → Blocklist snapshots: saves snapshot
- Blocklist lookup → Custom domains: applies overrides
- Browser operator → Control web UI: opens
- Control web UI → UI behavior: loads scripts
- UI behavior → HTTP and WebSocket: requests status and actions
- HTTP and WebSocket → Configuration: updates settings
- HTTP and WebSocket → Blocklist download: controls reload
- HTTP and WebSocket → Custom domains: manages domains
- HTTP and WebSocket → Logging: serves logs
- HTTP and WebSocket → WebDAV access: routes WebDAV
- Configuration → Config and files: persists settings
- WebDAV access → Config and files: reads and writes files
- First-run setup → Config and files: downloads web files
- First-run setup → Network services: uses connectivity
- Application startup → Network services: starts networking
- Application startup → DNS query service: starts DNS
- Application startup → Configuration: loads settings
- Application startup → Status LED: updates status
- Blocklist download → Logging: reports progress