# acidvegas/mdaxfr architecture

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

- Interactive diagram: https://gitdiagram.com/acidvegas/mdaxfr
- Repository: https://github.com/acidvegas/mdaxfr

## Overview

##### Project type and purpose
- This is a command-line DNS-centric tooling project (full CLI application) whose main purpose is to perform mass DNS zone transfers (AXFR) for single domains, lists of domains, root nameservers, TLDs, and public-suffix TLDs. It also provides a daily scheduled run via GitHub Actions to scan root TLDs and collect results in the `axfrout/` directory.

##### File structure
- Top level:
- `mdaxfr` → the main executable (Go or similar compiled binary).
- `extras/` → auxiliary scripts and data sources (`mdaxfr.py`, `icann_axfr`, `opennic`, `ozones`).
- `axfrout/` → output storage of daily AXFR logs for various servers/TLDs.
- `.github/workflows/daily-axfr.yml` → GitHub Actions workflow to run the tool on a schedule.
- `.screens/preview.gif` → demo animation for the README.
- `README.md`, `LICENSE`.

##### README for additional insights
- The README describes usage patterns (single, batched, GNU Parallel).
- It mentions a Python variant in `extras/`.
- It highlights integration points: DNS resolution, zone transfers, TLD lists from IANA or Public Suffix List, and GitHub Actions for scheduling.

##### Main components and their interactions
a. CLI Frontend (`mdaxfr`)
- Parses arguments (domain, list, flags).
- Reads stdin or file inputs.
b. Nameserver Discovery Module
- For each target domain:
- Resolves NS records.
- Resolves each nameserver to A/AAAA addresses.
c. AXFR Engine
- Attempts zone transfer to each nameserver IP.
- Applies concurrency controls (goroutines or threads).
- Prints or logs successful transfers with full zone data.
d. Output Handler
- Writes raw AXFR logs under `axfrout/` when run via GitHub Actions.
- Writes to stdout when run interactively.
e. Extras Subsystem (`extras/`)
- Python implementation (`mdaxfr.py`) with more advanced concurrency flags.
- Auxiliary zone lists (`icann_axfr`, `opennic`, `ozones`).
f. Automation Layer (GitHub Actions)
- Scheduled cron job defined in `daily-axfr.yml`.
- Invokes `./mdaxfr --tlds` (or similar) against root/TLD list.
- Commits results back to `axfrout/`.

##### Architectural patterns and design principles
- Modular design: Clear separation of CLI input, resolution logic, AXFR logic, and output handling.
- Concurrency pattern: Worker pools or goroutines to parallelize DNS lookups and AXFR attempts.
- Plugin-like “extras” folder for alternative implementations and data sources.
- Infrastructure as code: GitHub Actions manages scheduling and repository state updates.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Automation
    GitHubActions["GitHub Actions Scheduler"]:::automation
    GitHubActions -->|"cron/schedule"| CLI

    %% Core Components
    CLI["CLI Frontend\n(mdaxfr)"]:::internal
    click CLI "https://github.com/acidvegas/mdaxfr/tree/main/mdaxfr"

    CLI -->|"DNS NS query"| Resolver
    Resolver["Resolver Service"]:::internal
    click Resolver "https://github.com/acidvegas/mdaxfr/tree/main/mdaxfr"
    Resolver -->|"A/AAAA queries"| DNS["External DNS Servers"]:::external

    CLI -->|"AXFR request over TCP port 53"| AXFR
    AXFR["AXFR Engine\n(Worker Pool)"]:::internal
    click AXFR "https://github.com/acidvegas/mdaxfr/tree/main/mdaxfr"
    AXFR -->|"AXFR TCP port 53"| DNS
    AXFR -->|"Write zone data"| OutputHandler

    %% Output Handling
    OutputHandler["Output Handler"]:::storage
    OutputHandler -.-> STDOUT["stdout"]:::storage
    OutputHandler -->|"log files"| Logs["axfrout/"]:::storage
    click Logs "https://github.com/acidvegas/mdaxfr/tree/main/axfrout/"

    %% Extras Subsystem
    subgraph "Extras Subsystem"
        ExtrasDir["extras/"]:::automation
        click ExtrasDir "https://github.com/acidvegas/mdaxfr/tree/main/extras/"
        PyCLI["Python CLI variant\n(mdaxfr.py)"]:::internal
        click PyCLI "https://github.com/acidvegas/mdaxfr/blob/main/extras/mdaxfr.py"
        ICANN["ICANN zone list\n(icann_axfr)"]:::external
        click ICANN "https://github.com/acidvegas/mdaxfr/tree/main/extras/icann_axfr"
        OpenNIC["OpenNIC zone list\n(opennic)"]:::external
        click OpenNIC "https://github.com/acidvegas/mdaxfr/tree/main/extras/opennic"
        OZONES["Other zone lists\n(ozones)"]:::external
        click OZONES "https://github.com/acidvegas/mdaxfr/tree/main/extras/ozones"
        ExtrasDir --> PyCLI
        ExtrasDir --> ICANN
        ExtrasDir --> OpenNIC
        ExtrasDir --> OZONES
        PyCLI --> CLI
    end

    %% External Data Sources
    IANA["IANA TLD List"]:::external
    PSL["Public Suffix List"]:::external
    IANA -->|"HTTP fetch"| CLI
    PSL -->|"HTTP fetch"| CLI

    %% Documentation & Demo
    subgraph "Documentation & Demo"
        README["README.md"]:::docs
        click README "https://github.com/acidvegas/mdaxfr/blob/main/README.md"
        Preview[".screens/preview.gif"]:::docs
        click Preview "https://github.com/acidvegas/mdaxfr/blob/main/.screens/preview.gif"
        LICENSE["LICENSE"]:::docs
        click LICENSE "https://github.com/acidvegas/mdaxfr/tree/main/LICENSE"
    end

    %% Styles
    classDef internal fill:#b2f2bb,stroke:#2f8f4b,color:#0f2e0e;
    classDef external fill:#aedcff,stroke:#2b6cb0,color:#072b55;
    classDef storage fill:#e2e3e5,stroke:#6c757d,color:#343a40;
    classDef automation fill:#ffddb5,stroke:#f08c00,color:#663800;
    classDef docs fill:#fef3c7,stroke:#d97706,color:#92400e;
```
