# rrchelbi/apex architecture

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

- Interactive diagram: https://gitdiagram.com/rrchelbi/apex
- Repository: https://github.com/rrchelbi/apex

## Overview

1. **Top-level shape**
   - This is a single Rust package with both a **library core** (`src/lib.rs`) and a **binary entry point** (`src/main.rs`).
   - The architecture is intentionally small: one network-facing server module, one protocol module tree, and a thin executable wrapper.

2. **Execution path**
   - `main.rs` boots the process, configures logging, and starts the DNS server.
   - The server binds to **UDP `0.0.0.0:2053`** by default, so the whole system is centered around raw DNS datagrams rather than HTTP or a higher-level framework.

3. **Transport boundary**
   - `src/server.rs` is the runtime boundary between the network and the resolver logic.
   - It receives UDP packets, hands them to the parser, drives resolution, then serializes the reply back onto the wire.
   - This module is where request/response lifecycle, socket handling, and logging of queries live.

4. **Protocol subsystem**
   - `src/protocol/` contains the DNS wire-format implementation.
   - `header.rs`, `packet.rs`, `question.rs`, `query.rs`, and `record.rs` model RFC 1035 concepts directly, with a focus on **zero-copy parsing/serialization** from raw bytes.
   - This layer isolates all DNS-specific byte layout concerns from the server logic.

5. **Internal data model**
   - Incoming wire bytes are converted into structured DNS types such as headers, questions, queries, and records.
   - The resolver operates on these internal types, not on raw buffers, which keeps packet handling and resolution logic cleanly separated.

6. **Recursive resolution flow**
   - The server performs **recursive DNS resolution itself**, rather than delegating to the host OS resolver.
   - The flow starts from **root servers**, then iteratively follows referrals to authoritative name servers until it can answer the question.
   - The debug trace in the README shows this as a series of lookups against upstream DNS servers.

7. **Record handling scope**
   - The project currently supports **A, AAAA, NS, CNAME, and MX** records, plus **unknown record passthrough**.
   - That means the protocol layer and resolver are designed to preserve and forward DNS data even when it is not fully understood.

8. **Cross-cutting concerns**
   - `anyhow` is used for error propagation across parser, resolver, and server boundaries.
   - `tracing` and `tracing-subscriber` provide structured logs, which are important for following recursive resolution steps and debugging wire-level failures.

9. **Current architecture limits**
   - The README makes clear this is still early-stage: no TTL cache, no concurrent query handling, no authoritative zone service, and no DoT/DoH.
   - Architecturally, that means the current system is a **recursive UDP resolver**, not a full DNS platform.

10. **Diagram-friendly boundary summary**
   - A useful architecture diagram would show:
     - **Client DNS query → UDP listener/server → protocol parser → recursive resolver → upstream root/authoritative servers → protocol serializer → UDP response**
   - The key internal split is between **transport + orchestration** in `server.rs` and **wire-format DNS modeling** in `src/protocol/`.

