# 0xerr0r/blocky architecture

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

- Interactive diagram: https://gitdiagram.com/0xerr0r/blocky
- Repository: https://github.com/0xerr0r/blocky

## Overview

1. **What this repository is**
   - Blocky is a Go-based DNS proxy/ad-blocker. Its runtime job is to accept DNS requests, apply policy and enrichment, then forward to upstream resolvers or answer locally.

2. **Primary runtime entrypoints**
   - `main.go` / `main_static.go` build the single binary.
   - `cmd/` contains the CLI surface: `serve`, `query`, `lists`, `cache`, `healthcheck`, `validate`, `blocking`, `version`, and `root`.
   - This means the binary can run as a long-lived DNS service or as an admin/inspection tool.

3. **Network ingress and service boundary**
   - `server/` is the transport-facing boundary for DNS and HTTP endpoints.
   - The repo supports DNS over UDP/TCP plus HTTP-based endpoints such as DoH and a REST API.
   - `server_config_trigger*` suggests configuration changes can cause live reconfiguration/reloads without restarting the process.

4. **Core request-processing pipeline**
   - `resolver/` is the heart of the system: it is a chain of resolver components that decorate or replace each other.
   - The chain includes blocking, filtering, hosts-file handling, custom DNS overrides, conditional forwarding, FQDN-only behavior, DNS64, DNSSEC validation, ECS handling, metrics, and query logging.
   - The resolver layer is where a query is transformed from an incoming DNS request into a final answer or block response.

5. **Upstream selection and forwarding**
   - `resolver/upstream_resolver.go`, `parallel_best_resolver.go`, `strict_resolver.go`, and `upstream_tree_resolver.go` indicate multiple strategies for choosing upstream DNS servers.
   - The upstream side supports classic DNS transports and encrypted transports, including DoT/DoH and QUIC-related client code.
   - This separation makes upstream choice configurable per client group or policy rule.

6. **Blocking and policy data**
   - `lists/` handles downloading, caching, and parsing block/allow lists.
   - `lists/parsers/` supports different list formats such as plain line lists and hosts-file style entries.
   - `trie/` provides fast domain matching structures for policy enforcement, which is central to ad-blocking and allowlisting performance.

7. **Caching subsystem**
   - `cache/` abstracts cache behavior, with implementations for Redis-backed caching and in-memory string/grouped caches.
   - `cache/prefetching/` adds expiration/prefetch behavior for frequently used DNS answers.
   - This layer is used to reduce repeated upstream lookups and improve response latency.

8. **External state and coordination**
   - `redis/` provides Redis integration and pub/sub/event bridging.
   - The presence of `cache/redis.go` and `config/redis.go` shows Redis is an optional external dependency, likely for shared cache or distributed coordination.
   - The architecture is otherwise intentionally stateless; Redis is the main shared-state boundary when enabled.

9. **Configuration model**
   - `config/` defines the YAML-driven configuration schema and validation for blocking, caching, upstreams, DNSSEC, ECS, query logging, custom DNS, hosts file integration, and more.
   - `config/migration/` suggests backward-compatible config migration between versions.
   - Configuration is therefore a first-class input to the runtime pipeline, not just startup metadata.

10. **Observability and audit output**
   - `metrics/` exposes Prometheus-style metrics and ties them into the resolver/event flow.
   - `querylog/` supports multiple output backends: file, database, logger, or disabled.
   - `log/` provides request-aware logging context, so operational visibility is part of the request path.

11. **Management API and generated interfaces**
   - `api/` contains generated server/client/interface code from an OpenAPI definition.
   - This API is distinct from DNS traffic: it is the control/management surface used for inspection and administration.
   - `web/` and `docs/api/openapi.yaml` support the human-facing and machine-facing documentation for that management layer.

12. **Protocol and security helpers**
   - `resolver/dnssec/` implements DNSSEC validation primitives.
   - `util/` holds shared DNS/HTTP/TLS helpers, EDNS0 handling, ARPA parsing, and build info.
   - These are support libraries that keep protocol-specific logic out of the main pipeline.

