# syedwafeeq/dns-resolver-implementation architecture

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

- Interactive diagram: https://gitdiagram.com/syedwafeeq/dns-resolver-implementation
- Repository: https://github.com/syedwafeeq/dns-resolver-implementation

## Overview

DNS Consensus Resolver accepts DNS-over-UDP queries, checks its TTL cache, and on a miss queries Google and Cloudflare over DoH. It extracts A records, resolves ASNs, and validates private-address, IP-overlap, and ASN-overlap signals before returning the Google response or a sinkhole answer. Transactions are queued for JSON-line logging. The implementation is concentrated in resolve.py; README documents the capabilities and flow. No separate source module or persistent cache implementation is present.

Main entry points: [`resolve.py`](https://github.com/syedwafeeq/dns-resolver-implementation/blob/main/resolve.py) (Query Handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["DNS Server"]
  node_listener["UDP Listener<br/>[resolve.py]"]
  node_handler["Query Handler<br/>[resolve.py]"]
  node_sinkhole["Sinkhole Reply<br/>[resolve.py]"]
end

subgraph group_validation["Consensus Validation"]
  node_google["Google DoH"]
  node_cloudflare["Cloudflare DoH"]
  node_extract["A Record Extraction<br/>[resolve.py]"]
  node_asn["ASN Lookup<br/>[resolve.py]"]
  node_validator["Response Validator<br/>[resolve.py]"]
end

subgraph group_state["Cache and Logging"]
  node_cache[("TTL Cache<br/>[resolve.py]")]
  node_logger["Log Queue and Writer<br/>[resolve.py]"]
  node_logfile[("JSON Log File<br/>[resolve.py]")]
end

node_client(("DNS Client"))
node_rdap["RDAP Service"]

node_client -->|"sends DNS"| node_listener
node_listener -->|"dispatches query"| node_handler
node_handler -->|"checks cache"| node_cache
node_handler -->|"queries DoH"| node_google
node_handler -->|"queries DoH"| node_cloudflare
node_handler -->|"extracts records"| node_extract
node_handler -->|"gets ASN sets"| node_asn
node_asn -->|"looks up ASN"| node_rdap
node_handler -->|"checks consensus"| node_validator
node_handler -->|"builds blocked reply"| node_sinkhole
node_handler -->|"stores response"| node_cache
node_handler -->|"sends DNS reply"| node_client
node_handler -->|"queues event"| node_logger
node_logger -->|"appends JSON"| node_logfile

click node_listener "https://github.com/syedwafeeq/dns-resolver-implementation/blob/main/resolve.py"
click node_handler "https://github.com/syedwafeeq/dns-resolver-implementation/blob/main/resolve.py"
click node_cache "https://github.com/syedwafeeq/dns-resolver-implementation/blob/main/resolve.py"
click node_extract "https://github.com/syedwafeeq/dns-resolver-implementation/blob/main/resolve.py"
click node_asn "https://github.com/syedwafeeq/dns-resolver-implementation/blob/main/resolve.py"
click node_validator "https://github.com/syedwafeeq/dns-resolver-implementation/blob/main/resolve.py"
click node_sinkhole "https://github.com/syedwafeeq/dns-resolver-implementation/blob/main/resolve.py"
click node_logger "https://github.com/syedwafeeq/dns-resolver-implementation/blob/main/resolve.py"
click node_logfile "https://github.com/syedwafeeq/dns-resolver-implementation/blob/main/resolve.py"

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_listener,node_handler,node_sinkhole,node_client toneBlue
class node_google,node_cloudflare,node_extract,node_asn,node_validator toneAmber
class node_cache,node_logger,node_logfile toneMint
class node_rdap toneIndigo
```

## Components

### DNS Server

- [UDP Listener](https://github.com/syedwafeeq/dns-resolver-implementation/blob/main/resolve.py): `resolve.py`
- [Query Handler](https://github.com/syedwafeeq/dns-resolver-implementation/blob/main/resolve.py): `resolve.py`
- [Sinkhole Reply](https://github.com/syedwafeeq/dns-resolver-implementation/blob/main/resolve.py): `resolve.py`

### Consensus Validation

- **Google DoH**
- **Cloudflare DoH**
- [A Record Extraction](https://github.com/syedwafeeq/dns-resolver-implementation/blob/main/resolve.py): `resolve.py`
- [ASN Lookup](https://github.com/syedwafeeq/dns-resolver-implementation/blob/main/resolve.py): `resolve.py`
- [Response Validator](https://github.com/syedwafeeq/dns-resolver-implementation/blob/main/resolve.py): `resolve.py`

### Cache and Logging

- [TTL Cache](https://github.com/syedwafeeq/dns-resolver-implementation/blob/main/resolve.py): `resolve.py`
- [Log Queue and Writer](https://github.com/syedwafeeq/dns-resolver-implementation/blob/main/resolve.py): `resolve.py`
- [JSON Log File](https://github.com/syedwafeeq/dns-resolver-implementation/blob/main/resolve.py): `resolve.py`

### Other components

- **DNS Client**
- **RDAP Service**

## Connections

- DNS Client → UDP Listener: sends DNS (evidence: `README.md`)
- UDP Listener → Query Handler: dispatches query (evidence: `resolve.py`)
- Query Handler → TTL Cache: checks cache (evidence: `resolve.py`)
- Query Handler → Google DoH: queries DoH (evidence: `resolve.py`)
- Query Handler → Cloudflare DoH: queries DoH (evidence: `resolve.py`)
- Query Handler → A Record Extraction: extracts records (evidence: `resolve.py`)
- Query Handler → ASN Lookup: gets ASN sets (evidence: `resolve.py`)
- ASN Lookup → RDAP Service: looks up ASN (evidence: `resolve.py`)
- Query Handler → Response Validator: checks consensus (evidence: `resolve.py`)
- Query Handler → Sinkhole Reply: builds blocked reply (evidence: `resolve.py`)
- Query Handler → TTL Cache: stores response (evidence: `resolve.py`)
- Query Handler → DNS Client: sends DNS reply (evidence: `resolve.py`)
- Query Handler → Log Queue and Writer: queues event (evidence: `resolve.py`)
- Log Queue and Writer → JSON Log File: appends JSON (evidence: `resolve.py`)
