# tuhinpal/esp-dns-ad-blocker architecture

> Architecture diagram of the GitHub repository tuhinpal/esp-dns-ad-blocker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tuhinpal/esp-dns-ad-blocker
- Repository: https://github.com/tuhinpal/esp-dns-ad-blocker

## Overview

This MicroPython project turns an ESP32 or Pico W into a DNS ad blocker with a browser-based blocklist manager. At startup, the application connects to WiFi, loads the persistent domain list, creates both servers, and runs DNS, web, and periodic-maintenance loops concurrently. DNS requests are checked against the blocklist and cache before being forwarded upstream; the web interface lists, adds, and removes blocked domains. The excerpts show these core flows, but not detailed hardware behavior beyond the WiFi manager or any web use of its WiFi reference.

Main entry points: [`main.py`](https://github.com/tuhinpal/esp-dns-ad-blocker/blob/main/main.py) (Application Orchestrator), [`dns_socket.py`](https://github.com/tuhinpal/esp-dns-ad-blocker/blob/main/dns_socket.py) (DNS Request Handler), [`blocklist_manager.py`](https://github.com/tuhinpal/esp-dns-ad-blocker/blob/main/blocklist_manager.py) (Blocklist Manager), [`web_socket.py`](https://github.com/tuhinpal/esp-dns-ad-blocker/blob/main/web_socket.py) (Web Interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Device Runtime"]
  node_main["Application Orchestrator<br/>[main.py]"]
  node_wifi["WiFi Connection<br/>[wifi_manager.py]"]
end

subgraph group_dns["DNS Service"]
  node_dns_handler["DNS Request Handler<br/>[dns_socket.py]"]
  node_dns_cache["DNS Cache<br/>[dns_socket.py]"]
end

subgraph group_management["Blocklist Management"]
  node_web["Web Interface<br/>[web_socket.py]"]
  node_blocklist["Blocklist Manager"]
  node_blocklist_file[("Persistent Blocklist<br/>[blocklist.txt]")]
end

node_device(("ESP Device"))
node_dns_client(("DNS Clients"))
node_upstream{{"Cloudflare DNS"}}
node_browser(("Browser User"))

node_device -->|"runs"| node_main
node_main -->|"connects"| node_wifi
node_main -->|"initializes"| node_blocklist
node_main -->|"starts DNS loop"| node_dns_handler
node_main -->|"starts web loop"| node_web
node_main -->|"schedules maintenance"| node_dns_handler
node_dns_client -->|"sends queries"| node_dns_handler
node_dns_handler -->|"checks domain"| node_blocklist
node_dns_handler -->|"checks and updates"| node_dns_cache
node_dns_handler -->|"forwards query"| node_upstream
node_browser -->|"sends requests"| node_web
node_web -->|"lists and edits"| node_blocklist
node_blocklist -->|"loads and saves"| node_blocklist_file

click node_main "https://github.com/tuhinpal/esp-dns-ad-blocker/blob/main/main.py"
click node_wifi "https://github.com/tuhinpal/esp-dns-ad-blocker/blob/main/wifi_manager.py"
click node_dns_handler "https://github.com/tuhinpal/esp-dns-ad-blocker/blob/main/dns_socket.py"
click node_dns_cache "https://github.com/tuhinpal/esp-dns-ad-blocker/blob/main/dns_socket.py"
click node_web "https://github.com/tuhinpal/esp-dns-ad-blocker/blob/main/web_socket.py"
click node_blocklist "https://github.com/tuhinpal/esp-dns-ad-blocker/blob/main/blocklist_manager.py"
click node_blocklist_file "https://github.com/tuhinpal/esp-dns-ad-blocker/blob/main/blocklist.txt"

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_main,node_wifi,node_dns_client,node_browser toneBlue
class node_dns_handler,node_dns_cache toneAmber
class node_web,node_blocklist,node_blocklist_file toneMint
class node_device,node_upstream toneIndigo
```

## Components

### Device Runtime

- [Application Orchestrator](https://github.com/tuhinpal/esp-dns-ad-blocker/blob/main/main.py): `main.py`
- [WiFi Connection](https://github.com/tuhinpal/esp-dns-ad-blocker/blob/main/wifi_manager.py): `wifi_manager.py`

### DNS Service

- [DNS Request Handler](https://github.com/tuhinpal/esp-dns-ad-blocker/blob/main/dns_socket.py): `dns_socket.py`
- [DNS Cache](https://github.com/tuhinpal/esp-dns-ad-blocker/blob/main/dns_socket.py): `dns_socket.py`

### Blocklist Management

- [Web Interface](https://github.com/tuhinpal/esp-dns-ad-blocker/blob/main/web_socket.py): `web_socket.py`
- [Blocklist Manager](https://github.com/tuhinpal/esp-dns-ad-blocker/blob/main/blocklist_manager.py): `blocklist_manager.py`
- [Persistent Blocklist](https://github.com/tuhinpal/esp-dns-ad-blocker/blob/main/blocklist.txt): `blocklist.txt`

### Other components

- **ESP Device**
- **DNS Clients**
- **Cloudflare DNS**
- **Browser User**

## Connections

- ESP Device → Application Orchestrator: runs (evidence: `README.md`)
- Application Orchestrator → WiFi Connection: connects (evidence: `main.py`)
- Application Orchestrator → Blocklist Manager: initializes (evidence: `main.py`)
- Application Orchestrator → DNS Request Handler: starts DNS loop (evidence: `main.py`)
- Application Orchestrator → Web Interface: starts web loop (evidence: `main.py`)
- Application Orchestrator → DNS Request Handler: schedules maintenance (evidence: `main.py`)
- DNS Clients → DNS Request Handler: sends queries (evidence: `README.md`)
- DNS Request Handler → Blocklist Manager: checks domain (evidence: `dns_socket.py`)
- DNS Request Handler → DNS Cache: checks and updates (evidence: `dns_socket.py`)
- DNS Request Handler → Cloudflare DNS: forwards query (evidence: `dns_socket.py`)
- Browser User → Web Interface: sends requests (evidence: `README.md`)
- Web Interface → Blocklist Manager: lists and edits (evidence: `web_socket.py`)
- Blocklist Manager → Persistent Blocklist: loads and saves (evidence: `blocklist_manager.py`)