13. **Operational packaging**
   - The repo is packaged as a containerized Go service: `Dockerfile`, `.devcontainer`, and GitHub Actions workflows cover build, release, test, and docs generation.
   - The project is designed for deployment as a single binary or container, with dashboards and docs included, but those are auxiliary to the core DNS service.

14. **How the main data flow fits together**
   - Client DNS request enters `server/` → passes through a composed resolver chain in `resolver/` → policy/list/trie checks and cache lookups happen → upstream selection/forwarding occurs if needed → response is optionally validated, rewritten, logged, and metered → final answer returns to the client.
   - Control-plane actions like config changes, API calls, and list refreshes feed into that pipeline through the config/list/cache/event subsystems.

Main entry points: [`resolver/resolver.go`](https://github.com/0xerr0r/blocky/blob/main/resolver/resolver.go) (Resolver Chain), [`config/config.go`](https://github.com/0xerr0r/blocky/blob/main/config/config.go) (Config), [`server/server.go`](https://github.com/0xerr0r/blocky/blob/main/server/server.go) (Server), [`resolver/upstream_resolver.go`](https://github.com/0xerr0r/blocky/blob/main/resolver/upstream_resolver.go) (Upstream)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_runtime["Runtime"]
  node_main["Main<br/>binary entrypoint<br/>[main.go]"]
  node_main_static["Static Main<br/>binary entrypoint<br/>[main_static.go]"]
  node_cmd_root["CLI Root<br/>command tree<br/>[root.go]"]
  node_cmd_serve["Serve<br/>dns service cmd<br/>[serve.go]"]
  node_cmd_admin["Admin Cmds<br/>utility commands<br/>[query.go]"]
end

subgraph group_g_server["Serving"]
  node_server["Server<br/>transport boundary<br/>[server.go]"]
  node_server_http["HTTP Endpoints<br/>http api<br/>[http.go]"]
  node_server_trigger["Reload Trigger<br/>config watcher"]
end

subgraph group_g_resolver["Resolution"]
  node_resolver_core["Resolver Chain<br/>pipeline core<br/>[resolver.go]"]
  node_resolver_blocking["Blocking<br/>policy resolver"]
  node_resolver_filtering["Filtering<br/>rewrite resolver"]
  node_resolver_hosts["Hosts<br/>override resolver"]
  node_resolver_upstream["Upstream<br/>forwarding resolver"]
  node_resolver_strategies["Selection<br/>upstream strategy"]
  node_resolver_dnssec["DNSSEC<br/>validation resolver<br/>[dnssec_resolver.go]"]
  node_resolver_ecs["ECS<br/>client-subnet resolver<br/>[ecs_resolver.go]"]
end

subgraph group_g_data["Policy & State"]
  node_lists["Lists<br/>policy data<br/>[downloader.go]"]
  node_trie["Trie<br/>match index<br/>[trie.go]"]
  node_cache["Cache<br/>[cache_interface.go]"]
  node_config["Config<br/>[config.go]"]
  node_redis["Redis<br/>shared state<br/>[redis.go]"]
end

subgraph group_g_obs["Observability"]
  node_resolver_metrics["Metrics<br/>telemetry resolver"]
  node_resolver_logging["Query Log<br/>audit resolver"]
  node_metrics["Metrics Export<br/>prometheus endpoint<br/>[metrics.go]"]
  node_querylog["Query Log Sink<br/>audit sinks<br/>[writer.go]"]
end

subgraph group_g_admin["Admin/API"]
  node_api["Management API<br/>control api<br/>[api_server.gen.go]"]
  node_web["Web UI<br/>documentation ui<br/>[index.go]"]
end

node_main -->|"boots"| node_cmd_root
node_main_static -->|"boots"| node_cmd_root
node_cmd_root -->|"dispatches"| node_cmd_serve
node_cmd_root -->|"dispatches"| node_cmd_admin
node_cmd_serve -->|"starts"| node_server
node_server -->|"exposes"| node_server_http
node_server -->|"watches"| node_server_trigger
node_server -->|"routes to"| node_resolver_core
node_resolver_core -->|"applies"| node_resolver_blocking
node_resolver_core -->|"applies"| node_resolver_filtering
node_resolver_core -->|"applies"| node_resolver_hosts
node_resolver_core -->|"applies"| node_resolver_dnssec
node_resolver_core -->|"applies"| node_resolver_ecs
node_resolver_core -->|"observes"| node_resolver_metrics
node_resolver_core -->|"audits"| node_resolver_logging
node_resolver_blocking -->|"uses"| node_lists
node_resolver_blocking -->|"matches"| node_trie
node_resolver_filtering -->|"reads"| node_config
node_resolver_hosts -->|"reads"| node_config
node_resolver_dnssec -->|"reads"| node_config
node_resolver_upstream -->|"selects"| node_resolver_strategies
node_resolver_upstream -->|"consults"| node_cache
node_resolver_upstream -->|"optionally uses"| node_redis
node_cache -->|"backed by"| node_redis
node_config -->|"configures"| node_lists
node_config -->|"configures"| node_cache
node_config -->|"configures"| node_resolver_upstream
node_config -->|"configures"| node_server
node_api -->|"controls"| node_config
node_web -->|"documents"| node_api
node_metrics -->|"exports"| node_resolver_metrics
node_querylog -->|"sinks"| node_resolver_logging

click node_main "https://github.com/0xerr0r/blocky/blob/main/main.go"
click node_main_static "https://github.com/0xerr0r/blocky/blob/main/main_static.go"
click node_cmd_root "https://github.com/0xerr0r/blocky/blob/main/cmd/root.go"
click node_cmd_serve "https://github.com/0xerr0r/blocky/blob/main/cmd/serve.go"
click node_cmd_admin "https://github.com/0xerr0r/blocky/blob/main/cmd/query.go"
click node_server "https://github.com/0xerr0r/blocky/blob/main/server/server.go"
click node_server_http "https://github.com/0xerr0r/blocky/blob/main/server/http.go"
click node_server_trigger "https://github.com/0xerr0r/blocky/blob/main/server/server_config_trigger.go"
click node_resolver_core "https://github.com/0xerr0r/blocky/blob/main/resolver/resolver.go"
click node_resolver_blocking "https://github.com/0xerr0r/blocky/blob/main/resolver/blocking_resolver.go"
click node_resolver_filtering "https://github.com/0xerr0r/blocky/blob/main/resolver/filtering_resolver.go"
click node_resolver_hosts "https://github.com/0xerr0r/blocky/blob/main/resolver/hosts_file_resolver.go"
click node_resolver_upstream "https://github.com/0xerr0r/blocky/blob/main/resolver/upstream_resolver.go"
click node_resolver_strategies "https://github.com/0xerr0r/blocky/blob/main/resolver/parallel_best_resolver.go"
click node_resolver_dnssec "https://github.com/0xerr0r/blocky/blob/main/resolver/dnssec_resolver.go"
click node_resolver_ecs "https://github.com/0xerr0r/blocky/blob/main/resolver/ecs_resolver.go"
click node_resolver_metrics "https://github.com/0xerr0r/blocky/blob/main/resolver/metrics_resolver.go"
click node_resolver_logging "https://github.com/0xerr0r/blocky/blob/main/resolver/query_logging_resolver.go"
click node_lists "https://github.com/0xerr0r/blocky/blob/main/lists/downloader.go"
click node_trie "https://github.com/0xerr0r/blocky/blob/main/trie/trie.go"
click node_cache "https://github.com/0xerr0r/blocky/blob/main/cache/cache_interface.go"
click node_config "https://github.com/0xerr0r/blocky/blob/main/config/config.go"
click node_redis "https://github.com/0xerr0r/blocky/blob/main/redis/redis.go"
click node_api "https://github.com/0xerr0r/blocky/blob/main/api/api_server.gen.go"
click node_web "https://github.com/0xerr0r/blocky/blob/main/web/index.go"
click node_metrics "https://github.com/0xerr0r/blocky/blob/main/metrics/metrics.go"
click node_querylog "https://github.com/0xerr0r/blocky/blob/main/querylog/writer.go"

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_main,node_main_static,node_cmd_root,node_cmd_serve,node_cmd_admin toneBlue
class node_server,node_server_http,node_server_trigger toneAmber
class node_resolver_core,node_resolver_blocking,node_resolver_filtering,node_resolver_hosts,node_resolver_upstream,node_resolver_strategies,node_resolver_dnssec,node_resolver_ecs toneMint
class node_lists,node_trie,node_cache,node_config,node_redis toneRose
class node_resolver_metrics,node_resolver_logging,node_metrics,node_querylog toneIndigo
class node_api,node_web toneTeal
```

## Components

### Runtime

CLI entrypoints and process startup

- [Main](https://github.com/0xerr0r/blocky/blob/main/main.go): binary entrypoint · Builds the Blocky executable · `main.go`
- [Static Main](https://github.com/0xerr0r/blocky/blob/main/main_static.go): binary entrypoint · Alternate build entrypoint for static packaging · `main_static.go`
- [CLI Root](https://github.com/0xerr0r/blocky/blob/main/cmd/root.go): command tree · Shared command wiring for subcommands · `cmd/root.go`
- [Serve](https://github.com/0xerr0r/blocky/blob/main/cmd/serve.go): dns service cmd · Starts the long-lived DNS/HTTP service · `cmd/serve.go`
- [Admin Cmds](https://github.com/0xerr0r/blocky/blob/main/cmd/query.go): utility commands · Inspection and maintenance commands such as query, lists, cache, healthcheck, validate, blocking, and version · `cmd/query.go`

### Serving

DNS and HTTP ingress boundaries

- [Server](https://github.com/0xerr0r/blocky/blob/main/server/server.go): transport boundary · DNS and HTTP listener boundary · `server/server.go`
- [HTTP Endpoints](https://github.com/0xerr0r/blocky/blob/main/server/http.go): http api · DoH and REST-facing HTTP handling · `server/http.go`
- [Reload Trigger](https://github.com/0xerr0r/blocky/blob/main/server/server_config_trigger.go): config watcher · Triggers live reconfiguration on config changes · `server/server_config_trigger.go`

### Resolution

Composed request-processing pipeline

- [Resolver Chain](https://github.com/0xerr0r/blocky/blob/main/resolver/resolver.go): pipeline core · Composed resolver pipeline that transforms each DNS request · `resolver/resolver.go`
- [Blocking](https://github.com/0xerr0r/blocky/blob/main/resolver/blocking_resolver.go): policy resolver · Applies allow/block policy before forwarding · `resolver/blocking_resolver.go`
- [Filtering](https://github.com/0xerr0r/blocky/blob/main/resolver/filtering_resolver.go): rewrite resolver · Applies domain and qtype filtering rules · `resolver/filtering_resolver.go`
- [Hosts](https://github.com/0xerr0r/blocky/blob/main/resolver/hosts_file_resolver.go): override resolver · Answers from hosts-file style overrides · `resolver/hosts_file_resolver.go`
- [Upstream](https://github.com/0xerr0r/blocky/blob/main/resolver/upstream_resolver.go): forwarding resolver · Forwards queries to selected upstream resolvers · `resolver/upstream_resolver.go`
- [Selection](https://github.com/0xerr0r/blocky/blob/main/resolver/parallel_best_resolver.go): upstream strategy · Parallel, strict, and tree-based upstream selection strategies · `resolver/parallel_best_resolver.go`
- [DNSSEC](https://github.com/0xerr0r/blocky/blob/main/resolver/dnssec_resolver.go): validation resolver · Validates DNSSEC chains and responses · `resolver/dnssec_resolver.go`
- [ECS](https://github.com/0xerr0r/blocky/blob/main/resolver/ecs_resolver.go): client-subnet resolver · Handles EDNS client subnet behavior · `resolver/ecs_resolver.go`

### Policy & State

Lists, cache, config, and shared state

- [Lists](https://github.com/0xerr0r/blocky/blob/main/lists/downloader.go): policy data · Downloads, caches, and parses block/allow lists · `lists/downloader.go`
- [Trie](https://github.com/0xerr0r/blocky/blob/main/trie/trie.go): match index · Fast domain matching structure for policy enforcement · `trie/trie.go`
- [Cache](https://github.com/0xerr0r/blocky/blob/main/cache/cache_interface.go): answer cache · In-memory and Redis-backed DNS cache layer · `cache/cache_interface.go`
- [Config](https://github.com/0xerr0r/blocky/blob/main/config/config.go): runtime config · YAML configuration schema, validation, and migration · `config/config.go`
- [Redis](https://github.com/0xerr0r/blocky/blob/main/redis/redis.go): shared state · Optional Redis integration for cache and event coordination · `redis/redis.go`

### Observability

Logging, metrics, and query audit

- [Metrics](https://github.com/0xerr0r/blocky/blob/main/resolver/metrics_resolver.go): telemetry resolver · Emits request metrics from the resolution path · `resolver/metrics_resolver.go`
- [Query Log](https://github.com/0xerr0r/blocky/blob/main/resolver/query_logging_resolver.go): audit resolver · Writes per-query audit records · `resolver/query_logging_resolver.go`
- [Metrics Export](https://github.com/0xerr0r/blocky/blob/main/metrics/metrics.go): prometheus endpoint · Prometheus-style metrics exposure · `metrics/metrics.go`
- [Query Log Sink](https://github.com/0xerr0r/blocky/blob/main/querylog/writer.go): audit sinks · File, database, logger, or disabled query-log writers · `querylog/writer.go`

### Admin/API

Management API and docs

- [Management API](https://github.com/0xerr0r/blocky/blob/main/api/api_server.gen.go): control api · Generated API surface for inspection and administration · `api/api_server.gen.go`
- [Web UI](https://github.com/0xerr0r/blocky/blob/main/web/index.go): documentation ui · Human-facing API documentation and static assets · `web/index.go`

## Connections

- Main → CLI Root: boots · Main binary initializes the CLI command tree
- Static Main → CLI Root: boots · Static build uses the same command tree
- CLI Root → Serve: dispatches · Root CLI selects the service command
- CLI Root → Admin Cmds: dispatches · Root CLI selects admin and inspection commands
- Serve → Server: starts · Serve command starts the network boundary
- Server → HTTP Endpoints: exposes · Server binds HTTP-based endpoints such as DoH and API
- Server → Reload Trigger: watches · Server reacts to configuration changes
- Server → Resolver Chain: routes to · Incoming DNS requests enter the resolver pipeline
- Resolver Chain → Blocking: applies · Core pipeline evaluates blocking policy
- Resolver Chain → Filtering: applies · Core pipeline applies request filtering
- Resolver Chain → Hosts: applies · Core pipeline can answer from hosts overrides
- Resolver Chain → DNSSEC: applies · Core pipeline can validate DNSSEC
- Resolver Chain → ECS: applies · Core pipeline can add or honor ECS behavior
- Resolver Chain → Metrics: observes · Core pipeline emits request metrics
- Resolver Chain → Query Log: audits · Core pipeline writes query logs
- Blocking → Lists: uses · Blocking policy is built from configured lists
- Blocking → Trie: matches · Policy checks use domain matching structures
- Filtering → Config: reads · Filtering rules come from configuration
- Hosts → Config: reads · Hosts overrides are configuration-driven
- DNSSEC → Config: reads · DNSSEC validation is enabled and tuned by config
- Upstream → Selection: selects · Forwarding delegates upstream choice to strategies
- Upstream → Cache: consults · Forwarding can reuse cached answers
- Upstream → Redis: optionally uses · Shared cache or coordination can be backed by Redis
- Cache → Redis: backed by · Cache layer can be implemented on Redis
- Config → Lists: configures · Configuration defines list sources and policy behavior
- Config → Cache: configures · Configuration defines cache behavior
- Config → Upstream: configures · Configuration defines upstream selection and forwarding
- Config → Server: configures · Configuration defines serving endpoints and listeners
- Management API → Config: controls · Management API can inspect or change runtime configuration
- Web UI → Management API: documents · Web assets present the management API documentation
- Metrics Export → Metrics: exports · Metrics subsystem exposes resolver-derived telemetry
- Query Log Sink → Query Log: sinks · Query logging resolver writes into configured sinks
