# briankohler/dnsapi architecture

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

- Interactive diagram: https://gitdiagram.com/briankohler/dnsapi
- Repository: https://github.com/briankohler/dnsapi

## Overview

Based on our analysis of the file tree and README, this project is a containerized, full-stack DNS management service. Its core purpose is to expose a REST API (written in Go) to manage TinyDNS zone files, which are subsequently served via the TinyDNS service fronted by an Unbound caching resolver. Consul is used as the persistent data store (and, optionally, as a FUSE-backed filesystem for the zonefile), and there is optional integration with S3 for versioning and backup.

- DNS API Service: Represented by the “dnsapi” container which contains the Go source (organized in subdirectories such as “dnsapi”, “consulhelper”, “helper”, “log”, and “logmiddleware”). This component accepts REST calls (on port 9080) and implements business logic for record manipulation.
- TinyDNS Service: Represented by the “tinydns” container (with its own Dockerfile, configuration, and start script). It is responsible for serving the DNS zone files generated/updated by the API.
- Unbound DNS Resolver: Represented by the “unbound” container. It is used as a caching DNS resolver and listens on port 53.
- Persistent Data Store (Consul): Shown as an external or auxiliary component (backed by the “consuldata” directory), which is used by the API to persist DNS data. Optionally, this is also involved in providing a FUSE-backed filesystem to the TinyDNS service when the experimental USE_CONSULFS flag is set.
- Optional Components:
- DNS Dummper: There is a “dnsapidumper” service that appears designed to dump or backup zone file information.
- S3 Backup: Indicate that when provided AWS credentials and the S3_BUCKET environment variable, the tiny datafile can be backed-up/versioned with Git and S3.

##### Relationships and Interactions
- REST Client (or even a cURL command, as shown in the README) interacts with the DNS API service.
- The DNS API service processes requests (e.g., creating, updating, or deleting A, NS, CNAME, SOA records) and interacts with Consul for persistent storage.
- When records are changed, the API updates the TinyDNS zonefile (and possibly uses the “dnsapidumper” to reflect those changes).
- The TinyDNS service, in its container, reads and serves the updated zonefile.
- Unbound operates on top of every change as a caching front-end, effectively serving DNS requests based on the latest zonefile.
- Optional: When configured, S3 integration backs up versioned zonefiles, and the experimental FUSE-based mounting (with USE_CONSULFS) changes how the zonefile is accessed by TinyDNS.

##### Architectural Patterns and Design Principles
- Modular Separation: The Go application is neatly segmented into packages managing different responsibilities (record handling, logging, and Consul integration).
- Containerization: All services (API, TinyDNS, Unbound) are containerized (Dockerfiles are provided) and orchestrated with a docker-compose.yml file.
- Service Interaction: The use of environment variables (like USE_CONSULFS and S3_BUCKET) and external configuration files points to a design that emphasizes flexible deployment.

##### Technologies, Frameworks, and Libraries
- Go language for building the API.
- Docker for containerization (each service has its own Dockerfile).
- Docker Compose for service orchestration.
- Consul for persistence and as an experimental FUSE filesystem backend.
- Unbound DNS caching resolver.
- TinyDNS for generating/serving zone files.
- (Optionally) AWS S3 for file versioning and backup combined with Git-versioning.

##### Final Reminder to the Principal Software Engineer
- Every major component (API, TinyDNS, Unbound, Consul/S3) is clearly labeled.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top-level nodes
    REST["REST Client (cURL)"]:::client

    subgraph "DNS API Service Components"
        direction TB
        api["DNS API Service\n(port 9080)"]:::container
        subgraph "Internal Modules"
            direction TB
            a1["dnsapi"]:::module
            a2["consulhelper"]:::module
            a3["helper"]:::module
            a4["log"]:::module
            a5["logmiddleware"]:::module
        end
        dumper["dnsapidumper (Optional)"]:::optional
        %% Internal communication within API service
        api -->|"triggerDump"| dumper
    end

    consul["Consul (Persistent Data Store)"]:::database
    tinydns["TinyDNS Service"]:::container
    unbound["Unbound DNS Resolver\n(port 53)"]:::container
    s3["S3 Backup (Optional)"]:::optional

    %% External interactions
    REST -->|"HTTP_Request"| api
    api -->|"Store/UpdateZonefile"| consul
    api -->|"UpdateZonefile"| tinydns
    tinydns -->|"ServeZonefile"| unbound
    tinydns -->|"Backup"| s3
    consul -->|"FUSE_mount(Optional)"| tinydns

    %% Click Events
    click api "https://github.com/briankohler/dnsapi/tree/master/dnsapi/"
    click tinydns "https://github.com/briankohler/dnsapi/tree/master/tinydns/"
    click unbound "https://github.com/briankohler/dnsapi/tree/master/unbound/"
    click consul "https://github.com/briankohler/dnsapi/tree/master/consuldata/"
    click dumper "https://github.com/briankohler/dnsapi/tree/master/dnsapi/dnsapidumper/"

    %% Styles
    classDef client fill:#f4d03f,stroke:#aa8800,stroke-width:2px,color:#000
    classDef container fill:#aed6f1,stroke:#21618c,stroke-width:2px
    classDef module fill:#d6eaf8,stroke:#2874a6,stroke-width:1px
    classDef database fill:#abebc6,stroke:#186a3b,stroke-width:2px
    classDef optional fill:#f5b7b1,stroke:#943126,stroke-width:2px
```
