# dnsimple/erldns architecture

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

- Interactive diagram: https://gitdiagram.com/dnsimple/erldns
- Repository: https://github.com/dnsimple/erldns

## Overview

ErlDNS is an authoritative DNS server. Its documented main workflow accepts DNS requests through listeners, processes them in the query pipeline, and uses loaded, cached zones to serve responses. The repository also provides runtime zone administration and telemetry instrumentation. The README documents subsystem responsibilities, but no source excerpts were provided, so internal call wiring beyond those documented relationships is omitted.

Main entry points: [`src/listeners/erldns_listeners.erl`](https://github.com/dnsimple/erldns/blob/main/src/listeners/erldns_listeners.erl) (DNS listeners), [`src/admin/erldns_admin.erl`](https://github.com/dnsimple/erldns/blob/main/src/admin/erldns_admin.erl) (Admin API), [`src/pipes/erldns_pipeline.erl`](https://github.com/dnsimple/erldns/blob/main/src/pipes/erldns_pipeline.erl) (Query pipeline), [`src/zones/load/erldns_zone_loader.erl`](https://github.com/dnsimple/erldns/blob/main/src/zones/load/erldns_zone_loader.erl) (Zone loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_network["DNS listeners"]
  node_listeners["DNS listeners"]
  node_udp["UDP transport"]
  node_tcp["TCP transport"]
end

subgraph group_query["Query processing"]
  node_pipeline["Query pipeline"]
  node_resolver["DNS resolver"]
  node_recursive["Recursive resolver"]
  node_questions["Question handling"]
  node_dnssec["DNSSEC<br/>[erldns_dnssec.erl]"]
  node_edns["EDNS processing<br/>[erldns_edns.erl]"]
  node_throttle["Query throttling"]
  node_packet_cache["Packet cache"]
end

subgraph group_zones["Zone management"]
  node_zone_load["Zone loader"]
  node_zone_files["Zone JSON files"]
  node_zones["Zone service<br/>[erldns_zones.erl]"]
  node_zone_cache[("Zone cache")]
end

subgraph group_admin["Administration"]
  node_admin["Admin API<br/>[erldns_admin.erl]"]
  node_admin_zones["Zone endpoints"]
  node_admin_records["Record endpoints"]
end

node_dns_client(("DNS client"))
node_admin_client(("Admin API client"))
node_telemetry["Telemetry"]

node_dns_client -->|"sends DNS queries"| node_listeners
node_listeners -->|"accepts UDP"| node_udp
node_listeners -->|"accepts TCP"| node_tcp
node_listeners -->|"dispatches queries"| node_pipeline
node_zone_files -->|"provides zone data"| node_zone_load
node_zone_load -->|"loads zones"| node_zones
node_admin_client -->|"sends HTTP requests"| node_admin
node_admin -->|"routes requests"| node_admin_zones
node_admin -->|"routes requests"| node_admin_records
node_pipeline -->|"emits events"| node_telemetry
node_listeners -->|"emits events"| node_telemetry

click node_listeners "https://github.com/dnsimple/erldns/blob/main/src/listeners/erldns_listeners.erl"
click node_udp "https://github.com/dnsimple/erldns/blob/main/src/listeners/udp/erldns_proto_udp.erl"
click node_tcp "https://github.com/dnsimple/erldns/blob/main/src/listeners/tcp/erldns_proto_tcp.erl"
click node_pipeline "https://github.com/dnsimple/erldns/blob/main/src/pipes/erldns_pipeline.erl"
click node_resolver "https://github.com/dnsimple/erldns/blob/main/src/pipes/erldns_resolver.erl"
click node_recursive "https://github.com/dnsimple/erldns/blob/main/src/pipes/erldns_resolver_recursive.erl"
click node_questions "https://github.com/dnsimple/erldns/blob/main/src/pipes/erldns_questions.erl"
click node_dnssec "https://github.com/dnsimple/erldns/blob/main/src/pipes/erldns_dnssec.erl"
click node_edns "https://github.com/dnsimple/erldns/blob/main/src/erldns_edns.erl"
click node_throttle "https://github.com/dnsimple/erldns/blob/main/src/pipes/erldns_query_throttle.erl"
click node_packet_cache "https://github.com/dnsimple/erldns/blob/main/src/pipes/erldns_packet_cache.erl"
click node_zone_load "https://github.com/dnsimple/erldns/blob/main/src/zones/load/erldns_zone_loader.erl"
click node_zone_files "https://github.com/dnsimple/erldns/tree/main/priv/zones"
click node_zones "https://github.com/dnsimple/erldns/blob/main/src/zones/erldns_zones.erl"
click node_zone_cache "https://github.com/dnsimple/erldns/blob/main/src/zones/erldns_zone_cache.erl"
click node_admin "https://github.com/dnsimple/erldns/blob/main/src/admin/erldns_admin.erl"
click node_admin_zones "https://github.com/dnsimple/erldns/blob/main/src/admin/erldns_admin_zone_handler.erl"
click node_admin_records "https://github.com/dnsimple/erldns/blob/main/src/admin/erldns_admin_zone_records_handler.erl"

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_listeners,node_udp,node_tcp,node_dns_client,node_admin_client toneBlue
class node_pipeline,node_resolver,node_recursive,node_questions,node_dnssec,node_edns,node_throttle,node_packet_cache toneAmber
class node_zone_load,node_zone_files,node_zones,node_zone_cache toneMint
class node_admin,node_admin_zones,node_admin_records toneRose
class node_telemetry toneIndigo
```

## Components

### DNS listeners

- [DNS listeners](https://github.com/dnsimple/erldns/blob/main/src/listeners/erldns_listeners.erl): `src/listeners/erldns_listeners.erl`
- [UDP transport](https://github.com/dnsimple/erldns/blob/main/src/listeners/udp/erldns_proto_udp.erl): `src/listeners/udp/erldns_proto_udp.erl`
- [TCP transport](https://github.com/dnsimple/erldns/blob/main/src/listeners/tcp/erldns_proto_tcp.erl): `src/listeners/tcp/erldns_proto_tcp.erl`

### Query processing

- [Query pipeline](https://github.com/dnsimple/erldns/blob/main/src/pipes/erldns_pipeline.erl): `src/pipes/erldns_pipeline.erl`
- [DNS resolver](https://github.com/dnsimple/erldns/blob/main/src/pipes/erldns_resolver.erl): `src/pipes/erldns_resolver.erl`
- [Recursive resolver](https://github.com/dnsimple/erldns/blob/main/src/pipes/erldns_resolver_recursive.erl): `src/pipes/erldns_resolver_recursive.erl`
- [Question handling](https://github.com/dnsimple/erldns/blob/main/src/pipes/erldns_questions.erl): `src/pipes/erldns_questions.erl`
- [DNSSEC](https://github.com/dnsimple/erldns/blob/main/src/pipes/erldns_dnssec.erl): `src/pipes/erldns_dnssec.erl`
- [EDNS processing](https://github.com/dnsimple/erldns/blob/main/src/erldns_edns.erl): `src/erldns_edns.erl`
- [Query throttling](https://github.com/dnsimple/erldns/blob/main/src/pipes/erldns_query_throttle.erl): `src/pipes/erldns_query_throttle.erl`
- [Packet cache](https://github.com/dnsimple/erldns/blob/main/src/pipes/erldns_packet_cache.erl): `src/pipes/erldns_packet_cache.erl`

### Zone management

- [Zone loader](https://github.com/dnsimple/erldns/blob/main/src/zones/load/erldns_zone_loader.erl): `src/zones/load/erldns_zone_loader.erl`
- [Zone JSON files](https://github.com/dnsimple/erldns/tree/main/priv/zones): `priv/zones`
- [Zone service](https://github.com/dnsimple/erldns/blob/main/src/zones/erldns_zones.erl): `src/zones/erldns_zones.erl`
- [Zone cache](https://github.com/dnsimple/erldns/blob/main/src/zones/erldns_zone_cache.erl): `src/zones/erldns_zone_cache.erl`

### Administration

- [Admin API](https://github.com/dnsimple/erldns/blob/main/src/admin/erldns_admin.erl): `src/admin/erldns_admin.erl`
- [Zone endpoints](https://github.com/dnsimple/erldns/blob/main/src/admin/erldns_admin_zone_handler.erl): `src/admin/erldns_admin_zone_handler.erl`
- [Record endpoints](https://github.com/dnsimple/erldns/blob/main/src/admin/erldns_admin_zone_records_handler.erl): `src/admin/erldns_admin_zone_records_handler.erl`

### Other components

- **DNS client**
- **Admin API client**
- **Telemetry**

## Connections

- DNS client → DNS listeners: sends DNS queries
- DNS listeners → UDP transport: accepts UDP
- DNS listeners → TCP transport: accepts TCP
- DNS listeners → Query pipeline: dispatches queries
- Zone JSON files → Zone loader: provides zone data
- Zone loader → Zone service: loads zones
- Admin API client → Admin API: sends HTTP requests
- Admin API → Zone endpoints: routes requests
- Admin API → Record endpoints: routes requests
- Query pipeline → Telemetry: emits events
- DNS listeners → Telemetry: emits events