# struktsource/lumen-dns architecture

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

- Interactive diagram: https://gitdiagram.com/struktsource/lumen-dns
- Repository: https://github.com/struktsource/lumen-dns

## Overview

Lumen is a self-hosted DNS and network-management service. Its main path is DNS clients sending queries through bounded listeners to recursive or encrypted-forwarding resolution, with filtering and optional local answers; administrators manage configuration and network features through the console or CLI. The graph also retains documented DHCP, mDNS, certificates, authoritative zones, IPAM, and discovery capabilities. Several subsystem links are documented in the README; unsampled implementation details are not treated as inspected evidence.

Main entry points: [`apps/lumen/src/main.rs`](https://github.com/struktsource/lumen-dns/blob/main/apps/lumen/src/main.rs) (Lumen daemon), [`crates/lumen-web/src/console.rs`](https://github.com/struktsource/lumen-dns/blob/main/crates/lumen-web/src/console.rs) (Console API), [`crates/lumen-core/src/transport.rs`](https://github.com/struktsource/lumen-dns/blob/main/crates/lumen-core/src/transport.rs) (DNS transports), [`crates/lumen-core/src/lib.rs`](https://github.com/struktsource/lumen-dns/blob/main/crates/lumen-core/src/lib.rs) (Query service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["DNS runtime"]
  node_daemon["Lumen daemon<br/>[main.rs]"]
  node_config["Configuration<br/>[lib.rs]"]
  node_listeners["DNS transports<br/>[transport.rs]"]
  node_service["Query service<br/>[lib.rs]"]
  node_certificates["ACME certificates<br/>[acme.rs]"]
end

subgraph group_dns["Resolution features"]
  node_resolver["Recursive resolver<br/>[lib.rs]"]
  node_forwarding["Encrypted forwarding<br/>[forward.rs]"]
  node_filter["Client filtering<br/>[lib.rs]"]
  node_zones["Authoritative zones<br/>[zones.rs]"]
end

subgraph group_network["Network services"]
  node_dhcp["DHCP server<br/>[server.rs]"]
  node_mdns["mDNS bridge<br/>[bridge.rs]"]
  node_ipam[("Address management<br/>[store.rs]")]
  node_discovery["Network discovery<br/>[engine.rs]"]
end

subgraph group_management["Management"]
  node_cli["lumenctl<br/>[main.rs]"]
  node_management_api["Management API<br/>[lib.rs]"]
  node_state[("SQLite state<br/>[lib.rs]")]
end

subgraph group_web["Web console"]
  node_console["Console API<br/>[console.rs]"]
  node_web_host["Console host<br/>[host.rs]"]
  node_browser["Browser console<br/>[app.js]"]
end

node_dns_client(("DNS clients"))

node_dns_client -->|"sends queries"| node_listeners
node_listeners -->|"dispatches queries"| node_service
node_service -->|"resolves queries"| node_resolver
node_resolver -->|"forwards optionally"| node_forwarding
node_service -.->|"filters clients"| node_filter
node_resolver -->|"serves zones"| node_zones
node_daemon -.->|"loads settings"| node_config
node_daemon -.->|"starts service"| node_listeners
node_listeners -->|"obtains certificates"| node_certificates
node_daemon -.->|"starts optionally"| node_dhcp
node_daemon -.->|"enables optionally"| node_mdns
node_daemon -.->|"runs optionally"| node_discovery
node_console -->|"manages addresses"| node_ipam
node_console -->|"manages DHCP"| node_dhcp
node_browser -->|"calls API"| node_console
node_console -->|"queries daemon"| node_web_host
node_console -->|"reads and writes"| node_state
node_cli -->|"controls service"| node_daemon
node_management_api -.->|"manages state"| node_state

click node_daemon "https://github.com/struktsource/lumen-dns/blob/main/apps/lumen/src/main.rs"
click node_config "https://github.com/struktsource/lumen-dns/blob/main/crates/lumen-config/src/lib.rs"
click node_listeners "https://github.com/struktsource/lumen-dns/blob/main/crates/lumen-core/src/transport.rs"
click node_service "https://github.com/struktsource/lumen-dns/blob/main/crates/lumen-core/src/lib.rs"
click node_resolver "https://github.com/struktsource/lumen-dns/blob/main/crates/lumen-resolver/src/lib.rs"
click node_forwarding "https://github.com/struktsource/lumen-dns/blob/main/crates/lumen-resolver/src/forward.rs"
click node_filter "https://github.com/struktsource/lumen-dns/blob/main/crates/lumen-filter/src/lib.rs"
click node_zones "https://github.com/struktsource/lumen-dns/blob/main/crates/lumen-resolver/src/zones.rs"
click node_certificates "https://github.com/struktsource/lumen-dns/blob/main/crates/lumen-core/src/acme.rs"
click node_dhcp "https://github.com/struktsource/lumen-dns/blob/main/crates/lumen-dhcp/src/server.rs"
click node_mdns "https://github.com/struktsource/lumen-dns/blob/main/crates/lumen-mdns/src/bridge.rs"
click node_ipam "https://github.com/struktsource/lumen-dns/blob/main/crates/lumen-ipam/src/store.rs"
click node_discovery "https://github.com/struktsource/lumen-dns/blob/main/crates/lumen-netmon/src/engine.rs"
click node_cli "https://github.com/struktsource/lumen-dns/blob/main/apps/lumenctl/src/main.rs"
click node_management_api "https://github.com/struktsource/lumen-dns/blob/main/crates/lumen-api/src/lib.rs"
click node_state "https://github.com/struktsource/lumen-dns/blob/main/crates/lumen-store/src/lib.rs"
click node_console "https://github.com/struktsource/lumen-dns/blob/main/crates/lumen-web/src/console.rs"
click node_web_host "https://github.com/struktsource/lumen-dns/blob/main/crates/lumen-web/src/host.rs"
click node_browser "https://github.com/struktsource/lumen-dns/blob/main/web/js/app.js"

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_daemon,node_config,node_listeners,node_service,node_certificates,node_dns_client toneBlue
class node_resolver,node_forwarding,node_filter,node_zones toneAmber
class node_dhcp,node_mdns,node_ipam,node_discovery toneMint
class node_cli,node_management_api,node_state toneRose
class node_console,node_web_host,node_browser toneIndigo
```

## Components

### DNS runtime

- [Lumen daemon](https://github.com/struktsource/lumen-dns/blob/main/apps/lumen/src/main.rs): `apps/lumen/src/main.rs`
- [Configuration](https://github.com/struktsource/lumen-dns/blob/main/crates/lumen-config/src/lib.rs): `crates/lumen-config/src/lib.rs`
- [DNS transports](https://github.com/struktsource/lumen-dns/blob/main/crates/lumen-core/src/transport.rs): `crates/lumen-core/src/transport.rs`
- [Query service](https://github.com/struktsource/lumen-dns/blob/main/crates/lumen-core/src/lib.rs): `crates/lumen-core/src/lib.rs`
- [ACME certificates](https://github.com/struktsource/lumen-dns/blob/main/crates/lumen-core/src/acme.rs): `crates/lumen-core/src/acme.rs`

### Resolution features

- [Recursive resolver](https://github.com/struktsource/lumen-dns/blob/main/crates/lumen-resolver/src/lib.rs): `crates/lumen-resolver/src/lib.rs`
- [Encrypted forwarding](https://github.com/struktsource/lumen-dns/blob/main/crates/lumen-resolver/src/forward.rs): `crates/lumen-resolver/src/forward.rs`
- [Client filtering](https://github.com/struktsource/lumen-dns/blob/main/crates/lumen-filter/src/lib.rs): `crates/lumen-filter/src/lib.rs`
- [Authoritative zones](https://github.com/struktsource/lumen-dns/blob/main/crates/lumen-resolver/src/zones.rs): `crates/lumen-resolver/src/zones.rs`

### Network services

- [DHCP server](https://github.com/struktsource/lumen-dns/blob/main/crates/lumen-dhcp/src/server.rs): `crates/lumen-dhcp/src/server.rs`
- [mDNS bridge](https://github.com/struktsource/lumen-dns/blob/main/crates/lumen-mdns/src/bridge.rs): `crates/lumen-mdns/src/bridge.rs`
- [Address management](https://github.com/struktsource/lumen-dns/blob/main/crates/lumen-ipam/src/store.rs): `crates/lumen-ipam/src/store.rs`
- [Network discovery](https://github.com/struktsource/lumen-dns/blob/main/crates/lumen-netmon/src/engine.rs): `crates/lumen-netmon/src/engine.rs`

### Management

- [lumenctl](https://github.com/struktsource/lumen-dns/blob/main/apps/lumenctl/src/main.rs): `apps/lumenctl/src/main.rs`
- [Management API](https://github.com/struktsource/lumen-dns/blob/main/crates/lumen-api/src/lib.rs): `crates/lumen-api/src/lib.rs`
- [SQLite state](https://github.com/struktsource/lumen-dns/blob/main/crates/lumen-store/src/lib.rs): `crates/lumen-store/src/lib.rs`

### Web console

- [Console API](https://github.com/struktsource/lumen-dns/blob/main/crates/lumen-web/src/console.rs): `crates/lumen-web/src/console.rs`
- [Console host](https://github.com/struktsource/lumen-dns/blob/main/crates/lumen-web/src/host.rs): `crates/lumen-web/src/host.rs`
- [Browser console](https://github.com/struktsource/lumen-dns/blob/main/web/js/app.js): `web/js/app.js`

### Other components

- **DNS clients**

## Connections

- DNS clients → DNS transports: sends queries
- DNS transports → Query service: dispatches queries (evidence: `crates/lumen-core/src/transport.rs`)
- Query service → Recursive resolver: resolves queries (evidence: `crates/lumen-core/src/lib.rs`)
- Recursive resolver → Encrypted forwarding: forwards optionally (evidence: `crates/lumen-resolver/src/lib.rs`)
- Query service → Client filtering: filters clients
- Recursive resolver → Authoritative zones: serves zones (evidence: `crates/lumen-resolver/src/zones.rs`)
- Lumen daemon → Configuration: loads settings
- Lumen daemon → DNS transports: starts service
- DNS transports → ACME certificates: obtains certificates (evidence: `crates/lumen-core/src/transport.rs`)
- Lumen daemon → DHCP server: starts optionally
- Lumen daemon → mDNS bridge: enables optionally
- Lumen daemon → Network discovery: runs optionally
- Console API → Address management: manages addresses
- Console API → DHCP server: manages DHCP
- Browser console → Console API: calls API
- Console API → Console host: queries daemon (evidence: `crates/lumen-web/src/console.rs`)
- Console API → SQLite state: reads and writes (evidence: `crates/lumen-web/src/console.rs`)
- lumenctl → Lumen daemon: controls service
- Management API → SQLite state: manages state
