# auv888/dns_relay architecture

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

- Interactive diagram: https://gitdiagram.com/auv888/dns_relay
- Repository: https://github.com/auv888/dns_relay

## Overview

SND is a single-threaded DNS relay with local caching, upstream forwarding, configurable runtime modes, and binary event logging. The main workflow is client query → local lookup or upstream relay → client response; startup parses options, initializes sockets and cache, and optionally loads cached records. The graph also includes log parsing and DNS wire-format support. Some server and parser implementation is excerpted only partially, so edges to their dependencies rely on the shown calls, SOURCE INDEX references, or README statements rather than a full source review.

Main entry points: [`src/DNS_server.c`](https://github.com/auv888/dns_relay/blob/master/src/DNS_server.c) (Socket event loop), [`src/main.c`](https://github.com/auv888/dns_relay/blob/master/src/main.c) (Program entry), [`src/DNS_arguments.c`](https://github.com/auv888/dns_relay/blob/master/src/DNS_arguments.c) (CLI and cache loader), [`src/DNS_convert.c`](https://github.com/auv888/dns_relay/blob/master/src/DNS_convert.c) (DNS codec)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Startup and configuration"]
  node_main["Program entry<br/>[main.c]"]
  node_arguments["CLI and cache loader<br/>[DNS_arguments.c]"]
end

subgraph group_relay["DNS relay"]
  node_server["Socket event loop<br/>[DNS_server.c]"]
  node_wire["DNS codec<br/>[DNS_convert.c]"]
  node_message["DNS message types<br/>[DNS_struct.h]"]
end

subgraph group_support["Runtime support"]
  node_cache[("DNS cache<br/>[DNS_cache.c]")]
  node_idmap[("Transaction ID map<br/>[DNS_id.c]")]
end

subgraph group_observability["Logging and analysis"]
  node_debug["Binary event logger<br/>[DNS_debug.c]"]
  node_logparser["Log parser<br/>[DNS_logparser.c]"]
end

node_operator(("Operator"))
node_client(("DNS clients"))
node_upstream(("Upstream DNS"))
node_logfile["Binary log file"]

node_operator -->|"starts"| node_main
node_main -->|"parses options"| node_arguments
node_main -->|"initializes and runs"| node_server
node_main -->|"loads cache file"| node_arguments
node_client -->|"sends queries"| node_server
node_server -->|"decodes and encodes"| node_wire
node_wire -->|"uses structures"| node_message
node_server -->|"looks up and updates"| node_cache
node_arguments -->|"inserts loaded records"| node_cache
node_server -->|"tracks forwarded queries"| node_idmap
node_server -->|"forwards queries"| node_upstream
node_upstream -->|"returns answers"| node_server
node_server -->|"replies"| node_client
node_server -->|"writes events"| node_debug
node_debug -->|"writes binary records"| node_logfile
node_operator -->|"runs on logs"| node_logparser
node_logfile -->|"provides input"| node_logparser

click node_main "https://github.com/auv888/dns_relay/blob/master/src/main.c"
click node_arguments "https://github.com/auv888/dns_relay/blob/master/src/DNS_arguments.c"
click node_server "https://github.com/auv888/dns_relay/blob/master/src/DNS_server.c"
click node_wire "https://github.com/auv888/dns_relay/blob/master/src/DNS_convert.c"
click node_message "https://github.com/auv888/dns_relay/blob/master/include/DNS_struct.h"
click node_cache "https://github.com/auv888/dns_relay/blob/master/src/DNS_cache.c"
click node_idmap "https://github.com/auv888/dns_relay/blob/master/src/DNS_id.c"
click node_debug "https://github.com/auv888/dns_relay/blob/master/src/DNS_debug.c"
click node_logparser "https://github.com/auv888/dns_relay/blob/master/src/DNS_logparser.c"

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_arguments,node_client toneBlue
class node_server,node_wire,node_message toneAmber
class node_cache,node_idmap toneMint
class node_debug,node_logparser toneRose
class node_operator,node_upstream,node_logfile toneIndigo
```

## Components

### Startup and configuration

- [Program entry](https://github.com/auv888/dns_relay/blob/master/src/main.c): `src/main.c`
- [CLI and cache loader](https://github.com/auv888/dns_relay/blob/master/src/DNS_arguments.c): `src/DNS_arguments.c`

### DNS relay

- [Socket event loop](https://github.com/auv888/dns_relay/blob/master/src/DNS_server.c): `src/DNS_server.c`
- [DNS codec](https://github.com/auv888/dns_relay/blob/master/src/DNS_convert.c): `src/DNS_convert.c`
- [DNS message types](https://github.com/auv888/dns_relay/blob/master/include/DNS_struct.h): `include/DNS_struct.h`

### Runtime support

- [DNS cache](https://github.com/auv888/dns_relay/blob/master/src/DNS_cache.c): `src/DNS_cache.c`
- [Transaction ID map](https://github.com/auv888/dns_relay/blob/master/src/DNS_id.c): `src/DNS_id.c`

### Logging and analysis

- [Binary event logger](https://github.com/auv888/dns_relay/blob/master/src/DNS_debug.c): `src/DNS_debug.c`
- [Log parser](https://github.com/auv888/dns_relay/blob/master/src/DNS_logparser.c): `src/DNS_logparser.c`

### Other components

- **Operator**
- **DNS clients**
- **Upstream DNS**
- **Binary log file**

## Connections

- Operator → Program entry: starts (evidence: `README.md`)
- Program entry → CLI and cache loader: parses options (evidence: `src/main.c`)
- Program entry → Socket event loop: initializes and runs (evidence: `src/main.c`)
- Program entry → CLI and cache loader: loads cache file (evidence: `src/main.c`)
- DNS clients → Socket event loop: sends queries (evidence: `README.md`)
- Socket event loop → DNS codec: decodes and encodes (evidence: `src/DNS_server.c`)
- DNS codec → DNS message types: uses structures (evidence: `src/DNS_convert.c`)
- Socket event loop → DNS cache: looks up and updates (evidence: `src/DNS_server.c`)
- CLI and cache loader → DNS cache: inserts loaded records (evidence: `src/DNS_arguments.c`)
- Socket event loop → Transaction ID map: tracks forwarded queries (evidence: `src/DNS_server.c`)
- Socket event loop → Upstream DNS: forwards queries (evidence: `README.md`)
- Upstream DNS → Socket event loop: returns answers (evidence: `README.md`)
- Socket event loop → DNS clients: replies (evidence: `README.md`)
- Socket event loop → Binary event logger: writes events (evidence: `src/DNS_server.c`)
- Binary event logger → Binary log file: writes binary records
- Operator → Log parser: runs on logs (evidence: `src/DNS_logparser.c`)
- Binary log file → Log parser: provides input (evidence: `src/DNS_logparser.c`)
