# rt1811/tiny-dns-resolver architecture

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

- Interactive diagram: https://gitdiagram.com/rt1811/tiny-dns-resolver
- Repository: https://github.com/rt1811/tiny-dns-resolver

## Overview

This is a small standalone iterative DNS resolver. The principal workflow starts in `Main`, resolves an A-record lookup through root and delegated nameservers, and prints the resulting IPv4 addresses. `IterativeResolver` owns delegation traversal, response validation, CNAME handling, missing-glue helper lookups, and alternate-server retries; `DnsCodec` handles wire-format encoding and parsing, while `DnsClient` performs UDP exchanges. The resolver source is partial, so internal call details beyond the documented responsibilities are not expanded.

Main entry points: [`src/IterativeResolver.java`](https://github.com/rt1811/tiny-dns-resolver/blob/main/src/IterativeResolver.java) (Iterative resolver), [`src/Main.java`](https://github.com/rt1811/tiny-dns-resolver/blob/main/src/Main.java) (CLI entry), [`src/DnsClient.java`](https://github.com/rt1811/tiny-dns-resolver/blob/main/src/DnsClient.java) (UDP client), [`src/DnsCodec.java`](https://github.com/rt1811/tiny-dns-resolver/blob/main/src/DnsCodec.java) (Packet codec)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry point"]
  node_main["CLI entry<br/>[Main.java]"]
end

subgraph group_resolution["Resolution"]
  node_resolver["Iterative resolver"]
  node_delegation["Referral traversal"]
  node_helpers["Glue and CNAME"]
  node_validation["Response checks"]
end

subgraph group_protocol["DNS protocol"]
  node_codec["Packet codec<br/>[DnsCodec.java]"]
  node_message["Parsed message<br/>[DnsMessage.java]"]
  node_client["UDP client<br/>[DnsClient.java]"]
end

node_user(("Lookup user"))
node_dns(("DNS nameservers"))

node_user -->|"requests lookup"| node_main
node_main -->|"calls resolveA"| node_resolver
node_resolver -->|"follows referrals"| node_delegation
node_resolver -->|"handles aliases and glue"| node_helpers
node_resolver -->|"validates responses"| node_validation
node_resolver -->|"encodes and parses"| node_codec
node_codec -->|"creates message"| node_message
node_resolver -->|"sends queries"| node_client
node_client -->|"UDP exchange"| node_dns
node_dns -->|"returns datagram"| node_client
node_resolver -->|"returns addresses"| node_main

click node_main "https://github.com/rt1811/tiny-dns-resolver/blob/main/src/Main.java"
click node_resolver "https://github.com/rt1811/tiny-dns-resolver/blob/main/src/IterativeResolver.java"
click node_delegation "https://github.com/rt1811/tiny-dns-resolver/blob/main/src/IterativeResolver.java"
click node_helpers "https://github.com/rt1811/tiny-dns-resolver/blob/main/src/IterativeResolver.java"
click node_validation "https://github.com/rt1811/tiny-dns-resolver/blob/main/src/IterativeResolver.java"
click node_codec "https://github.com/rt1811/tiny-dns-resolver/blob/main/src/DnsCodec.java"
click node_message "https://github.com/rt1811/tiny-dns-resolver/blob/main/src/DnsMessage.java"
click node_client "https://github.com/rt1811/tiny-dns-resolver/blob/main/src/DnsClient.java"

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_user toneBlue
class node_resolver,node_delegation,node_helpers,node_validation toneAmber
class node_codec,node_message,node_client,node_dns toneMint
```

## Components

### Entry point

- [CLI entry](https://github.com/rt1811/tiny-dns-resolver/blob/main/src/Main.java): `src/Main.java`

### Resolution

- [Iterative resolver](https://github.com/rt1811/tiny-dns-resolver/blob/main/src/IterativeResolver.java): `src/IterativeResolver.java`
- [Referral traversal](https://github.com/rt1811/tiny-dns-resolver/blob/main/src/IterativeResolver.java): `src/IterativeResolver.java`
- [Glue and CNAME](https://github.com/rt1811/tiny-dns-resolver/blob/main/src/IterativeResolver.java): `src/IterativeResolver.java`
- [Response checks](https://github.com/rt1811/tiny-dns-resolver/blob/main/src/IterativeResolver.java): `src/IterativeResolver.java`

### DNS protocol

- [Packet codec](https://github.com/rt1811/tiny-dns-resolver/blob/main/src/DnsCodec.java): `src/DnsCodec.java`
- [Parsed message](https://github.com/rt1811/tiny-dns-resolver/blob/main/src/DnsMessage.java): `src/DnsMessage.java`
- [UDP client](https://github.com/rt1811/tiny-dns-resolver/blob/main/src/DnsClient.java): `src/DnsClient.java`

### Other components

- **Lookup user**
- **DNS nameservers**

## Connections

- Lookup user → CLI entry: requests lookup
- CLI entry → Iterative resolver: calls resolveA
- Iterative resolver → Referral traversal: follows referrals
- Iterative resolver → Glue and CNAME: handles aliases and glue
- Iterative resolver → Response checks: validates responses
- Iterative resolver → Packet codec: encodes and parses
- Packet codec → Parsed message: creates message
- Iterative resolver → UDP client: sends queries
- UDP client → DNS nameservers: UDP exchange
- DNS nameservers → UDP client: returns datagram
- Iterative resolver → CLI entry: returns addresses