# cnnvito/dnsregion architecture

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

- Interactive diagram: https://gitdiagram.com/cnnvito/dnsregion
- Repository: https://github.com/cnnvito/dnsregion

## Overview

The project in question is a command-line tool written in Go that performs two main actions: (1) it obtains DNS resolution records (using protocols such as DOH (DNS-over-HTTPS) and DOT (DNS-over-TLS)) and (2) it looks up the geographic “归属地” (region) for the resolved IP addresses. In addition, the tool supports simulating DNS resolution from different client regions (EDNS support) via a command-line subcommand, making it easier to diagnose region-specific DNS behavior (for example, for CDN setups).

##### Main Components
- Command-Line Interface (CLI) Layer:
- Represented by “cmd/main.go” and specialized subcommands in the “cmd” directory (e.g., dns.go, edns.go, list.go, base.go).
- This is the entry point of the application that accepts user arguments and chooses the appropriate action.

- DNS Resolution Engine:
- Implementations for handling different DNS protocols live within modules like dns.go and dns_doh.go.
- This component is responsible for making network calls to remote DNS servers over protocols such as DOH and DOT.

- EDNS Simulation Module:
- Contains parts such as “cmd/edns.go” and likely makes use of the “client_subnet.go” file.
- It simulates queries from different client subnets using data located in the “data” folder (e.g., client_ips.json).

- IP Region Lookup Module:
- Handled by “ip_database.go” along with the data file “data/ip2region.xdb”.
- This component maps the resolved IPs to geographical regions.

- Data and Configuration:
- The “data” directory holds essential static resources (client_ips.json and ip2region.xdb) required for lookups.
- Other configuration elements or scripts (e.g., build.sh) are used for deployment or building the project.

- External Dependencies:
- Interaction with external DNS servers and the ip2region database (an external open-source project referenced in the README) is vital.
- Although not explicitly separated in files, this module is implied from the README and file structure.

##### Relationships and Interactions
- The CLI layer collects input and dispatches control to the respective DNS resolution module based on the selected command (dns, edns, list).
- The DNS resolution engine in turn calls out to external DNS servers (via DOH or DOT) to obtain DNS records.
- Once IPs are returned, the IP region lookup module uses the ip2region data to determine the geographic attribution of these IPs.
- When using the EDNS simulation, the tool uses the client subnet data (from the JSON file) to simulate queries from various regions.
- Data flows from the network (via DNS queries) to internal processing (DNS resolution engine) and then through the region lookup module before presenting results to the user.

##### Architectural Patterns and Design Principles
- Modular Command Architecture: Each command (dns, edns, list) is separated into its own file under the “cmd” directory. This promotes ease of extension and clear separation of concerns.
- Separation of Concerns: There is a clear division between command-line input processing, DNS query handling, and regional data lookup.
- Use of External Resources: The system relies on external services (DNS servers, ip2region database) and local data configurations to deliver its functionality.

##### Technologies, Frameworks, or Libraries
- Go language is the primary technology used.
- Built-in or custom modules for DNS querying (handling DOH, DOT, EDNS).
- Integration with ip2region’s data lookup (referenced in the README).
- GitHub workflows are set up for CI/CD, as indicated by the .github/workflows directory.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Input
    User["User"]:::cli

    %% CLI Frontend Subgraph
    subgraph "CLI Frontend"
        cli_main["CLI: Main"]:::cli
        cli_base["CLI: Base"]:::cli
        cli_dns["CLI: DNS Command"]:::cli
        cli_edns["CLI: EDNS Command"]:::cli
        cli_list["CLI: List Command"]:::cli
    end

    %% DNS Resolution Engine Subgraph
    subgraph "DNS Resolution Engine"
        dns_core["DNS Resolution (dns.go)"]:::dns
        dns_doh["DNS DOH Module (dns_doh.go)"]:::dns
    end

    %% EDNS Simulation Module Subgraph
    subgraph "EDNS Simulation Module"
        edns_cmd["EDNS Simulation (cmd/edns.go)"]:::edns
        edns_subnet["Client Subnet (client_subnet.go)"]:::edns
    end

    %% IP Region Lookup Module Subgraph
    subgraph "IP Region Lookup Module"
        ip_db["IP Lookup (ip_database.go)"]:::ip
        ip_data["ip2region Data (data/ip2region.xdb)"]:::ip
    end

    %% Data Resources Subgraph
    subgraph "Data Resources"
        data_ips["Client IPs (data/client_ips.json)"]:::data
    end

    %% External Dependency
    ext_dns["External DNS Servers (DOH/DOT)"]:::ext

    %% Build and Deployment
    subgraph "Build & Deployment"
        build["Build Script (build.sh)"]:::build
        workflow["CI/CD Workflow (.github/workflows/go.yml)"]:::build
    end

    %% Data Flow Connections
    User -->|"CommandInput"| cli_main
    cli_main -->|"Dispatch"| cli_dns
    cli_main -->|"Dispatch"| cli_edns
    cli_main -->|"Dispatch"| cli_list
    cli_main -->|"Prepare Base"| cli_base

    cli_dns -->|"InvokeDNS"| dns_core
    cli_edns -->|"InvokeEDNS"| edns_cmd

    edns_cmd -->|"UseSubnetData"| edns_subnet
    edns_subnet -->|"EnhanceQuery"| dns_core

    dns_core -->|"DNSQuery"| ext_dns
    dns_core -->|"IPLookup"| ip_db
    ip_db -->|"UsesData"| ip_data

    edns_cmd -->|"ReadsSubnetJSON"| data_ips

    %% Styles Definitions
    classDef cli fill:#FCE5CD,stroke:#BF9000,stroke-width:2px;
    classDef dns fill:#C9DAF8,stroke:#1155CC,stroke-width:2px;
    classDef edns fill:#D9EAD3,stroke:#38761D,stroke-width:2px;
    classDef ip fill:#EAD1DC,stroke:#8E3B8E,stroke-width:2px;
    classDef data fill:#FFF2CC,stroke:#C27BA0,stroke-width:2px;
    classDef ext fill:#F4CCCC,stroke:#CC0000,stroke-width:2px;
    classDef build fill:#D0E0E3,stroke:#457A73,stroke-width:2px;

    %% Click Events
    click cli_main "https://github.com/cnnvito/dnsregion/blob/main/cmd/main.go"
    click cli_base "https://github.com/cnnvito/dnsregion/blob/main/cmd/base.go"
    click cli_dns "https://github.com/cnnvito/dnsregion/blob/main/cmd/dns.go"
    click cli_edns "https://github.com/cnnvito/dnsregion/blob/main/cmd/edns.go"
    click cli_list "https://github.com/cnnvito/dnsregion/blob/main/cmd/list.go"
    click dns_core "https://github.com/cnnvito/dnsregion/blob/main/dns.go"
    click dns_doh "https://github.com/cnnvito/dnsregion/blob/main/dns_doh.go"
    click edns_subnet "https://github.com/cnnvito/dnsregion/blob/main/client_subnet.go"
    click ip_db "https://github.com/cnnvito/dnsregion/blob/main/ip_database.go"
    click ip_data "https://github.com/cnnvito/dnsregion/blob/main/data/ip2region.xdb"
    click data_ips "https://github.com/cnnvito/dnsregion/blob/main/data/client_ips.json"
    click build "https://github.com/cnnvito/dnsregion/blob/main/build.sh"
    click workflow "https://github.com/cnnvito/dnsregion/blob/main/.github/workflows/go.yml"
```
