# timothymiller/cloudflare-ddns architecture

> Architecture diagram of the GitHub repository timothymiller/cloudflare-ddns, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/timothymiller/cloudflare-ddns
- Repository: https://github.com/timothymiller/cloudflare-ddns

## Overview

##### Project type and purpose
- This is a small self-hosted Python service (“cloudflare-ddns.py”) that periodically reads a JSON configuration, checks your public IPv4/IPv6 addresses, and updates DNS records in Cloudflare via its HTTP API.
- It’s designed to run in various environments (bare-metal with cron or systemd, Docker container, Docker Compose, or Kubernetes).

##### File structure
- Top-level
- cloudflare-ddns.py: main application script
- config-example.json: sample user configuration
- requirements.txt: Python dependencies (zero-dependency, likely only standard library / HTTP client)
- start-sync.sh: bootstraps a Python venv and runs the script
- Dockerfile: builds a minimal container image
- Deployment folders
- docker/: docker-compose.yml for single-host Docker Compose
- k8s/: Kubernetes Deployment / Secret template
- systemd/: .service and .timer files for systemd scheduling
- scripts/: helper scripts for building, publishing, and running Docker images
- GitHub CI/CD workflows under .github/workflows/image.yml, plus issue templates and Dependabot config

##### README
- Describes feature set (IPv4/IPv6, subdomains, load-balancing, caching)
- Explains configuration schema for zones, authentication, TTL, purge options
- Shows four run-modes:
a. Linux + cron (via start-sync.sh)
b. systemd + timer
c. Docker / Docker Compose
d. Kubernetes (Secret + Deployment)
- Mentions environment variable support and multi-arch Docker builds

a. Main components
- Scheduler / Runner (cron job, systemd timer, or k8s CronJob / Deployment with built-in loop)
- Python Runtime (cloudflare-ddns.py inside a venv or container)
- Configuration Store (config.json mounted as a file or provided as a Kubernetes Secret)
- Local Cache (in-memory or file cache of recent API responses)
- Cloudflare API (external HTTP service)
- (Optional) Docker Host or Kubernetes Cluster orchestrator
b. Relationships and interactions
1. Scheduler triggers the Python script at configured intervals
2. Script loads config.json / environment variables
3. Script reads current public IP(s) via local interface or external endpoint (e.g., cdn-cgi/trace)
4. Script compares against cached value; if changed or purgeUnknownRecords=true, it issues HTTP requests to Cloudflare API to update DNS records
5. Cloudflare API responds; script updates cache
6. Logs or metrics can be emitted to stdout (Docker logs), systemd journal, or Kubernetes logs
c. Architectural patterns / design principles
- Single responsibility: one script does configuration parsing, caching, IP detection, API updates
- Config-driven behavior: all credentials, zones, subdomains, and TTLs defined in JSON or environment variables
- Adapter pattern: can run under different schedulers without changing core logic
- Zero-trust container: runs with host networking (in Docker), minimal privileges, file-based config or Kubernetes Secret
d. Key technologies and frameworks
- Python 3.5+ (stdlib HTTP or requests)
- Docker (small Alpine‐based image)
- Docker Compose (network_mode: host)
- Kubernetes Deployment & Secret
- systemd service & timer units
- Bash scripts for building and orchestrating
- Cloudflare HTTP REST API

