# bhanupratapys/dnswarden architecture

> Architecture diagram of the GitHub repository bhanupratapys/dnswarden, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bhanupratapys/dnswarden
- Repository: https://github.com/bhanupratapys/dnswarden

## Overview

##### Project type and purpose
- This repository is not a classic code-only application but rather the documentation and configuration “stamps” for a privacy-oriented, filterable DNS service (DNSWarden). It defines multiple DNS resolver endpoints (over DoT, DoH, DoQ, DNSCrypt) and provides per-client configuration files (“stamps”) for different filter profiles (uncensored, adblock, adult, custom).

##### File structure
- Top-level:
- `.github/workflows/delete_workflows.yml` – CI workflow managing stamp files.
- `stamps/` – folders containing markdown templates that clients import to configure their DNS software.
- `LICENSE`, `README.md` – project metadata and service overview.
- No traditional “src” or “backend/frontend” code here; the repo’s function is to hold configuration artifacts and documentation for the running DNS infrastructure.

##### README for additional insights
- Describes four filter profiles (uncensored, adblock, adult, custom) and supported protocols (DNS-over-TLS, HTTPS, QUIC, DNSCrypt).
- Lists public endpoints per profile and protocol.
- Mentions upstream datacenter fallbacks, blocklists, DNSSEC/QNAME minimization.
- Client software support and “stamps” download URLs.

##### Main components and interactions (to be shown
a. Clients
- Various client apps or OS resolvers (Android apps, Knot, Unbound, dnscrypt-proxy, etc.)
b. Network transit
- The internet channel (TLS, HTTPS, QUIC, DNSCrypt tunnels)
c. Edge/Ingress layer
- Protocol listeners (DoT listener, DoH HTTP server, DoQ QUIC server, DNSCrypt server)
d. Filter engine
- Blocklist DB + policy engine applying the chosen filter profile (uncensored/adblock/adult/custom)
e. Resolver core
- Caching resolver logic with DNSSEC and QNAME minimization
f. Upstream fallback
- Datacenter DNS servers used when the resolver cannot answer from cache
g. Stamps repository & CI
- `.github` workflow that regenerates stamp files → `stamps/` folder → clients pulling updated stamps

##### Relationships and data flows
- Clients → (protocol channel: DoT/DoH/DoQ/DNSCrypt) → Edge listeners
- Edge listeners → Filter engine (profile decision) → Resolver core
- Resolver core → Upstream DNS if cache miss → Resolver → Filter engine (optional re-check) → Edge listener → Client
- CI Pipeline → regenerates stamp configs → updates Git repo → clients pull new stamp files

##### Architectural patterns and design principles
- Micro-service style: separate protocol handlers and filter/resolver logic
- Config-driven profiles: one codebase, multiple filter profiles via policy engine
- Operator-managed CI: automated stamp-file publication
- Security & privacy: DNSSEC, QNAME minimization, no logging

##### Technologies and frameworks
- DNS servers (Unbound, Knot-resolver, or custom C/Go DNS code)
- TLS/QUIC libraries, HTTP servers for DoH
- GitHub Actions for CI/CD of stamps
- Markdown-based stamp templates

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        Clients["Clients\n(Mobile/Desktop/OS Resolvers)"]:::clients
    end

    %% Network Layer
    subgraph "Network Layer"
        DoT[(DoT Listener)]:::protocol
        DoH["DoH HTTP Server"]:::protocol
        DoQ[(DoQ QUIC Server)]:::protocol
        DNSCrypt["DNSCrypt Server"]:::protocol
    end

    %% Server Layer
    subgraph "Server Layer"
        FilterEngine["Filter Engine\n(Profile Policy)"]:::filter
        BlocklistDB[(Blocklist DB)]:::db
        ResolverCore["Resolver Core\n(DNSSEC & QNAME Minimization)"]:::resolver
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        UpstreamDNS[(Upstream DNS Servers)]:::upstream
        CI["CI/CD Pipeline\n(GitHub Actions)"]:::ci
        StampRepo["Stamp Repository"]:::repo
    end

    %% Legend (optional grouping)
    classDef clients fill:#f9f,stroke:#333,color:#000;
    classDef protocol fill:#bbf,stroke:#333,color:#000;
    classDef filter fill:#fbf,stroke:#333,color:#000;
    classDef db fill:#fff2a8,stroke:#333,color:#000;
    classDef resolver fill:#bfb,stroke:#333,color:#000;
    classDef upstream fill:#ffd,stroke:#333,color:#000;
    classDef ci fill:#fdd,stroke:#333,color:#000;
    classDef repo fill:#def,stroke:#333,color:#000;

    %% Data Flows
    Clients -->|"DoT Request"| DoT
    Clients -->|"DoH Request"| DoH
    Clients -->|"DoQ Request"| DoQ
    Clients -->|"DNSCrypt Request"| DNSCrypt

    DoT -->|"validated"| FilterEngine
    DoH -->|"validated"| FilterEngine
    DoQ -->|"validated"| FilterEngine
    DNSCrypt -->|"validated"| FilterEngine

    FilterEngine -->|"filter applied"| ResolverCore
    ResolverCore -->|"cache miss"| UpstreamDNS
    UpstreamDNS -->|"response"| ResolverCore
    ResolverCore -->|"filtered response"| FilterEngine
    FilterEngine -->|"response"| DoT
    FilterEngine -->|"response"| DoH
    FilterEngine -->|"response"| DoQ
    FilterEngine -->|"response"| DNSCrypt
    DoT --> Clients
    DoH --> Clients
    DoQ --> Clients
    DNSCrypt --> Clients

    %% CI/CD Pipeline flow
    CI -->|"regenerate stamps"| StampRepo
    StampRepo -->|"clients pull stamps"| Clients

    %% Click Events
    click CI "https://github.com/bhanupratapys/dnswarden/blob/master/.github/workflows/delete_workflows.yml"
    click StampRepo "https://github.com/bhanupratapys/dnswarden/tree/master/stamps/"
    click DNSCrypt "https://github.com/bhanupratapys/dnswarden/tree/master/stamps/dnscrypt/"
    click EuropeStamp "https://github.com/bhanupratapys/dnswarden/blob/master/stamps/dnscrypt/europe-switzerland.md"
    click RelayStamp "https://github.com/bhanupratapys/dnswarden/blob/master/stamps/dnscrypt/relay.md"
    click DoHStamp "https://github.com/bhanupratapys/dnswarden/blob/master/stamps/doh/Readme.md"
    click README "https://github.com/bhanupratapys/dnswarden/blob/master/README.md"
    click LICENSE "https://github.com/bhanupratapys/dnswarden/tree/master/LICENSE"

    %% Invisible mapping nodes for stamping specifics
    EuropeStamp["Europe (Switzerland) Stamp"]:::repo
    RelayStamp["Relay Stamp"]:::repo
    DoHStamp["DoH Stamp Templates"]:::repo

    %% Positioning
    class EuropeStamp,RelayStamp,DoHStamp repo
    StampRepo --> EuropeStamp
    StampRepo --> RelayStamp
    StampRepo --> DoHStamp
```