Main entry points: [`src/server.rs`](https://github.com/rrchelbi/apex/blob/main/src/server.rs) (DNS server), [`src/protocol/packet.rs`](https://github.com/rrchelbi/apex/blob/main/src/protocol/packet.rs) (Packet), [`src/lib.rs`](https://github.com/rrchelbi/apex/blob/main/src/lib.rs) (Library core), [`src/main.rs`](https://github.com/rrchelbi/apex/blob/main/src/main.rs) (Main)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_client(("DNS client<br/>external peer"))
  node_main_rs["Main<br/>binary entry<br/>[main.rs]"]
  node_lib_rs["Library core<br/>crate root<br/>[lib.rs]"]
  node_server_rs["DNS server<br/>udp resolver<br/>[server.rs]"]
  node_root_servers(("Root servers<br/>upstream DNS"))
  node_auth_servers(("Auth servers<br/>upstream DNS"))
end

subgraph group_protocol["Protocol"]
  node_header_rs["Header<br/>[header.rs]"]
  node_packet_rs["Packet<br/>[packet.rs]"]
  node_question_rs["Question<br/>[question.rs]"]
  node_query_rs["Query<br/>[query.rs]"]
  node_record_rs["Record<br/>[record.rs]"]
end

node_client -->|"starts"| node_main_rs
node_main_rs -->|"launches"| node_server_rs
node_lib_rs -->|"exports"| node_server_rs
node_lib_rs -->|"exports"| node_packet_rs
node_server_rs -->|"parses"| node_packet_rs
node_packet_rs -->|"contains"| node_header_rs
node_packet_rs -->|"contains"| node_question_rs
node_packet_rs -->|"contains"| node_record_rs
node_question_rs -->|"maps to"| node_query_rs
node_server_rs -->|"drives"| node_query_rs
node_server_rs -->|"queries"| node_root_servers
node_root_servers -->|"refers"| node_auth_servers
node_auth_servers -->|"returns"| node_record_rs
node_server_rs -->|"serializes"| node_packet_rs

click node_main_rs "https://github.com/rrchelbi/apex/blob/main/src/main.rs"
click node_lib_rs "https://github.com/rrchelbi/apex/blob/main/src/lib.rs"
click node_server_rs "https://github.com/rrchelbi/apex/blob/main/src/server.rs"
click node_header_rs "https://github.com/rrchelbi/apex/blob/main/src/protocol/header.rs"
click node_packet_rs "https://github.com/rrchelbi/apex/blob/main/src/protocol/packet.rs"
click node_question_rs "https://github.com/rrchelbi/apex/blob/main/src/protocol/question.rs"
click node_query_rs "https://github.com/rrchelbi/apex/blob/main/src/protocol/query.rs"
click node_record_rs "https://github.com/rrchelbi/apex/blob/main/src/protocol/record.rs"

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,node_main_rs,node_lib_rs,node_server_rs,node_root_servers,node_auth_servers toneBlue
class node_header_rs,node_packet_rs,node_question_rs,node_query_rs,node_record_rs toneAmber
```

## Components

### Runtime

Process entry, UDP server, and recursive DNS flow.

- **DNS client**: external peer · Sends DNS queries over UDP.
- [Main](https://github.com/rrchelbi/apex/blob/main/src/main.rs): binary entry · Boots logging and starts the server. · `src/main.rs`
- [Library core](https://github.com/rrchelbi/apex/blob/main/src/lib.rs): crate root · Shared library surface for the resolver and protocol modules. · `src/lib.rs`
- [DNS server](https://github.com/rrchelbi/apex/blob/main/src/server.rs): udp resolver · Receives packets, drives recursive resolution, and writes replies. · `src/server.rs`
- **Root servers**: upstream DNS · Starting point for iterative recursive lookup.
- **Auth servers**: upstream DNS · Authoritative name servers followed during referrals.

### Protocol

DNS wire-format parsing and serialization.

- [Header](https://github.com/rrchelbi/apex/blob/main/src/protocol/header.rs): dns header · Models the DNS header fields in wire format. · `src/protocol/header.rs`
- [Packet](https://github.com/rrchelbi/apex/blob/main/src/protocol/packet.rs): dns packet · Top-level DNS message parsing and serialization. · `src/protocol/packet.rs`
- [Question](https://github.com/rrchelbi/apex/blob/main/src/protocol/question.rs): dns question · Represents the query question section. · `src/protocol/question.rs`
- [Query](https://github.com/rrchelbi/apex/blob/main/src/protocol/query.rs): dns query · Structured internal query model used by resolution logic. · `src/protocol/query.rs`
- [Record](https://github.com/rrchelbi/apex/blob/main/src/protocol/record.rs): dns record · Models resource records, including unknown passthrough. · `src/protocol/record.rs`

## Connections

- DNS client → Main: starts · Client traffic reaches the process started by the binary.
- Main → DNS server: launches · Main configures logging and starts the UDP DNS server.
- Library core → DNS server: exports · Library crate exposes the server runtime.
- Library core → Packet: exports · Library crate exposes protocol primitives.
- DNS server → Packet: parses · Incoming UDP datagrams are decoded into DNS packets.
- Packet → Header: contains · Packet structure includes DNS header fields.
- Packet → Question: contains · Packet structure includes question sections.
- Packet → Record: contains · Packet structure includes resource records.
- Question → Query: maps to · Parsed questions become internal query objects.
- DNS server → Query: drives · Server resolves structured queries instead of raw bytes.
- DNS server → Root servers: queries · Recursive resolution begins at root servers.
- Root servers → Auth servers: refers · Referrals are followed to authoritative servers.
- Auth servers → Record: returns · Authoritative answers are represented as DNS records.
- DNS server → Packet: serializes · Resolved answers are encoded back onto the wire.