# stackexchange/dnscontrol architecture

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

- Interactive diagram: https://gitdiagram.com/stackexchange/dnscontrol
- Repository: https://github.com/stackexchange/dnscontrol

## Overview

DNSControl is DNS infrastructure-as-code: users describe zones in a JavaScript-compatible configuration, preview changes against DNS providers, then push approved corrections. The graph includes configuration parsing and normalization, provider integration, and the separate interactive initialization capability documented in the README. Several runtime paths are represented from documentation because their implementation was not excerpted; those links are dashed and unverified.

Main entry points: [`commands/ppreviewPush.go`](https://github.com/stackexchange/dnscontrol/blob/main/commands/ppreviewPush.go) (Preview and push), [`providers`](https://github.com/stackexchange/dnscontrol/tree/main/providers) (DNS provider adapters), [`main.go`](https://github.com/stackexchange/dnscontrol/blob/main/main.go) (Command dispatcher), [`commands/init.go`](https://github.com/stackexchange/dnscontrol/blob/main/commands/init.go) (Setup wizard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI workflows"]
  node_cli["Command dispatcher<br/>[main.go]"]
  node_init["Setup wizard<br/>[init.go]"]
  node_previewpush["Preview and push<br/>[ppreviewPush.go]"]
end

subgraph group_config["Configuration and records"]
  node_jsconfig["JS configuration<br/>[js.go]"]
  node_domain["Zone model<br/>[domain.go]"]
  node_records["DNS records<br/>[record.go]"]
  node_normalize["Normalize and validate<br/>[validate.go]"]
end

subgraph group_engine["Planning and providers"]
  node_providerregistry["Provider registry<br/>[providers.go]"]
  node_diff["Change analysis<br/>[diff2.go]"]
  node_corrections["Correction runner<br/>[ppreviewPush.go]"]
end

subgraph group_integrations["Provider services"]
  node_dnsproviders["DNS provider adapters"]
  node_registrars["Registrar adapters"]
end

node_operator(("DNS operator"))
node_dnsapi{{"DNS provider APIs"}}
node_registrarapi{{"Registrar APIs"}}
node_creds["Credentials file"]

node_operator -->|"runs"| node_cli
node_cli -->|"dispatches"| node_previewpush
node_cli -.->|"dispatches"| node_init
node_operator -->|"defines zones"| node_jsconfig
node_jsconfig -.->|"produces config"| node_domain
node_domain -.->|"holds records"| node_records
node_previewpush -->|"normalizes config"| node_normalize
node_previewpush -->|"creates providers"| node_providerregistry
node_previewpush -.->|"queries zones"| node_dnsproviders
node_dnsproviders -.->|"reads current state"| node_dnsapi
node_previewpush -.->|"checks delegation"| node_registrars
node_registrars -.->|"manages delegation"| node_registrarapi
node_dnsproviders -->|"analyzes changes"| node_diff
node_previewpush -->|"coordinates"| node_corrections
node_corrections -.->|"applies corrections"| node_dnsproviders
node_init -->|"writes credentials"| node_creds
node_init -.->|"imports existing zones"| node_dnsproviders

click node_cli "https://github.com/stackexchange/dnscontrol/blob/main/main.go"
click node_init "https://github.com/stackexchange/dnscontrol/blob/main/commands/init.go"
click node_previewpush "https://github.com/stackexchange/dnscontrol/blob/main/commands/ppreviewPush.go"
click node_jsconfig "https://github.com/stackexchange/dnscontrol/blob/main/pkg/js/js.go"
click node_domain "https://github.com/stackexchange/dnscontrol/blob/main/models/domain.go"
click node_records "https://github.com/stackexchange/dnscontrol/blob/main/models/record.go"
click node_normalize "https://github.com/stackexchange/dnscontrol/blob/main/pkg/normalize/validate.go"
click node_providerregistry "https://github.com/stackexchange/dnscontrol/blob/main/pkg/providers/providers.go"
click node_diff "https://github.com/stackexchange/dnscontrol/blob/main/pkg/diff2/diff2.go"
click node_corrections "https://github.com/stackexchange/dnscontrol/blob/main/commands/ppreviewPush.go"
click node_dnsproviders "https://github.com/stackexchange/dnscontrol/tree/main/providers"
click node_registrars "https://github.com/stackexchange/dnscontrol/tree/main/providers"

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_cli,node_init,node_previewpush toneBlue
class node_jsconfig,node_domain,node_records,node_normalize toneAmber
class node_providerregistry,node_diff,node_corrections,node_dnsapi,node_registrarapi toneMint
class node_dnsproviders,node_registrars toneRose
class node_operator,node_creds toneIndigo
```

## Components

### CLI workflows

- [Command dispatcher](https://github.com/stackexchange/dnscontrol/blob/main/main.go): `main.go`
- [Setup wizard](https://github.com/stackexchange/dnscontrol/blob/main/commands/init.go): `commands/init.go`
- [Preview and push](https://github.com/stackexchange/dnscontrol/blob/main/commands/ppreviewPush.go): `commands/ppreviewPush.go`

### Configuration and records

- [JS configuration](https://github.com/stackexchange/dnscontrol/blob/main/pkg/js/js.go): `pkg/js/js.go`
- [Zone model](https://github.com/stackexchange/dnscontrol/blob/main/models/domain.go): `models/domain.go`
- [DNS records](https://github.com/stackexchange/dnscontrol/blob/main/models/record.go): `models/record.go`
- [Normalize and validate](https://github.com/stackexchange/dnscontrol/blob/main/pkg/normalize/validate.go): `pkg/normalize/validate.go`

### Planning and providers

- [Provider registry](https://github.com/stackexchange/dnscontrol/blob/main/pkg/providers/providers.go): `pkg/providers/providers.go`
- [Change analysis](https://github.com/stackexchange/dnscontrol/blob/main/pkg/diff2/diff2.go): `pkg/diff2/diff2.go`
- [Correction runner](https://github.com/stackexchange/dnscontrol/blob/main/commands/ppreviewPush.go): `commands/ppreviewPush.go`

### Provider services

- [DNS provider adapters](https://github.com/stackexchange/dnscontrol/tree/main/providers): `providers`
- [Registrar adapters](https://github.com/stackexchange/dnscontrol/tree/main/providers): `providers`

### Other components

- **DNS operator**
- **DNS provider APIs**
- **Registrar APIs**
- **Credentials file**

## Connections

- DNS operator → Command dispatcher: runs (evidence: `README.md`)
- Command dispatcher → Preview and push: dispatches (evidence: `main.go`)
- Command dispatcher → Setup wizard: dispatches
- DNS operator → JS configuration: defines zones (evidence: `README.md`)
- JS configuration → Zone model: produces config
- Zone model → DNS records: holds records
- Preview and push → Normalize and validate: normalizes config (evidence: `commands/ppreviewPush.go`)
- Preview and push → Provider registry: creates providers
- Preview and push → DNS provider adapters: queries zones (evidence: `README.md`)
- DNS provider adapters → DNS provider APIs: reads current state (evidence: `README.md`)
- Preview and push → Registrar adapters: checks delegation (evidence: `commands/ppreviewPush.go`)
- Registrar adapters → Registrar APIs: manages delegation
- DNS provider adapters → Change analysis: analyzes changes (evidence: `providers/route53/route53Provider.go`)
- Preview and push → Correction runner: coordinates (evidence: `commands/ppreviewPush.go`)
- Correction runner → DNS provider adapters: applies corrections (evidence: `README.md`)
- Setup wizard → Credentials file: writes credentials (evidence: `README.md`)
- Setup wizard → DNS provider adapters: imports existing zones (evidence: `README.md`)