# niammuddin/zet-dns architecture

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

- Interactive diagram: https://gitdiagram.com/niammuddin/zet-dns
- Repository: https://github.com/niammuddin/zet-dns

## Overview

Zet-DNS is a DNS filtering server built around Unbound, with a web admin dashboard and an automatically refreshed Komdigi Trust Positif blocklist. DNS clients send queries to the resolver, which provides filtering and documented DNS features; administrators use the dashboard to manage rules. A separate updater builds a replacement CDB, and Unbound hot-remaps it without a resolver reload. The README documents these capabilities, but no source excerpts were provided, so implementation-level calls and several internal links cannot be verified.

Main entry points: [`src/bin/unbound`](https://github.com/niammuddin/zet-dns/blob/main/src/bin/unbound) (Unbound resolver), [`src/bin/dnstrust-admin`](https://github.com/niammuddin/zet-dns/blob/main/src/bin/dnstrust-admin) (Admin dashboard), [`src/etc/nftables.conf`](https://github.com/niammuddin/zet-dns/blob/main/src/etc/nftables.conf) (nftables firewall), [`src/scripts/update-blacklist.sh`](https://github.com/niammuddin/zet-dns/blob/main/src/scripts/update-blacklist.sh) (Blacklist updater)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dns["DNS service"]
  node_resolver["Unbound resolver"]
  node_dnsconfig["Resolver configuration<br/>[unbound.conf]"]
  node_filtering["Trust+ filtering"]
  node_safesearch["SafeSearch<br/>[safesearch.conf]"]
  node_whitelist["Whitelist<br/>[whitelist.conf]"]
  node_localdns["Local DNS<br/>[hosts.conf]"]
  node_tproxy["T-Proxy DNS<br/>[tproxy.conf]"]
  node_dnssec["DNSSEC"]
end

subgraph group_admin["Administration"]
  node_dashboard["Admin dashboard"]
  node_adminrules["Rule management"]
  node_inspection["DNS inspector"]
  node_activity["Activity log"]
  node_blockpage["Block page"]
end

subgraph group_updates["Blocklist updates"]
  node_updater["Blacklist updater"]
  node_schedule["Update schedule"]
  node_cdb[("Blocklist CDB")]
  node_remap["Hot-remap worker"]
end

subgraph group_host["Host security"]
  node_firewall["nftables firewall<br/>[nftables.conf]"]
end

node_clients(("DNS clients"))
node_router(("Redirecting router"))
node_browser(("Admin browser"))

node_clients -->|"sends queries"| node_resolver
node_resolver -->|"answers queries"| node_clients
node_router -.->|"redirects DNS"| node_resolver
node_resolver -->|"filters domains"| node_filtering
node_resolver -->|"applies"| node_safesearch
node_resolver -->|"honors exceptions"| node_whitelist
node_resolver -->|"resolves locally"| node_localdns
node_resolver -.->|"accepts redirected DNS"| node_tproxy
node_resolver -->|"supports"| node_dnssec
node_browser -->|"opens"| node_dashboard
node_dashboard -->|"manages"| node_adminrules
node_dashboard -->|"provides"| node_inspection
node_dashboard -->|"provides"| node_activity
node_dashboard -->|"serves"| node_blockpage
node_schedule -->|"schedules"| node_updater
node_updater -->|"builds and replaces"| node_cdb
node_remap -->|"triggers hot-remap"| node_resolver
node_firewall -->|"allows DNS traffic"| node_resolver
node_firewall -->|"allows dashboard traffic"| node_dashboard

click node_resolver "https://github.com/niammuddin/zet-dns/blob/main/src/bin/unbound"
click node_dnsconfig "https://github.com/niammuddin/zet-dns/blob/main/src/etc/unbound/unbound.conf"
click node_filtering "https://github.com/niammuddin/zet-dns/tree/main/src/etc/unbound"
click node_safesearch "https://github.com/niammuddin/zet-dns/blob/main/src/etc/unbound/safesearch.conf"
click node_whitelist "https://github.com/niammuddin/zet-dns/blob/main/src/etc/unbound/whitelist.conf"
click node_localdns "https://github.com/niammuddin/zet-dns/blob/main/src/etc/unbound/hosts.conf"
click node_tproxy "https://github.com/niammuddin/zet-dns/blob/main/src/etc/unbound/tproxy.conf"
click node_dnssec "https://github.com/niammuddin/zet-dns/tree/main/src/etc/unbound"
click node_dashboard "https://github.com/niammuddin/zet-dns/blob/main/src/bin/dnstrust-admin"
click node_adminrules "https://github.com/niammuddin/zet-dns/blob/main/src/bin/dnstrust-admin"
click node_inspection "https://github.com/niammuddin/zet-dns/blob/main/src/bin/dnstrust-admin"
click node_activity "https://github.com/niammuddin/zet-dns/blob/main/src/bin/dnstrust-admin"
click node_blockpage "https://github.com/niammuddin/zet-dns/blob/main/src/bin/dnstrust-admin"
click node_updater "https://github.com/niammuddin/zet-dns/blob/main/src/scripts/update-blacklist.sh"
click node_schedule "https://github.com/niammuddin/zet-dns/blob/main/src/systemd/unbound-blacklist-update.timer"
click node_cdb "https://github.com/niammuddin/zet-dns/tree/main/src/etc"
click node_remap "https://github.com/niammuddin/zet-dns/blob/main/src/systemd/dnstrust-admin-worker.path"
click node_firewall "https://github.com/niammuddin/zet-dns/blob/main/src/etc/nftables.conf"

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_resolver,node_dnsconfig,node_filtering,node_safesearch,node_whitelist,node_localdns,node_tproxy,node_dnssec,node_clients,node_browser toneBlue
class node_dashboard,node_adminrules,node_inspection,node_activity,node_blockpage toneAmber
class node_updater,node_schedule,node_cdb,node_remap,node_router toneMint
class node_firewall toneRose
```

## Components

### DNS service

- [Unbound resolver](https://github.com/niammuddin/zet-dns/blob/main/src/bin/unbound): `src/bin/unbound`
- [Resolver configuration](https://github.com/niammuddin/zet-dns/blob/main/src/etc/unbound/unbound.conf): `src/etc/unbound/unbound.conf`
- [Trust+ filtering](https://github.com/niammuddin/zet-dns/tree/main/src/etc/unbound): `src/etc/unbound`
- [SafeSearch](https://github.com/niammuddin/zet-dns/blob/main/src/etc/unbound/safesearch.conf): `src/etc/unbound/safesearch.conf`
- [Whitelist](https://github.com/niammuddin/zet-dns/blob/main/src/etc/unbound/whitelist.conf): `src/etc/unbound/whitelist.conf`
- [Local DNS](https://github.com/niammuddin/zet-dns/blob/main/src/etc/unbound/hosts.conf): `src/etc/unbound/hosts.conf`
- [T-Proxy DNS](https://github.com/niammuddin/zet-dns/blob/main/src/etc/unbound/tproxy.conf): `src/etc/unbound/tproxy.conf`
- [DNSSEC](https://github.com/niammuddin/zet-dns/tree/main/src/etc/unbound): `src/etc/unbound`

### Administration

- [Admin dashboard](https://github.com/niammuddin/zet-dns/blob/main/src/bin/dnstrust-admin): `src/bin/dnstrust-admin`
- [Rule management](https://github.com/niammuddin/zet-dns/blob/main/src/bin/dnstrust-admin): `src/bin/dnstrust-admin`
- [DNS inspector](https://github.com/niammuddin/zet-dns/blob/main/src/bin/dnstrust-admin): `src/bin/dnstrust-admin`
- [Activity log](https://github.com/niammuddin/zet-dns/blob/main/src/bin/dnstrust-admin): `src/bin/dnstrust-admin`
- [Block page](https://github.com/niammuddin/zet-dns/blob/main/src/bin/dnstrust-admin): `src/bin/dnstrust-admin`

### Blocklist updates

- [Blacklist updater](https://github.com/niammuddin/zet-dns/blob/main/src/scripts/update-blacklist.sh): `src/scripts/update-blacklist.sh`
- [Update schedule](https://github.com/niammuddin/zet-dns/blob/main/src/systemd/unbound-blacklist-update.timer): `src/systemd/unbound-blacklist-update.timer`
- [Blocklist CDB](https://github.com/niammuddin/zet-dns/tree/main/src/etc): `src/etc`
- [Hot-remap worker](https://github.com/niammuddin/zet-dns/blob/main/src/systemd/dnstrust-admin-worker.path): `src/systemd/dnstrust-admin-worker.path`

### Host security

- [nftables firewall](https://github.com/niammuddin/zet-dns/blob/main/src/etc/nftables.conf): `src/etc/nftables.conf`

### Other components

- **DNS clients**
- **Redirecting router**
- **Admin browser**

## Connections

- DNS clients → Unbound resolver: sends queries (evidence: `README.md`)
- Unbound resolver → DNS clients: answers queries (evidence: `README.md`)
- Redirecting router → Unbound resolver: redirects DNS (evidence: `README.md`)
- Unbound resolver → Trust+ filtering: filters domains (evidence: `README.md`)
- Unbound resolver → SafeSearch: applies (evidence: `README.md`)
- Unbound resolver → Whitelist: honors exceptions (evidence: `README.md`)
- Unbound resolver → Local DNS: resolves locally (evidence: `README.md`)
- Unbound resolver → T-Proxy DNS: accepts redirected DNS (evidence: `README.md`)
- Unbound resolver → DNSSEC: supports (evidence: `README.md`)
- Admin browser → Admin dashboard: opens (evidence: `README.md`)
- Admin dashboard → Rule management: manages (evidence: `README.md`)
- Admin dashboard → DNS inspector: provides (evidence: `README.md`)
- Admin dashboard → Activity log: provides (evidence: `README.md`)
- Admin dashboard → Block page: serves (evidence: `README.md`)
- Update schedule → Blacklist updater: schedules (evidence: `README.md`)
- Blacklist updater → Blocklist CDB: builds and replaces (evidence: `README.md`)
- Hot-remap worker → Unbound resolver: triggers hot-remap (evidence: `README.md`)
- nftables firewall → Unbound resolver: allows DNS traffic (evidence: `README.md`)
- nftables firewall → Admin dashboard: allows dashboard traffic (evidence: `README.md`)