# jeessy2/ddns-go architecture

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

- Interactive diagram: https://gitdiagram.com/jeessy2/ddns-go
- Repository: https://github.com/jeessy2/ddns-go

## Overview

DDNS-GO periodically discovers public IPv4/IPv6 addresses and updates configured DNS records, with a local web interface for setup and monitoring. The graph follows the documented workflow and the sampled scheduler, webhook, and HTTP-auth code; IP discovery, configuration persistence, and individual provider details are represented at their tree-supported module boundaries because their implementations were not sampled.

Main entry points: [`dns/index.go`](https://github.com/jeessy2/ddns-go/blob/master/dns/index.go) (Update scheduler), [`web`](https://github.com/jeessy2/ddns-go/tree/master/web) (Configuration and logs), [`config/webhook.go`](https://github.com/jeessy2/ddns-go/blob/master/config/webhook.go) (Webhook delivery), [`main.go`](https://github.com/jeessy2/ddns-go/blob/master/main.go) (Web server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime orchestration"]
  node_main["Application runtime<br/>[main.go]"]
end

subgraph group_config["Configuration and web UI"]
  node_config_store["Configuration<br/>[config.go]"]
  node_domain_settings["Domain settings<br/>[domains.go]"]
  node_web_server["Web server<br/>[main.go]"]
  node_web_auth["Web access control<br/>[auth.go]"]
  node_web_handlers["Configuration and logs"]
  node_web_ui["Browser interface"]
end

subgraph group_dns["Address and DNS updates"]
  node_scheduler["Update scheduler<br/>[index.go]"]
  node_ip_sources["IP sources<br/>[netInterface.go]"]
  node_ip_cache["IP cache<br/>[ip_cache.go]"]
  node_provider_adapters["DNS providers"]
end

subgraph group_notify["Notifications and integrations"]
  node_webhook_config["Webhook settings<br/>[webhook.go]"]
  node_webhook_delivery["Webhook delivery<br/>[webhook.go]"]
end

node_operator(("Administrator"))
node_dns_services{{"DNS services"}}
node_webhook_target{{"Webhook endpoint"}}

node_operator -->|"opens UI"| node_web_server
node_main -->|"starts timer"| node_scheduler
node_main -->|"starts server"| node_web_server
node_web_server -->|"protects routes"| node_web_auth
node_web_auth -->|"dispatches"| node_web_handlers
node_web_handlers -->|"reads and saves"| node_config_store
node_web_handlers -->|"serves UI"| node_web_ui
node_scheduler -->|"loads settings"| node_config_store
node_scheduler -->|"selects IP source"| node_ip_sources
node_scheduler -->|"passes cache"| node_ip_cache
node_scheduler -->|"dispatches updates"| node_provider_adapters
node_provider_adapters -->|"updates records"| node_dns_services
node_scheduler -->|"reports results"| node_webhook_delivery
node_webhook_delivery -->|"uses settings"| node_webhook_config
node_webhook_delivery -->|"sends request"| node_webhook_target
node_operator -->|"configures"| node_web_handlers
node_domain_settings -->|"defines records"| node_config_store

click node_main "https://github.com/jeessy2/ddns-go/blob/master/main.go"
click node_scheduler "https://github.com/jeessy2/ddns-go/blob/master/dns/index.go"
click node_config_store "https://github.com/jeessy2/ddns-go/blob/master/config/config.go"
click node_domain_settings "https://github.com/jeessy2/ddns-go/blob/master/config/domains.go"
click node_ip_sources "https://github.com/jeessy2/ddns-go/blob/master/config/netInterface.go"
click node_ip_cache "https://github.com/jeessy2/ddns-go/blob/master/util/ip_cache.go"
click node_provider_adapters "https://github.com/jeessy2/ddns-go/tree/master/dns"
click node_web_server "https://github.com/jeessy2/ddns-go/blob/master/main.go"
click node_web_auth "https://github.com/jeessy2/ddns-go/blob/master/web/auth.go"
click node_web_handlers "https://github.com/jeessy2/ddns-go/tree/master/web"
click node_web_ui "https://github.com/jeessy2/ddns-go/tree/master/static"
click node_webhook_config "https://github.com/jeessy2/ddns-go/blob/master/config/webhook.go"
click node_webhook_delivery "https://github.com/jeessy2/ddns-go/blob/master/config/webhook.go"

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_main toneBlue
class node_config_store,node_domain_settings,node_web_server,node_web_auth,node_web_handlers,node_web_ui toneAmber
class node_scheduler,node_ip_sources,node_ip_cache,node_provider_adapters,node_webhook_target toneMint
class node_webhook_config,node_webhook_delivery toneRose
class node_operator,node_dns_services toneIndigo
```

## Components

### Runtime orchestration

- [Application runtime](https://github.com/jeessy2/ddns-go/blob/master/main.go): `main.go`

### Configuration and web UI

- [Configuration](https://github.com/jeessy2/ddns-go/blob/master/config/config.go): `config/config.go`
- [Domain settings](https://github.com/jeessy2/ddns-go/blob/master/config/domains.go): `config/domains.go`
- [Web server](https://github.com/jeessy2/ddns-go/blob/master/main.go): `main.go`
- [Web access control](https://github.com/jeessy2/ddns-go/blob/master/web/auth.go): `web/auth.go`
- [Configuration and logs](https://github.com/jeessy2/ddns-go/tree/master/web): `web`
- [Browser interface](https://github.com/jeessy2/ddns-go/tree/master/static): `static`

### Address and DNS updates

- [Update scheduler](https://github.com/jeessy2/ddns-go/blob/master/dns/index.go): `dns/index.go`
- [IP sources](https://github.com/jeessy2/ddns-go/blob/master/config/netInterface.go): `config/netInterface.go`
- [IP cache](https://github.com/jeessy2/ddns-go/blob/master/util/ip_cache.go): `util/ip_cache.go`
- [DNS providers](https://github.com/jeessy2/ddns-go/tree/master/dns): `dns`

### Notifications and integrations

- [Webhook settings](https://github.com/jeessy2/ddns-go/blob/master/config/webhook.go): `config/webhook.go`
- [Webhook delivery](https://github.com/jeessy2/ddns-go/blob/master/config/webhook.go): `config/webhook.go`

### Other components

- **Administrator**
- **DNS services**
- **Webhook endpoint**

## Connections

- Administrator → Web server: opens UI
- Application runtime → Update scheduler: starts timer
- Application runtime → Web server: starts server
- Web server → Web access control: protects routes
- Web access control → Configuration and logs: dispatches
- Configuration and logs → Configuration: reads and saves
- Configuration and logs → Browser interface: serves UI
- Update scheduler → Configuration: loads settings
- Update scheduler → IP sources: selects IP source
- Update scheduler → IP cache: passes cache
- Update scheduler → DNS providers: dispatches updates
- DNS providers → DNS services: updates records
- Update scheduler → Webhook delivery: reports results
- Webhook delivery → Webhook settings: uses settings
- Webhook delivery → Webhook endpoint: sends request
- Administrator → Configuration and logs: configures
- Domain settings → Configuration: defines records