# zebradil/cloudflare-dynamic-dns architecture

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

- Interactive diagram: https://gitdiagram.com/zebradil/cloudflare-dynamic-dns
- Repository: https://github.com/zebradil/cloudflare-dynamic-dns

## Overview

##### Main Components
- CLI Entry Point: Represent the main executable (main.go) which wires up the application.
- Command Modules: Under the “cmd” directory, include components like “cloudflare.go”, “ip.go”, and “cmd.go” that parse command line arguments and configure the operation mode (manual run vs. daemon mode).
- Configuration Layer: Show how configuration is loaded from various sources such as command line flags, a YAML configuration file (default location in $HOME), and environment variables.
- IP Address Detection Module: Highlight the process of obtaining the current IP address. This includes:
– Directly reading from a specified network interface.
– Running an external command (via functions in the internal/execext package) to fetch the IP.
- Cloudflare API Client: Represent the component that constructs and sends HTTP requests to Cloudflare’s API to update DNS records based on the detected IP.
- State Management: Include how the state file (if enabled) is used to avoid unnecessary API calls by persisting the last used IP.
- Deployment & Automation Components:
- Build & Release: Optionally include supporting scripts and configuration files (goreleaser configuration, Taskfile.yaml) that manage the building, releasing, and dependency management.

##### Relationships and Data Flow
- Processing Layer: Show the command module invoking the IP detection module. Clarify how the tool processes the selection rules for both IPv4 and IPv6.
- API Interaction: Illustrate that the processed IP is then used by the Cloudflare API client to make REST calls to update DNS records.
- Feedback/State Update: Show that, on success, the state file gets updated to store the current IP, preventing redundant Cloudflare API calls.

##### Important Architectural Patterns
- Modularity: Each functionality (command parsing, IP detection, API interaction) is separated into distinct modules (e.g., located in “cmd” and “internal” directories).
- Configuration Abstraction: The design supports multiple configuration mechanisms, making the tool flexible and deployable in different environments (manual run, Docker, systemd).
- Daemon vs. One-shot: Emphasize the dual mode of execution; the flow branches in daemon mode where a scheduler (systemd or --run-every in manual invocation) repeatedly invokes the tool.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% High-Level Cloudflare Dynamic DNS Client
    subgraph "Cloudflare Dynamic DNS Client"
        %% Configuration Layer
        subgraph "Configuration Layer"
            A["CLI Arguments"]:::config
            B["Environment Variables"]:::config
        end

        %% Core Processing Layer
        subgraph "Core Processing"
            C["CLI Entry Point (main.go)"]:::core
            subgraph "Command Modules"
                D["Cloudflare Handler (cmd/cloudflare.go)"]:::core
                E["Command Dispatcher (cmd/cmd.go)"]:::core
                F["IP Command (cmd/ip.go)"]:::core
            end
        end

        %% Processing Modules
        subgraph "Processing Modules"
            G["IP Address Detection Module"]:::core
            subgraph "External Execution Module (internal/execext)"
                H["Exec Module (exec.go)"]:::core
                I["DevNull Handler (devnull.go)"]:::core
            end
            J["Cloudflare API Client"]:::core
        end

        %% State Management
        K["State Manager"]:::core
    end

    %% Deployment & Automation Components
    subgraph "Deployment & Automation"
        L["Docker Container (Dockerfile)"]:::external
        M["Docker Development (dev.Dockerfile)"]:::external
        N["systemd Service Unit (systemd/cloudflare-dynamic-dns@.service)"]:::external
        O["systemd Timer Unit (systemd/cloudflare-dynamic-dns@.timer)"]:::external
        P1["Build & Release (.goreleaser.yml)"]:::external
        P2["Build & Release (Taskfile.yaml)"]:::external
    end

    %% Relationships - Configuration to Entry Point
    A -->|"configures"| C
    B -->|"configures"| C

    %% Entry Point invoking Command Modules
    C -->|"invokes"| D
    C -->|"invokes"| E
    C -->|"invokes"| F

    %% IP Module Triggering IP Detection Process
    F -->|"selects"| G

    %% IP Detection executing External Command methods
    G -->|"executes"| H
    G -->|"executes"| I

    %% Cloudflare API Update Workflow
    D -->|"callsAPI"| J
    J -->|"updates"| K

    %% Deployment & Automation triggering the Core Processing
    L -->|"triggers"| C
    M -->|"triggers"| C
    N -->|"schedules"| C
    O -->|"triggers"| C
    P1 -->|"builds"| C
    P2 -->|"builds"| C

    %% Click Events
    click C "https://github.com/zebradil/cloudflare-dynamic-dns/blob/main/main.go"
    click D "https://github.com/zebradil/cloudflare-dynamic-dns/blob/main/cmd/cloudflare.go"
    click E "https://github.com/zebradil/cloudflare-dynamic-dns/blob/main/cmd/cmd.go"
    click F "https://github.com/zebradil/cloudflare-dynamic-dns/blob/main/cmd/ip.go"
    click H "https://github.com/zebradil/cloudflare-dynamic-dns/blob/main/internal/execext/exec.go"
    click I "https://github.com/zebradil/cloudflare-dynamic-dns/blob/main/internal/execext/devnull.go"
    click L "https://github.com/zebradil/cloudflare-dynamic-dns/tree/main/Dockerfile"
    click M "https://github.com/zebradil/cloudflare-dynamic-dns/blob/main/dev.Dockerfile"
    click N "https://github.com/zebradil/cloudflare-dynamic-dns/blob/main/systemd/cloudflare-dynamic-dns@.service"
    click O "https://github.com/zebradil/cloudflare-dynamic-dns/blob/main/systemd/cloudflare-dynamic-dns@.timer"
    click P1 "https://github.com/zebradil/cloudflare-dynamic-dns/blob/main/.goreleaser.yml"
    click P2 "https://github.com/zebradil/cloudflare-dynamic-dns/blob/main/Taskfile.yaml"

    %% Styles
    classDef config fill:#fde2e2,stroke:#aa0000,stroke-width:2px;
    classDef core fill:#e2f0cb,stroke:#4a7c59,stroke-width:2px;
    classDef external fill:#cff4fc,stroke:#0a9396,stroke-width:2px;
```
