# dnscrypt/dnscrypt-proxy architecture

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

- Interactive diagram: https://gitdiagram.com/dnscrypt/dnscrypt-proxy
- Repository: https://github.com/dnscrypt/dnscrypt-proxy

## Overview

dnscrypt-proxy is a configurable encrypted DNS proxy. A client query enters the proxy, passes through query processing and configured policy plugins, is resolved through an encrypted DNS protocol and selected resolver, then returns to the client; logging and monitoring expose activity. The README documents additional filtering, resolver updates, load balancing, anonymization, and local DoH capabilities. Some subsystem links are documented only at the product level, so those edges are dashed; source-level edges are limited to the excerpts shown.

Main entry points: [`dnscrypt-proxy/query_processing.go`](https://github.com/dnscrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/query_processing.go) (Query Processing), [`dnscrypt-proxy/plugins.go`](https://github.com/dnscrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/plugins.go) (Plugin Dispatch), [`dnscrypt-proxy/proxy.go`](https://github.com/dnscrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/proxy.go) (DNS Proxy), [`dnscrypt-proxy/main.go`](https://github.com/dnscrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/main.go) (Application Startup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Proxy Runtime"]
  node_app["Application Startup<br/>[main.go]"]
  node_config["Configuration<br/>[config_loader.go]"]
  node_proxy["DNS Proxy<br/>[proxy.go]"]
  node_query["Query Processing"]
end

subgraph group_protocols["Encrypted DNS"]
  node_transport["HTTP Transport<br/>[xtransport.go]"]
  node_dnscrypt["DNSCrypt Crypto<br/>[crypto.go]"]
  node_pq["Post-Quantum<br/>[pq.go]"]
  node_odoh["Oblivious DoH<br/>[oblivious_doh.go]"]
  node_localdoh["Local DoH<br/>[local-doh.go]"]
end

subgraph group_policy["Query Policy"]
  node_plugins["Plugin Dispatch<br/>[plugins.go]"]
  node_cloak["Cloaking Rules<br/>[plugin_cloak.go]"]
  node_forward["Resolver Forwarding<br/>[plugin_forward.go]"]
  node_filters["DNS Filtering"]
  node_cache[("DNS Cache<br/>[plugin_cache.go]")]
  node_scheduling["Time Filtering<br/>[time_ranges.go]"]
end

subgraph group_discovery["Resolver Discovery"]
  node_servers["Resolver Selection<br/>[serversInfo.go]"]
  node_sources["Resolver Sources<br/>[sources.go]"]
  node_blocklistgen["Blocklist Generator"]
end

subgraph group_observability["Monitoring"]
  node_querylog["Query Logging"]
  node_monitor["Monitoring UI<br/>[monitoring_ui.go]"]
  node_dashboard["Dashboard Client<br/>[monitoring.js]"]
end

node_client(("DNS Client"))

node_client -.->|"sends query"| node_proxy
node_app -->|"loads config"| node_config
node_app -->|"starts proxy"| node_proxy
node_proxy -.->|"processes query"| node_query
node_query -->|"exchanges queries"| node_proxy
node_query -->|"applies logging"| node_plugins
node_plugins -.->|"dispatches filters"| node_filters
node_plugins -.->|"dispatches cloaking"| node_cloak
node_plugins -.->|"dispatches cache"| node_cache
node_plugins -.->|"applies schedules"| node_scheduling
node_plugins -.->|"forwards queries"| node_forward
node_forward -.->|"selects resolver"| node_servers
node_servers -.->|"updates resolver lists"| node_sources
node_blocklistgen -.->|"generates blocklists"| node_filters
node_query -.->|"sends DoH"| node_transport
node_query -.->|"encrypts DNSCrypt"| node_dnscrypt
node_dnscrypt -.->|"supports PQ"| node_pq
node_query -->|"handles ODoH"| node_odoh
node_query -.->|"serves local DoH"| node_localdoh
node_proxy -.->|"records queries"| node_querylog
node_proxy -.->|"exposes monitoring"| node_monitor
node_dashboard -.->|"requests metrics"| node_monitor

click node_app "https://github.com/dnscrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/main.go"
click node_config "https://github.com/dnscrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/config_loader.go"
click node_proxy "https://github.com/dnscrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/proxy.go"
click node_query "https://github.com/dnscrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/query_processing.go"
click node_transport "https://github.com/dnscrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/xtransport.go"
click node_dnscrypt "https://github.com/dnscrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/crypto.go"
click node_pq "https://github.com/dnscrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/pq.go"
click node_odoh "https://github.com/dnscrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/oblivious_doh.go"
click node_localdoh "https://github.com/dnscrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/local-doh.go"
click node_plugins "https://github.com/dnscrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/plugins.go"
click node_cloak "https://github.com/dnscrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/plugin_cloak.go"
click node_forward "https://github.com/dnscrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/plugin_forward.go"
click node_filters "https://github.com/dnscrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/plugin_block_name.go"
click node_cache "https://github.com/dnscrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/plugin_cache.go"
click node_scheduling "https://github.com/dnscrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/time_ranges.go"
click node_servers "https://github.com/dnscrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/serversInfo.go"
click node_sources "https://github.com/dnscrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/sources.go"
click node_blocklistgen "https://github.com/dnscrypt/dnscrypt-proxy/blob/master/utils/generate-domains-blocklist/generate-domains-blocklist.py"
click node_querylog "https://github.com/dnscrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/plugin_query_log.go"
click node_monitor "https://github.com/dnscrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/monitoring_ui.go"
click node_dashboard "https://github.com/dnscrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/static/js/monitoring.js"

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_app,node_config,node_proxy,node_query,node_client toneBlue
class node_transport,node_dnscrypt,node_pq,node_odoh,node_localdoh toneAmber
class node_plugins,node_cloak,node_forward,node_filters,node_cache,node_scheduling toneMint
class node_servers,node_sources,node_blocklistgen toneRose
class node_querylog,node_monitor,node_dashboard toneIndigo
```

## Components

### Proxy Runtime

- [Application Startup](https://github.com/dnscrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/main.go): `dnscrypt-proxy/main.go`
- [Configuration](https://github.com/dnscrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/config_loader.go): `dnscrypt-proxy/config_loader.go`
- [DNS Proxy](https://github.com/dnscrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/proxy.go): `dnscrypt-proxy/proxy.go`
- [Query Processing](https://github.com/dnscrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/query_processing.go): `dnscrypt-proxy/query_processing.go`

### Encrypted DNS

- [HTTP Transport](https://github.com/dnscrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/xtransport.go): `dnscrypt-proxy/xtransport.go`
- [DNSCrypt Crypto](https://github.com/dnscrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/crypto.go): `dnscrypt-proxy/crypto.go`
- [Post-Quantum](https://github.com/dnscrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/pq.go): `dnscrypt-proxy/pq.go`
- [Oblivious DoH](https://github.com/dnscrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/oblivious_doh.go): `dnscrypt-proxy/oblivious_doh.go`
- [Local DoH](https://github.com/dnscrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/local-doh.go): `dnscrypt-proxy/local-doh.go`

### Query Policy

- [Plugin Dispatch](https://github.com/dnscrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/plugins.go): `dnscrypt-proxy/plugins.go`
- [Cloaking Rules](https://github.com/dnscrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/plugin_cloak.go): `dnscrypt-proxy/plugin_cloak.go`
- [Resolver Forwarding](https://github.com/dnscrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/plugin_forward.go): `dnscrypt-proxy/plugin_forward.go`
- [DNS Filtering](https://github.com/dnscrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/plugin_block_name.go): `dnscrypt-proxy/plugin_block_name.go`
- [DNS Cache](https://github.com/dnscrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/plugin_cache.go): `dnscrypt-proxy/plugin_cache.go`
- [Time Filtering](https://github.com/dnscrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/time_ranges.go): `dnscrypt-proxy/time_ranges.go`

### Resolver Discovery

- [Resolver Selection](https://github.com/dnscrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/serversInfo.go): `dnscrypt-proxy/serversInfo.go`
- [Resolver Sources](https://github.com/dnscrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/sources.go): `dnscrypt-proxy/sources.go`
- [Blocklist Generator](https://github.com/dnscrypt/dnscrypt-proxy/blob/master/utils/generate-domains-blocklist/generate-domains-blocklist.py): `utils/generate-domains-blocklist/generate-domains-blocklist.py`

### Monitoring

- [Query Logging](https://github.com/dnscrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/plugin_query_log.go): `dnscrypt-proxy/plugin_query_log.go`
- [Monitoring UI](https://github.com/dnscrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/monitoring_ui.go): `dnscrypt-proxy/monitoring_ui.go`
- [Dashboard Client](https://github.com/dnscrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/static/js/monitoring.js): `dnscrypt-proxy/static/js/monitoring.js`

### Other components

- **DNS Client**

## Connections

- DNS Client → DNS Proxy: sends query
- Application Startup → Configuration: loads config (evidence: `dnscrypt-proxy/main.go`)
- Application Startup → DNS Proxy: starts proxy (evidence: `dnscrypt-proxy/main.go`)
- DNS Proxy → Query Processing: processes query
- Query Processing → DNS Proxy: exchanges queries (evidence: `dnscrypt-proxy/query_processing.go`)
- Query Processing → Plugin Dispatch: applies logging (evidence: `dnscrypt-proxy/query_processing.go`)
- Plugin Dispatch → DNS Filtering: dispatches filters
- Plugin Dispatch → Cloaking Rules: dispatches cloaking
- Plugin Dispatch → DNS Cache: dispatches cache
- Plugin Dispatch → Time Filtering: applies schedules
- Plugin Dispatch → Resolver Forwarding: forwards queries
- Resolver Forwarding → Resolver Selection: selects resolver
- Resolver Selection → Resolver Sources: updates resolver lists
- Blocklist Generator → DNS Filtering: generates blocklists
- Query Processing → HTTP Transport: sends DoH
- Query Processing → DNSCrypt Crypto: encrypts DNSCrypt
- DNSCrypt Crypto → Post-Quantum: supports PQ
- Query Processing → Oblivious DoH: handles ODoH (evidence: `dnscrypt-proxy/query_processing.go`)
- Query Processing → Local DoH: serves local DoH
- DNS Proxy → Query Logging: records queries
- DNS Proxy → Monitoring UI: exposes monitoring
- Dashboard Client → Monitoring UI: requests metrics
