# bernoussama/mercury architecture

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

- Interactive diagram: https://gitdiagram.com/bernoussama/mercury
- Repository: https://github.com/bernoussama/mercury

## Overview

##### Main Components
- DNS Request Handler: Incoming DNS queries are received, likely through the entry point defined in cmd/serve.go.
- DNS Module: The core logic resides in the "dns" package (dns/dns.go and associated utility functions). This module handles query parsing, processing, and forming responses.
- Cache System: The "cache" package (cache/cache.go) is responsible for caching DNS query results, reducing the number of external requests.
- Zones Loader/Processor: The "zones" directory (with zone files like example.com.yml) represents authoritative zones. Mercury checks these configurations to provide authoritative answers.
- Recursive Resolver: A key feature whereby Mercury, if a query isn’t answered locally, will perform a recursive lookup using the Internet’s root servers.
- DNS Sinkhole: Although not a separate package, this capability is integrated into query processing logic to block or filter domains (for ad-blocking).
- Infrastructure & Deployment: Configuration files like Dockerfile, compose.yaml, and dev_compose.yaml indicate that Mercury is containerized and can be deployed using Docker or systemd.

##### Relationships and Interactions
- Incoming Client Requests: DNS queries arrive via UDP/TCP on configured ports (as defined in the Docker compose service and possibly in the Dockerfile).
- Request Routing: The main entry (main.go, cmd/root.go, and cmd/serve.go) dispatches queries to the dns package.
- Decision Branching: Within the DNS module, a decision is made:
- If the query matches a zone defined in the "zones" folder, handle it as an authoritative lookup.
- If not, pass the request to the recursive resolver to contact external root servers.
- Additionally, check if the requested domain should be sinkholed.
- Cache Usage: Before external resolution, check the cache module to see if the answer is already stored. After processing, update the cache accordingly.
- Concurrency: Parallel handling of queries is integrated into the design so that multiple clients can be serviced concurrently.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Each main function is clearly subdivided into independent modules (e.g., DNS processing, caching, zone management).
- Modular Design: The clear directory structure (cmd, dns, cache, zones) keeps logic isolated and encourages reusability.
- Containerization: Use of Dockerfiles and Compose files shows the project is designed to be easily deployed in containerized environments.
- Configuration Driven: The external configuration (zone files, Docker compose) allows dynamic modification without changing the core code.

##### Incorporate Relevant Technologies
- Go as the primary language – noted by the main.go and other .go files.
- Docker: Emphasized by Dockerfile, compose.yaml, and dev_compose.yaml for deployment.
- CI/CD Workflows: GitHub Actions workflows (.github/workflows) indicate automated build and release pipelines, which are essential for continuous integration but typically outside the core system architecture.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["DNS Request Handler / Entry Point"]:::internal
    B["DNS Processor Module"]:::internal
    C["Cache Module"]:::internal
    D["Authoritative Zone Manager"]:::internal
    E["Recursive Resolver"]:::internal
    F["Internet Root Servers"]:::external
    G["DNS Sinkhole Logic"]:::internal

    subgraph "Infrastructure & Deployment"
        H["Dockerfile"]:::deployment
        I["compose.yaml"]:::deployment
        J["dev_compose.yaml"]:::deployment
    end

    A -->|"dispatch"| B
    B -->|"check_cache"| C
    B -->|"zone_lookup"| D
    B -->|"recursive_lookup"| E
    B -->|"sinkhole_check"| G
    E -->|"external_query"| F
    E -->|"cache_update"| C

    click A "https://github.com/bernoussama/mercury/blob/main/cmd/serve.go"
    click B "https://github.com/bernoussama/mercury/blob/main/dns/dns.go"
    click C "https://github.com/bernoussama/mercury/blob/main/cache/cache.go"
    click D "https://github.com/bernoussama/mercury/tree/main/zones"
    click H "https://github.com/bernoussama/mercury/tree/main/Dockerfile"
    click I "https://github.com/bernoussama/mercury/blob/main/compose.yaml"
    click J "https://github.com/bernoussama/mercury/blob/main/dev_compose.yaml"

    classDef internal fill:#bbf,stroke:#333,stroke-width:2px;
    classDef external fill:#f88,stroke:#800,stroke-width:2px;
    classDef deployment fill:#afa,stroke:#090,stroke-width:2px;
```
