# m13253/dns-over-https architecture

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

- Interactive diagram: https://gitdiagram.com/m13253/dns-over-https
- Repository: https://github.com/m13253/dns-over-https

## Overview

This repository provides a local DNS-over-HTTPS client and an HTTP-facing DoH server. The client accepts DNS queries, chooses a configured DoH upstream, and supports Google JSON and IETF wire-format exchanges; the server accepts DoH requests and forwards DNS queries to recursive DNS servers. The README documents configurable upstream selection, proxy deployment, and both protocols. The sampled excerpts show client dispatch and server DNS exchanges, but not all server routing or startup internals, so those connections are omitted where unverified.

Main entry points: [`doh-client/client.go`](https://github.com/m13253/dns-over-https/blob/master/doh-client/client.go) (DNS listener), [`json-dns`](https://github.com/m13253/dns-over-https/tree/master/json-dns) (DNS JSON codec), [`doh-client/google.go`](https://github.com/m13253/dns-over-https/blob/master/doh-client/google.go) (Google exchange), [`doh-client/ietf.go`](https://github.com/m13253/dns-over-https/blob/master/doh-client/ietf.go) (IETF exchange)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["DoH client"]
  node_client_entry["Client startup<br/>[main.go]"]
  node_client_config["Client config<br/>[config.go]"]
  node_client_core["DNS listener<br/>[client.go]"]
  node_client_google["Google exchange<br/>[google.go]"]
  node_client_ietf["IETF exchange<br/>[ietf.go]"]
end

subgraph group_selection["Upstream selection"]
  node_selectors["Selector strategies"]
end

subgraph group_server["DoH server"]
  node_server_entry["Server startup<br/>[main.go]"]
  node_server_config["Server config<br/>[config.go]"]
  node_server_core["HTTP DNS server<br/>[server.go]"]
  node_server_google["Google request format<br/>[google.go]"]
  node_server_ietf["IETF request format<br/>[ietf.go]"]
end

subgraph group_shared["DNS formats"]
  node_json_dns["DNS JSON codec"]
end

node_dns_app(("DNS application"))
node_doh_upstream(("DoH upstream"))
node_recursive_dns(("Recursive DNS"))

node_dns_app -->|"sends DNS"| node_client_core
node_client_entry -->|"loads config"| node_client_config
node_client_entry -->|"starts client"| node_client_core
node_client_core -->|"selects upstream"| node_selectors
node_client_core -->|"dispatches JSON"| node_client_google
node_client_core -->|"dispatches wire"| node_client_ietf
node_client_google -->|"sends HTTP query"| node_doh_upstream
node_client_ietf -->|"sends HTTP query"| node_doh_upstream
node_client_google -->|"decodes response"| node_json_dns
node_client_ietf -->|"uses DNS codec"| node_json_dns
node_server_entry -->|"loads config"| node_server_config
node_server_entry -->|"starts server"| node_server_core
node_server_core -->|"exchanges DNS"| node_recursive_dns
node_server_core -->|"uses IP checks"| node_json_dns
node_server_ietf -->|"uses DNS helpers"| node_json_dns
node_server_google -->|"uses DNS helpers"| node_json_dns

click node_client_entry "https://github.com/m13253/dns-over-https/blob/master/doh-client/main.go"
click node_client_config "https://github.com/m13253/dns-over-https/blob/master/doh-client/config/config.go"
click node_client_core "https://github.com/m13253/dns-over-https/blob/master/doh-client/client.go"
click node_client_google "https://github.com/m13253/dns-over-https/blob/master/doh-client/google.go"
click node_client_ietf "https://github.com/m13253/dns-over-https/blob/master/doh-client/ietf.go"
click node_selectors "https://github.com/m13253/dns-over-https/tree/master/doh-client/selector"
click node_server_entry "https://github.com/m13253/dns-over-https/blob/master/doh-server/main.go"
click node_server_config "https://github.com/m13253/dns-over-https/blob/master/doh-server/config.go"
click node_server_core "https://github.com/m13253/dns-over-https/blob/master/doh-server/server.go"
click node_server_google "https://github.com/m13253/dns-over-https/blob/master/doh-server/google.go"
click node_server_ietf "https://github.com/m13253/dns-over-https/blob/master/doh-server/ietf.go"
click node_json_dns "https://github.com/m13253/dns-over-https/tree/master/json-dns"

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_client_entry,node_client_config,node_client_core,node_client_google,node_client_ietf toneBlue
class node_selectors toneAmber
class node_server_entry,node_server_config,node_server_core,node_server_google,node_server_ietf toneMint
class node_json_dns toneRose
class node_dns_app,node_doh_upstream,node_recursive_dns toneIndigo
```

## Components

### DoH client

- [Client startup](https://github.com/m13253/dns-over-https/blob/master/doh-client/main.go): `doh-client/main.go`
- [Client config](https://github.com/m13253/dns-over-https/blob/master/doh-client/config/config.go): `doh-client/config/config.go`
- [DNS listener](https://github.com/m13253/dns-over-https/blob/master/doh-client/client.go): `doh-client/client.go`
- [Google exchange](https://github.com/m13253/dns-over-https/blob/master/doh-client/google.go): `doh-client/google.go`
- [IETF exchange](https://github.com/m13253/dns-over-https/blob/master/doh-client/ietf.go): `doh-client/ietf.go`

### Upstream selection

- [Selector strategies](https://github.com/m13253/dns-over-https/tree/master/doh-client/selector): `doh-client/selector`

### DoH server

- [Server startup](https://github.com/m13253/dns-over-https/blob/master/doh-server/main.go): `doh-server/main.go`
- [Server config](https://github.com/m13253/dns-over-https/blob/master/doh-server/config.go): `doh-server/config.go`
- [HTTP DNS server](https://github.com/m13253/dns-over-https/blob/master/doh-server/server.go): `doh-server/server.go`
- [Google request format](https://github.com/m13253/dns-over-https/blob/master/doh-server/google.go): `doh-server/google.go`
- [IETF request format](https://github.com/m13253/dns-over-https/blob/master/doh-server/ietf.go): `doh-server/ietf.go`

### DNS formats

- [DNS JSON codec](https://github.com/m13253/dns-over-https/tree/master/json-dns): `json-dns`

### Other components

- **DNS application**
- **DoH upstream**
- **Recursive DNS**

## Connections

- DNS application → DNS listener: sends DNS (evidence: `Readme.md`)
- Client startup → Client config: loads config (evidence: `doh-client/main.go`)
- Client startup → DNS listener: starts client (evidence: `doh-client/main.go`)
- DNS listener → Selector strategies: selects upstream (evidence: `doh-client/client.go`)
- DNS listener → Google exchange: dispatches JSON (evidence: `doh-client/client.go`)
- DNS listener → IETF exchange: dispatches wire (evidence: `doh-client/client.go`)
- Google exchange → DoH upstream: sends HTTP query (evidence: `doh-client/google.go`)
- IETF exchange → DoH upstream: sends HTTP query (evidence: `doh-client/ietf.go`)
- Google exchange → DNS JSON codec: decodes response (evidence: `doh-client/google.go`)
- IETF exchange → DNS JSON codec: uses DNS codec (evidence: `doh-client/ietf.go`)
- Server startup → Server config: loads config (evidence: `doh-server/main.go`)
- Server startup → HTTP DNS server: starts server (evidence: `doh-server/main.go`)
- HTTP DNS server → Recursive DNS: exchanges DNS (evidence: `doh-server/server.go`)
- HTTP DNS server → DNS JSON codec: uses IP checks (evidence: `doh-server/server.go`)
- IETF request format → DNS JSON codec: uses DNS helpers (evidence: `doh-server/ietf.go`)
- Google request format → DNS JSON codec: uses DNS helpers (evidence: `doh-server/google.go`)