##### Details
- Call out authentication flow: API token or API key + email → attached as HTTP header
- Polling interval (e.g., every 15 minutes via cron or timer)
- Optional load-balancing logic path if configured (creates CNAME pools via API)
- If desired, annotate the Dockerfile layer breakdown (base image, application layer, entrypoint)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Bare-metal Environment
    subgraph "Bare-metal Environment"
        direction TB
        Cron["Cron Job"]:::local
        Timer["systemd Timer"]:::local
        Service["systemd Service"]:::local
        Cron -->|"every 15min"| Service
        Timer -->|triggers| Service
        Service -->|"executes"| PythonVM["Python venv"]:::app
        click PythonVM "https://github.com/timothymiller/cloudflare-ddns/blob/master/cloudflare-ddns.py"
        click Cron "https://github.com/timothymiller/cloudflare-ddns/blob/master/start-sync.sh"
        click Service "https://github.com/timothymiller/cloudflare-ddns/blob/master/systemd/cloudflare-ddns.service"
        click Timer "https://github.com/timothymiller/cloudflare-ddns/blob/master/systemd/cloudflare-ddns.timer"
        PythonVM -->|"reads"| ConfigBM["config-example.json"]:::storage
        click ConfigBM "https://github.com/timothymiller/cloudflare-ddns/blob/master/config-example.json"
        PythonVM -->|"reads/writes"| CacheBM["Local Cache"]:::storage
    end

    %% Docker Environment
    subgraph "Docker Environment"
        direction TB
        Host["Docker Host"]:::local
        Host -->|"docker run"| Container["DDNS Container"]:::app
        click Container "https://github.com/timothymiller/cloudflare-ddns/tree/master/Dockerfile"
        Container -->|"mounts"| ConfigDC["config-example.json"]:::storage
        click ConfigDC "https://github.com/timothymiller/cloudflare-ddns/blob/master/config-example.json"
        Container -->|"uses deps from"| Req["requirements.txt"]:::storage
        click Req "https://github.com/timothymiller/cloudflare-ddns/blob/master/requirements.txt"
        Container -->|"reads/writes"| CacheDC["Local Cache"]:::storage
        click Host "https://github.com/timothymiller/cloudflare-ddns/blob/master/docker/docker-compose.yml"
    end

    %% Kubernetes Environment
    subgraph "Kubernetes Cluster"
        direction TB
        K8sCluster["K8s Cluster"]:::local
        Secret["K8s Secret"]:::storage
        click Secret "https://github.com/timothymiller/cloudflare-ddns/blob/master/k8s/cloudflare-ddns.yml"
        Deployment["Deployment (CronJob)"]:::app
        K8sCluster --> Secret
        K8sCluster --> Deployment
        Deployment -->|"mounts"| Secret
        Deployment -->|"runs"| Pod["Pod"]:::app
        Pod -->|"reads/writes"| CacheK8s["Local Cache"]:::storage
    end

    %% Shared external interactions
    PythonVM -->|"GET public IP"| IP["External IP Endpoint"]:::external
    Container -->|"GET public IP"| IP
    Pod -->|"GET public IP"| IP
    PythonVM -->|"PATCH DNS record"| CFAPI["Cloudflare API"]:::external
    Container -->|"PATCH DNS record"| CFAPI
    Pod -->|"PATCH DNS record"| CFAPI

    %% CI/CD and Scripts
    subgraph "Supporting Tools"
        direction TB
        Scripts["scripts/"]:::tool
        click Scripts "https://github.com/timothymiller/cloudflare-ddns/tree/master/scripts/"
        DSC1["docker-build.sh"]:::tool
        click DSC1 "https://github.com/timothymiller/cloudflare-ddns/blob/master/scripts/docker-build.sh"
        DSC2["docker-build-all.sh"]:::tool
        click DSC2 "https://github.com/timothymiller/cloudflare-ddns/blob/master/scripts/docker-build-all.sh"
        DSP["docker-publish.sh"]:::tool
        click DSP "https://github.com/timothymiller/cloudflare-ddns/blob/master/scripts/docker-publish.sh"
        DSR["docker-run.sh"]:::tool
        click DSR "https://github.com/timothymiller/cloudflare-ddns/blob/master/scripts/docker-run.sh"
        CI["GitHub Actions Workflow"]:::tool
        click CI "https://github.com/timothymiller/cloudflare-ddns/blob/master/.github/workflows/image.yml"
        DB["Dependabot Config"]:::tool
        click DB "https://github.com/timothymiller/cloudflare-ddns/blob/master/.github/dependabot.yml"
    end

    %% Styles
    classDef local fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef app fill:#d4edda,stroke:#333,stroke-width:1px
    classDef storage fill:#e2e3e5,stroke:#333,stroke-width:1px
    classDef external fill:#ffe5b4,stroke:#333,stroke-width:1px
    classDef tool fill:#f0f0f0,stroke:#333,stroke-width:1px
```
