# hariantoatwork/dns01-proxy architecture

> Architecture diagram of the GitHub repository hariantoatwork/dns01-proxy, 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/hariantoatwork/dns01-proxy
- Repository: https://github.com/hariantoatwork/dns01-proxy

## Overview

dns01-proxy is an all-in-one DNS-01 certificate stack: its operator UI configures domains and accounts, then certificate jobs perform ACME issuance and write PEMs for consumers. Its runtime also serves authoritative DNS, manages settings and backups, and provides an edge reverse proxy; Tiny shared mode and the lab issuer are additional capabilities. The README documents the principal service boundaries; sampled source confirms selected DNS, authentication, storage, and job-planning details. Other feature links are dashed where implementation was not sampled.

Main entry points: [`src/dns01-proxy/plugins/client/runtime/pages/index.vue`](https://github.com/hariantoatwork/dns01-proxy/blob/main/src/dns01-proxy/plugins/client/runtime/pages/index.vue) (Operator UI), [`src/dns01-proxy/plugins/client/runtime/server/utils/certJobQueue/executor.ts`](https://github.com/hariantoatwork/dns01-proxy/blob/main/src/dns01-proxy/plugins/client/runtime/server/utils/certJobQueue/executor.ts) (Certificate job queue), [`src/dns01-proxy/plugins/client/runtime/server/api/certs/apply.post.ts`](https://github.com/hariantoatwork/dns01-proxy/blob/main/src/dns01-proxy/plugins/client/runtime/server/api/certs/apply.post.ts) (Certificate API), [`src/dns01-proxy/plugins/client/runtime/shared/utils/acmeIssueSteps.ts`](https://github.com/hariantoatwork/dns01-proxy/blob/main/src/dns01-proxy/plugins/client/runtime/shared/utils/acmeIssueSteps.ts) (ACME issue steps)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Operator control plane"]
  node_ui["Operator UI<br/>[index.vue]"]
  node_auth["UI authentication<br/>[adminAuth.ts]"]
  node_settings["Settings service<br/>[settingsService.ts]"]
  node_backups["Backup management<br/>[backup.ts]"]
  node_clientdata[("Client storage<br/>[storage.ts]")]
end

subgraph group_certs["Certificate lifecycle"]
  node_domains["Domain planning<br/>[domains.ts]"]
  node_certapi["Certificate API<br/>[apply.post.ts]"]
  node_jobs["Certificate job queue<br/>[executor.ts]"]
  node_acme["ACME issue steps<br/>[acmeIssueSteps.ts]"]
  node_pem[("Certificate files<br/>[letsencryptFs.ts]")]
  node_renew["Renew scheduler"]
end

subgraph group_dns["DNS identity service"]
  node_dnsserver["Authoritative DNS<br/>[server.ts]"]
  node_accounts["ACME DNS accounts<br/>[auth.ts]"]
  node_accountdb[("Account and TXT store<br/>[db.ts]")]
  node_tiny["Tiny shared DNS<br/>[tinyModeDns.ts]"]
end

subgraph group_edge["Edge proxy"]
  node_edgeproxy["Reverse proxy runtime<br/>[handle.ts]"]
  node_proxyconfig[("Proxy host configuration<br/>[proxyHostsFile.ts]")]
end

subgraph group_operations["Operations and extensions"]
  node_lab["Lab issuer<br/>[labIssueSteps.ts]"]
  node_diagnostics["DNS diagnostics<br/>[dnsQuery.ts]"]
end

node_operator(("Operator"))
node_lets(("Let's Encrypt"))
node_consumers(("Certificate consumers"))
node_publicdns(("Public DNS clients"))
node_visitors(("Public app visitors"))

node_operator -->|"operates"| node_ui
node_ui -.->|"authenticates through"| node_auth
node_ui -.->|"submits certificate actions"| node_certapi
node_ui -.->|"manages settings"| node_settings
node_ui -.->|"manages backups"| node_backups
node_ui -->|"reads and writes"| node_clientdata
node_ui -->|"edits certificate domains"| node_domains
node_certapi -.->|"validates domains"| node_domains
node_certapi -.->|"starts jobs"| node_jobs
node_jobs -.->|"tracks issue steps"| node_acme
node_acme -->|"requests certificates"| node_lets
node_lets -->|"queries DNS-01"| node_dnsserver
node_dnsserver -->|"reads TXT values"| node_accountdb
node_accounts -->|"reads and updates accounts"| node_accountdb
node_acme -->|"uses account credentials"| node_clientdata
node_jobs -->|"writes issued PEMs"| node_pem
node_renew -.->|"schedules renewals"| node_jobs
node_consumers -->|"mounts read-only"| node_pem
node_publicdns -->|"queries port 53"| node_dnsserver
node_visitors -->|"visits public apps"| node_edgeproxy
node_edgeproxy -.->|"uses host configuration"| node_proxyconfig
node_ui -.->|"runs lab issuance"| node_lab
node_ui -.->|"requests DNS checks"| node_diagnostics
node_tiny -->|"supports shared accounts"| node_accountdb

click node_ui "https://github.com/hariantoatwork/dns01-proxy/blob/main/src/dns01-proxy/plugins/client/runtime/pages/index.vue"
click node_auth "https://github.com/hariantoatwork/dns01-proxy/blob/main/src/dns01-proxy/plugins/client/runtime/server/utils/adminAuth.ts"
click node_settings "https://github.com/hariantoatwork/dns01-proxy/blob/main/src/dns01-proxy/plugins/client/runtime/server/utils/settingsService.ts"
click node_backups "https://github.com/hariantoatwork/dns01-proxy/blob/main/src/dns01-proxy/plugins/client/runtime/server/utils/backup.ts"
click node_clientdata "https://github.com/hariantoatwork/dns01-proxy/blob/main/src/dns01-proxy/plugins/client/runtime/server/utils/storage.ts"
click node_domains "https://github.com/hariantoatwork/dns01-proxy/blob/main/src/dns01-proxy/plugins/client/runtime/shared/utils/domains.ts"
click node_certapi "https://github.com/hariantoatwork/dns01-proxy/blob/main/src/dns01-proxy/plugins/client/runtime/server/api/certs/apply.post.ts"
click node_jobs "https://github.com/hariantoatwork/dns01-proxy/blob/main/src/dns01-proxy/plugins/client/runtime/server/utils/certJobQueue/executor.ts"
click node_acme "https://github.com/hariantoatwork/dns01-proxy/blob/main/src/dns01-proxy/plugins/client/runtime/shared/utils/acmeIssueSteps.ts"
click node_pem "https://github.com/hariantoatwork/dns01-proxy/blob/main/src/dns01-proxy/plugins/client/runtime/server/utils/letsencryptFs.ts"
click node_renew "https://github.com/hariantoatwork/dns01-proxy/blob/main/src/dns01-proxy/plugins/client/runtime/server/utils/certRenewScheduler.ts"
click node_dnsserver "https://github.com/hariantoatwork/dns01-proxy/blob/main/src/dns01-proxy/server/dns/server.ts"
click node_accounts "https://github.com/hariantoatwork/dns01-proxy/blob/main/src/dns01-proxy/server/utils/auth.ts"
click node_accountdb "https://github.com/hariantoatwork/dns01-proxy/blob/main/src/dns01-proxy/server/utils/db.ts"
click node_tiny "https://github.com/hariantoatwork/dns01-proxy/blob/main/src/dns01-proxy/plugins/client/runtime/shared/utils/tinyModeDns.ts"
click node_edgeproxy "https://github.com/hariantoatwork/dns01-proxy/blob/main/src/dns01-proxy/server/proxy/handle.ts"
click node_proxyconfig "https://github.com/hariantoatwork/dns01-proxy/blob/main/src/dns01-proxy/plugins/proxy/runtime/server/utils/proxyHostsFile.ts"
click node_lab "https://github.com/hariantoatwork/dns01-proxy/blob/main/src/dns01-proxy/plugins/dns01-lab/runtime/shared/utils/labIssueSteps.ts"
click node_diagnostics "https://github.com/hariantoatwork/dns01-proxy/blob/main/src/dns01-proxy/plugins/client/runtime/server/utils/dnsQuery.ts"

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_ui,node_auth,node_settings,node_backups,node_clientdata,node_publicdns toneBlue
class node_domains,node_certapi,node_jobs,node_acme,node_pem,node_renew toneAmber
class node_dnsserver,node_accounts,node_accountdb,node_tiny toneMint
class node_edgeproxy,node_proxyconfig toneRose
class node_lab,node_diagnostics,node_operator,node_lets,node_consumers,node_visitors toneIndigo
```

## Components

### Operator control plane

- [Operator UI](https://github.com/hariantoatwork/dns01-proxy/blob/main/src/dns01-proxy/plugins/client/runtime/pages/index.vue): `src/dns01-proxy/plugins/client/runtime/pages/index.vue`
- [UI authentication](https://github.com/hariantoatwork/dns01-proxy/blob/main/src/dns01-proxy/plugins/client/runtime/server/utils/adminAuth.ts): `src/dns01-proxy/plugins/client/runtime/server/utils/adminAuth.ts`
- [Settings service](https://github.com/hariantoatwork/dns01-proxy/blob/main/src/dns01-proxy/plugins/client/runtime/server/utils/settingsService.ts): `src/dns01-proxy/plugins/client/runtime/server/utils/settingsService.ts`
- [Backup management](https://github.com/hariantoatwork/dns01-proxy/blob/main/src/dns01-proxy/plugins/client/runtime/server/utils/backup.ts): `src/dns01-proxy/plugins/client/runtime/server/utils/backup.ts`
- [Client storage](https://github.com/hariantoatwork/dns01-proxy/blob/main/src/dns01-proxy/plugins/client/runtime/server/utils/storage.ts): `src/dns01-proxy/plugins/client/runtime/server/utils/storage.ts`

### Certificate lifecycle

- [Domain planning](https://github.com/hariantoatwork/dns01-proxy/blob/main/src/dns01-proxy/plugins/client/runtime/shared/utils/domains.ts): `src/dns01-proxy/plugins/client/runtime/shared/utils/domains.ts`
- [Certificate API](https://github.com/hariantoatwork/dns01-proxy/blob/main/src/dns01-proxy/plugins/client/runtime/server/api/certs/apply.post.ts): `src/dns01-proxy/plugins/client/runtime/server/api/certs/apply.post.ts`
- [Certificate job queue](https://github.com/hariantoatwork/dns01-proxy/blob/main/src/dns01-proxy/plugins/client/runtime/server/utils/certJobQueue/executor.ts): `src/dns01-proxy/plugins/client/runtime/server/utils/certJobQueue/executor.ts`
- [ACME issue steps](https://github.com/hariantoatwork/dns01-proxy/blob/main/src/dns01-proxy/plugins/client/runtime/shared/utils/acmeIssueSteps.ts): `src/dns01-proxy/plugins/client/runtime/shared/utils/acmeIssueSteps.ts`
- [Certificate files](https://github.com/hariantoatwork/dns01-proxy/blob/main/src/dns01-proxy/plugins/client/runtime/server/utils/letsencryptFs.ts): `src/dns01-proxy/plugins/client/runtime/server/utils/letsencryptFs.ts`
- [Renew scheduler](https://github.com/hariantoatwork/dns01-proxy/blob/main/src/dns01-proxy/plugins/client/runtime/server/utils/certRenewScheduler.ts): `src/dns01-proxy/plugins/client/runtime/server/utils/certRenewScheduler.ts`

### DNS identity service

- [Authoritative DNS](https://github.com/hariantoatwork/dns01-proxy/blob/main/src/dns01-proxy/server/dns/server.ts): `src/dns01-proxy/server/dns/server.ts`
- [ACME DNS accounts](https://github.com/hariantoatwork/dns01-proxy/blob/main/src/dns01-proxy/server/utils/auth.ts): `src/dns01-proxy/server/utils/auth.ts`
- [Account and TXT store](https://github.com/hariantoatwork/dns01-proxy/blob/main/src/dns01-proxy/server/utils/db.ts): `src/dns01-proxy/server/utils/db.ts`
- [Tiny shared DNS](https://github.com/hariantoatwork/dns01-proxy/blob/main/src/dns01-proxy/plugins/client/runtime/shared/utils/tinyModeDns.ts): `src/dns01-proxy/plugins/client/runtime/shared/utils/tinyModeDns.ts`

### Edge proxy

- [Reverse proxy runtime](https://github.com/hariantoatwork/dns01-proxy/blob/main/src/dns01-proxy/server/proxy/handle.ts): `src/dns01-proxy/server/proxy/handle.ts`
- [Proxy host configuration](https://github.com/hariantoatwork/dns01-proxy/blob/main/src/dns01-proxy/plugins/proxy/runtime/server/utils/proxyHostsFile.ts): `src/dns01-proxy/plugins/proxy/runtime/server/utils/proxyHostsFile.ts`

### Operations and extensions

- [Lab issuer](https://github.com/hariantoatwork/dns01-proxy/blob/main/src/dns01-proxy/plugins/dns01-lab/runtime/shared/utils/labIssueSteps.ts): `src/dns01-proxy/plugins/dns01-lab/runtime/shared/utils/labIssueSteps.ts`
- [DNS diagnostics](https://github.com/hariantoatwork/dns01-proxy/blob/main/src/dns01-proxy/plugins/client/runtime/server/utils/dnsQuery.ts): `src/dns01-proxy/plugins/client/runtime/server/utils/dnsQuery.ts`

### Other components

- **Operator**
- **Let's Encrypt**
- **Certificate consumers**
- **Public DNS clients**
- **Public app visitors**

## Connections

- Operator → Operator UI: operates (evidence: `README.md`)
- Operator UI → UI authentication: authenticates through
- Operator UI → Certificate API: submits certificate actions
- Operator UI → Settings service: manages settings
- Operator UI → Backup management: manages backups
- Operator UI → Client storage: reads and writes (evidence: `README.md`)
- Operator UI → Domain planning: edits certificate domains (evidence: `README.md`)
- Certificate API → Domain planning: validates domains
- Certificate API → Certificate job queue: starts jobs
- Certificate job queue → ACME issue steps: tracks issue steps
- ACME issue steps → Let's Encrypt: requests certificates (evidence: `README.md`)
- Let's Encrypt → Authoritative DNS: queries DNS-01 (evidence: `README.md`)
- Authoritative DNS → Account and TXT store: reads TXT values (evidence: `src/dns01-proxy/server/dns/server.ts`)
- ACME DNS accounts → Account and TXT store: reads and updates accounts (evidence: `src/dns01-proxy/server/utils/auth.ts`)
- ACME issue steps → Client storage: uses account credentials (evidence: `README.md`)
- Certificate job queue → Certificate files: writes issued PEMs (evidence: `README.md`)
- Renew scheduler → Certificate job queue: schedules renewals
- Certificate consumers → Certificate files: mounts read-only (evidence: `README.md`)
- Public DNS clients → Authoritative DNS: queries port 53 (evidence: `README.md`)
- Public app visitors → Reverse proxy runtime: visits public apps (evidence: `README.md`)
- Reverse proxy runtime → Proxy host configuration: uses host configuration
- Operator UI → Lab issuer: runs lab issuance
- Operator UI → DNS diagnostics: requests DNS checks
- Tiny shared DNS → Account and TXT store: supports shared accounts (evidence: `src/dns01-proxy/server/utils/db.ts`)
