# fernvenue/adguardhome-upstream architecture

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

- Interactive diagram: https://gitdiagram.com/fernvenue/adguardhome-upstream
- Repository: https://github.com/fernvenue/adguardhome-upstream

## Overview

##### Main Components

a) Core Components:
- AdGuardHome DNS Server
- Upstream Script Component
- Configuration Files System
- Systemd Timer/Service Components
- External DNS Services

b) Data Flow Components:
- dnsmasq-china-list Integration
- DNS Resolution Paths
- Configuration Update Flow

##### Specific Elements

a) Timer/Service Components:
**[upstream.timer] → [upstream.service] → [upstream.sh]**

b) Configuration Flow:
**[dnsmasq-china-list] → [upstream.sh] → [/usr/share/adguardhome.upstream]**

c) DNS Resolution Path:
**[Client] → [AdGuardHome] → [Chinese DNS (for Chinese domains)]**
- → [Global DNS (for other domains)]

##### Important Details to Highlight

- Parallel DNS query capability
- Optimistic caching mechanism
- Domain-based routing logic
- Configuration update automation

##### The separation between Chinese and global DNS resolution paths

This system design should clearly communicate how the project improves DNS resolution speed for Chinese domains while maintaining secure and efficient resolution for global domains, all while being automatically maintained through systemd timers or alternative scheduling systems.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles and Classes
    classDef core fill:#b3d1ff,stroke:#4d88ff
    classDef config fill:#90EE90,stroke:#006400
    classDef external fill:#FFB366,stroke:#CC7A00
    classDef automation fill:#E6B3FF,stroke:#9933FF
    classDef flow fill:#E6E6E6,stroke:#808080

    %% Legend
    subgraph Legend
        L1[Core Components]:::core
        L2[Configuration Files]:::config
        L3[External Services]:::external
        L4[Automation Components]:::automation
        L5[Flow Paths]:::flow
    end

    %% Top Layer - Automation
    subgraph Automation
        Timer[Upstream Timer]:::automation
        Service[Upstream Service]:::automation
        Script[Upstream Script]:::automation
    end
    click Timer "https://github.com/fernvenue/adguardhome-upstream/blob/master/upstream.timer"
    click Service "https://github.com/fernvenue/adguardhome-upstream/blob/master/upstream.service"
    click Script "https://github.com/fernvenue/adguardhome-upstream/blob/master/upstream.sh"

    %% Middle Layer - Configuration
    subgraph Configuration
        Config4[IPv4 Configuration]:::config
        Config6[IPv6 Configuration]:::config
        Config6Only[IPv6-only Configuration]:::config
        DNSMasqList[dnsmasq-china-list]:::external
    end
    click Config4 "https://github.com/fernvenue/adguardhome-upstream/blob/master/v4.conf"
    click Config6 "https://github.com/fernvenue/adguardhome-upstream/blob/master/v6.conf"
    click Config6Only "https://github.com/fernvenue/adguardhome-upstream/blob/master/v6only.conf"

    %% Bottom Layer - DNS Services
    subgraph "DNS Services"
        AGHome[AdGuardHome DNS Server]:::core
        ChineseDNS[Chinese DNS Servers]:::external
        GlobalDNS[Global DNS Servers]:::external
    end

    %% Relationships
    Timer -->|"Triggers Daily (5 AM)"| Service
    Service --> Script
    Script -->|Updates| Config4
    Script -->|Updates| Config6
    Script -->|Updates| Config6Only
    DNSMasqList -.->|Provides Domain List| Script
    Config4 --> AGHome
    Config6 --> AGHome
    Config6Only --> AGHome
    AGHome -->|Chinese Domains| ChineseDNS
    AGHome -->|Global Domains| GlobalDNS

    %% Client Flow
    Client[Client]:::flow
    Client -->|DNS Queries| AGHome

    %% Notes
    classDef note fill:#fff,stroke:#999
    Note1[Optimistic Caching]:::note
    Note2[Parallel DNS Queries]:::note
    Note1 --- AGHome
    Note2 --- AGHome
```
