# sridhar08-glitch/sheild-dns architecture

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

- Interactive diagram: https://gitdiagram.com/sridhar08-glitch/sheild-dns
- Repository: https://github.com/sridhar08-glitch/sheild-dns

## Overview

ShieldDNS is a three-part ad- and tracker-blocking product: a browser extension, a Windows local DNS server, and an Android DNS filter carried by a local VPN. The main workflows intercept browser requests or device DNS, apply blocklist and behavioral decisions, then block or resolve requests; the apps also expose controls and activity views. Windows orchestration and Android VPN/engine are shown from sampled source. Other Android capabilities and extension behavior are documented in the README; unsampled implementation details and their internal links are not inferred.

Main entry points: [`ShieldDNS/app/src/main/java/com/sridhar/shielddns/core/dns/DnsResolutionEngine.kt`](https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS/app/src/main/java/com/sridhar/shielddns/core/dns/DnsResolutionEngine.kt) (DNS decision engine), [`ShieldDNS-Windows/ShieldDNS/Services/DnsHostService.cs`](https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS-Windows/ShieldDNS/Services/DnsHostService.cs) (DNS host), [`ShieldDNS-Windows/ShieldDNS/Core/DnsResolutionEngine.cs`](https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS-Windows/ShieldDNS/Core/DnsResolutionEngine.cs) (Resolution engine), [`ShieldDNS/app/src/main/java/com/sridhar/shielddns/domain/usecase/VpnController.kt`](https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS/app/src/main/java/com/sridhar/shielddns/domain/usecase/VpnController.kt) (VPN controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_extension["Browser extension"]
  node_extension_worker["Request blocker<br/>[background.js]"]
  node_page_filter["Page filter<br/>[content.js]"]
  node_extension_ui["Extension controls<br/>[popup.js]"]
end

subgraph group_windows["Windows DNS app"]
  node_windows_ui["Desktop controls<br/>[MainWindow.xaml.cs]"]
  node_windows_host["DNS host<br/>[DnsHostService.cs]"]
  node_windows_server["DNS server<br/>[DnsServer.cs]"]
  node_windows_engine["Resolution engine"]
  node_windows_matcher["Domain matcher<br/>[DomainMatcher.cs]"]
  node_windows_lists["Blocklist loader"]
  node_windows_upstream["Upstream resolver"]
  node_windows_network["DNS redirection<br/>[NetworkService.cs]"]
  node_windows_cache[("DNS cache<br/>[DnsCache.cs]")]
end

subgraph group_android["Android VPN app"]
  node_android_ui["App controls<br/>[MainActivity.kt]"]
  node_vpn_control["VPN controller<br/>[VpnController.kt]"]
  node_vpn_service["VPN packet service"]
  node_android_engine["DNS decision engine"]
  node_android_matcher["Domain matcher<br/>[DomainMatcher.kt]"]
  node_android_lists["Blocklist repository"]
  node_android_reputation["Reputation scoring"]
  node_android_chains["Redirect detection<br/>[ChainDetector.kt]"]
  node_android_upstream["Encrypted upstream"]
  node_android_buffer[("Query activity buffer")]
  node_android_settings["Settings repository"]
end

node_browser(("Browser"))
node_windows_user(("Windows user"))
node_android_user(("Android user"))

node_browser -->|"sends requests"| node_extension_worker
node_extension_worker -->|"blocks requests"| node_browser
node_page_filter -->|"hides elements"| node_browser
node_extension_ui -.->|"controls filtering"| node_extension_worker
node_windows_user -->|"starts shield"| node_windows_ui
node_windows_ui -.->|"controls service"| node_windows_host
node_windows_host -->|"starts server"| node_windows_server
node_windows_host -->|"redirects DNS"| node_windows_network
node_windows_host -->|"loads lists"| node_windows_lists
node_windows_server -->|"dispatches queries"| node_windows_engine
node_windows_engine -->|"checks cache"| node_windows_cache
node_windows_engine -->|"checks domains"| node_windows_matcher
node_windows_lists -->|"loads domains"| node_windows_matcher
node_windows_engine -->|"resolves allowed"| node_windows_upstream
node_android_user -->|"starts protection"| node_android_ui
node_android_ui -.->|"requests VPN"| node_vpn_control
node_vpn_control -->|"starts service"| node_vpn_service
node_vpn_service -->|"handles DNS"| node_android_engine
node_android_engine -->|"checks domains"| node_android_matcher
node_android_engine -->|"scores risk"| node_android_reputation
node_android_engine -->|"detects redirects"| node_android_chains
node_android_engine -->|"resolves allowed"| node_android_upstream
node_android_engine -->|"records activity"| node_android_buffer
node_android_lists -->|"builds indexes"| node_android_matcher
node_vpn_control -->|"persists settings"| node_android_settings
node_android_engine -->|"uses DoH/DoT"| node_android_upstream
node_android_engine -->|"detects chains"| node_android_chains

click node_extension_worker "https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS-Extension/background.js"
click node_page_filter "https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS-Extension/content.js"
click node_extension_ui "https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS-Extension/popup.js"
click node_windows_ui "https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS-Windows/ShieldDNS/Views/MainWindow.xaml.cs"
click node_windows_host "https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS-Windows/ShieldDNS/Services/DnsHostService.cs"
click node_windows_server "https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS-Windows/ShieldDNS/Core/DnsServer.cs"
click node_windows_engine "https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS-Windows/ShieldDNS/Core/DnsResolutionEngine.cs"
click node_windows_matcher "https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS-Windows/ShieldDNS/Core/DomainMatcher.cs"
click node_windows_lists "https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS-Windows/ShieldDNS/Services/BlocklistService.cs"
click node_windows_upstream "https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS-Windows/ShieldDNS/Core/UpstreamResolver.cs"
click node_windows_network "https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS-Windows/ShieldDNS/Services/NetworkService.cs"
click node_windows_cache "https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS-Windows/ShieldDNS/Core/DnsCache.cs"
click node_android_ui "https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS/app/src/main/java/com/sridhar/shielddns/MainActivity.kt"
click node_vpn_control "https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS/app/src/main/java/com/sridhar/shielddns/domain/usecase/VpnController.kt"
click node_vpn_service "https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS/app/src/main/java/com/sridhar/shielddns/service/ShieldVpnService.kt"
click node_android_engine "https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS/app/src/main/java/com/sridhar/shielddns/core/dns/DnsResolutionEngine.kt"
click node_android_matcher "https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS/app/src/main/java/com/sridhar/shielddns/core/matcher/DomainMatcher.kt"
click node_android_lists "https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS/app/src/main/java/com/sridhar/shielddns/data/repository/BlocklistRepository.kt"
click node_android_reputation "https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS/app/src/main/java/com/sridhar/shielddns/core/reputation/ReputationScorer.kt"
click node_android_chains "https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS/app/src/main/java/com/sridhar/shielddns/core/redirectchain/ChainDetector.kt"
click node_android_upstream "https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS/app/src/main/java/com/sridhar/shielddns/core/dns/UpstreamResolver.kt"
click node_android_buffer "https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS/app/src/main/java/com/sridhar/shielddns/core/buffer/RollingDnsBuffer.kt"
click node_android_settings "https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS/app/src/main/java/com/sridhar/shielddns/data/repository/SettingsRepository.kt"

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_extension_worker,node_page_filter,node_extension_ui,node_browser,node_windows_user,node_android_user toneBlue
class node_windows_ui,node_windows_host,node_windows_server,node_windows_engine,node_windows_matcher,node_windows_lists,node_windows_upstream,node_windows_network,node_windows_cache toneAmber
class node_android_ui,node_vpn_control,node_vpn_service,node_android_engine,node_android_matcher,node_android_lists,node_android_reputation,node_android_chains,node_android_upstream,node_android_buffer,node_android_settings toneMint
```

## Components

### Browser extension

- [Request blocker](https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS-Extension/background.js): `ShieldDNS-Extension/background.js`
- [Page filter](https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS-Extension/content.js): `ShieldDNS-Extension/content.js`
- [Extension controls](https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS-Extension/popup.js): `ShieldDNS-Extension/popup.js`

### Windows DNS app

- [Desktop controls](https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS-Windows/ShieldDNS/Views/MainWindow.xaml.cs): `ShieldDNS-Windows/ShieldDNS/Views/MainWindow.xaml.cs`
- [DNS host](https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS-Windows/ShieldDNS/Services/DnsHostService.cs): `ShieldDNS-Windows/ShieldDNS/Services/DnsHostService.cs`
- [DNS server](https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS-Windows/ShieldDNS/Core/DnsServer.cs): `ShieldDNS-Windows/ShieldDNS/Core/DnsServer.cs`
- [Resolution engine](https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS-Windows/ShieldDNS/Core/DnsResolutionEngine.cs): `ShieldDNS-Windows/ShieldDNS/Core/DnsResolutionEngine.cs`
- [Domain matcher](https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS-Windows/ShieldDNS/Core/DomainMatcher.cs): `ShieldDNS-Windows/ShieldDNS/Core/DomainMatcher.cs`
- [Blocklist loader](https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS-Windows/ShieldDNS/Services/BlocklistService.cs): `ShieldDNS-Windows/ShieldDNS/Services/BlocklistService.cs`
- [Upstream resolver](https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS-Windows/ShieldDNS/Core/UpstreamResolver.cs): `ShieldDNS-Windows/ShieldDNS/Core/UpstreamResolver.cs`
- [DNS redirection](https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS-Windows/ShieldDNS/Services/NetworkService.cs): `ShieldDNS-Windows/ShieldDNS/Services/NetworkService.cs`
- [DNS cache](https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS-Windows/ShieldDNS/Core/DnsCache.cs): `ShieldDNS-Windows/ShieldDNS/Core/DnsCache.cs`

### Android VPN app

- [App controls](https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS/app/src/main/java/com/sridhar/shielddns/MainActivity.kt): `ShieldDNS/app/src/main/java/com/sridhar/shielddns/MainActivity.kt`
- [VPN controller](https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS/app/src/main/java/com/sridhar/shielddns/domain/usecase/VpnController.kt): `ShieldDNS/app/src/main/java/com/sridhar/shielddns/domain/usecase/VpnController.kt`
- [VPN packet service](https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS/app/src/main/java/com/sridhar/shielddns/service/ShieldVpnService.kt): `ShieldDNS/app/src/main/java/com/sridhar/shielddns/service/ShieldVpnService.kt`
- [DNS decision engine](https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS/app/src/main/java/com/sridhar/shielddns/core/dns/DnsResolutionEngine.kt): `ShieldDNS/app/src/main/java/com/sridhar/shielddns/core/dns/DnsResolutionEngine.kt`
- [Domain matcher](https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS/app/src/main/java/com/sridhar/shielddns/core/matcher/DomainMatcher.kt): `ShieldDNS/app/src/main/java/com/sridhar/shielddns/core/matcher/DomainMatcher.kt`
- [Blocklist repository](https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS/app/src/main/java/com/sridhar/shielddns/data/repository/BlocklistRepository.kt): `ShieldDNS/app/src/main/java/com/sridhar/shielddns/data/repository/BlocklistRepository.kt`
- [Reputation scoring](https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS/app/src/main/java/com/sridhar/shielddns/core/reputation/ReputationScorer.kt): `ShieldDNS/app/src/main/java/com/sridhar/shielddns/core/reputation/ReputationScorer.kt`
- [Redirect detection](https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS/app/src/main/java/com/sridhar/shielddns/core/redirectchain/ChainDetector.kt): `ShieldDNS/app/src/main/java/com/sridhar/shielddns/core/redirectchain/ChainDetector.kt`
- [Encrypted upstream](https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS/app/src/main/java/com/sridhar/shielddns/core/dns/UpstreamResolver.kt): `ShieldDNS/app/src/main/java/com/sridhar/shielddns/core/dns/UpstreamResolver.kt`
- [Query activity buffer](https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS/app/src/main/java/com/sridhar/shielddns/core/buffer/RollingDnsBuffer.kt): `ShieldDNS/app/src/main/java/com/sridhar/shielddns/core/buffer/RollingDnsBuffer.kt`
- [Settings repository](https://github.com/sridhar08-glitch/sheild-dns/blob/main/ShieldDNS/app/src/main/java/com/sridhar/shielddns/data/repository/SettingsRepository.kt): `ShieldDNS/app/src/main/java/com/sridhar/shielddns/data/repository/SettingsRepository.kt`

### Other components

- **Browser**
- **Windows user**
- **Android user**

## Connections

- Browser → Request blocker: sends requests (evidence: `README.md`)
- Request blocker → Browser: blocks requests (evidence: `README.md`)
- Page filter → Browser: hides elements (evidence: `README.md`)
- Extension controls → Request blocker: controls filtering
- Windows user → Desktop controls: starts shield (evidence: `README.md`)
- Desktop controls → DNS host: controls service
- DNS host → DNS server: starts server (evidence: `ShieldDNS-Windows/ShieldDNS/Services/DnsHostService.cs`)
- DNS host → DNS redirection: redirects DNS (evidence: `ShieldDNS-Windows/ShieldDNS/Services/DnsHostService.cs`)
- DNS host → Blocklist loader: loads lists (evidence: `ShieldDNS-Windows/ShieldDNS/Services/DnsHostService.cs`)
- DNS server → Resolution engine: dispatches queries (evidence: `ShieldDNS-Windows/ShieldDNS/Services/DnsHostService.cs`)
- Resolution engine → DNS cache: checks cache (evidence: `ShieldDNS-Windows/ShieldDNS/Core/DnsResolutionEngine.cs`)
- Resolution engine → Domain matcher: checks domains (evidence: `ShieldDNS-Windows/ShieldDNS/Core/DnsResolutionEngine.cs`)
- Blocklist loader → Domain matcher: loads domains (evidence: `ShieldDNS-Windows/ShieldDNS/Services/BlocklistService.cs`)
- Resolution engine → Upstream resolver: resolves allowed (evidence: `ShieldDNS-Windows/ShieldDNS/Core/DnsResolutionEngine.cs`)
- Android user → App controls: starts protection (evidence: `README.md`)
- App controls → VPN controller: requests VPN (evidence: `ShieldDNS/app/src/main/java/com/sridhar/shielddns/MainActivity.kt`)
- VPN controller → VPN packet service: starts service (evidence: `ShieldDNS/app/src/main/java/com/sridhar/shielddns/domain/usecase/VpnController.kt`)
- VPN packet service → DNS decision engine: handles DNS (evidence: `ShieldDNS/app/src/main/java/com/sridhar/shielddns/service/ShieldVpnService.kt`)
- DNS decision engine → Domain matcher: checks domains (evidence: `ShieldDNS/app/src/main/java/com/sridhar/shielddns/core/dns/DnsResolutionEngine.kt`)
- DNS decision engine → Reputation scoring: scores risk (evidence: `ShieldDNS/app/src/main/java/com/sridhar/shielddns/core/dns/DnsResolutionEngine.kt`)
- DNS decision engine → Redirect detection: detects redirects (evidence: `ShieldDNS/app/src/main/java/com/sridhar/shielddns/core/dns/DnsResolutionEngine.kt`)
- DNS decision engine → Encrypted upstream: resolves allowed (evidence: `ShieldDNS/app/src/main/java/com/sridhar/shielddns/core/dns/DnsResolutionEngine.kt`)
- DNS decision engine → Query activity buffer: records activity (evidence: `ShieldDNS/app/src/main/java/com/sridhar/shielddns/core/dns/DnsResolutionEngine.kt`)
- Blocklist repository → Domain matcher: builds indexes (evidence: `ShieldDNS/app/src/main/java/com/sridhar/shielddns/data/repository/BlocklistRepository.kt`)
- VPN controller → Settings repository: persists settings (evidence: `ShieldDNS/app/src/main/java/com/sridhar/shielddns/domain/usecase/VpnController.kt`)
- DNS decision engine → Encrypted upstream: uses DoH/DoT (evidence: `README.md`)
- DNS decision engine → Redirect detection: detects chains (evidence: `README.md`)