# vvm2/shiddns architecture

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

- Interactive diagram: https://gitdiagram.com/vvm2/shiddns
- Repository: https://github.com/vvm2/shiddns

## Overview

##### Core Components
- DNS Server (Main Service)
- Configuration Manager
- Message Parser/Handler
- Filter System
- Local DNS Resolver
- Upstream DNS Forwarder

##### External Components
- Upstream DNS Server (e.g., 1.1.1.1)
- Block List Sources
- Client DNS Queries

##### Main Service Layer
- UDP Socket Listener (port configurable)
- Message Processing Pipeline
- Control File Monitor (IPC mechanism)

##### Resolution Flow
a. Incoming DNS Query → Message Parser
b. Message Parser → Filter System
c. Filter System → Local DNS Resolver
d. Local DNS Resolver → Upstream DNS Forwarder (if local resolution fails)
e. Response Path back to Client

##### Configuration and Storage
- Local DNS Entries
- Filter Rules
- Network Settings
- Service Settings

##### Filter System Detail
- Block Lists Storage
- Allow Lists Storage
- Regular Expression Patterns
- Filter Rules Processor

- Blue: Core DNS components
- Green: Local DNS resolution components
- Red: Filtering and blocking components
- Gray: External services/components
- Yellow: Configuration elements

Specific Implementation Details to Highlight:

##### Message Flow
**Client Query → UDP Socket**
- → Message Parser
- → Filter Check
- → Resolution (Local/Upstream)
- → Response Generation
- → Client Response

##### Control Flow
**Control File → Service Commands**
- → Filter Refresh
- → Configuration Reload

##### Separation between local and upstream resolution paths

- Data flow directions
- Component types
- Configuration dependencies
- Security boundaries
- Filter processing paths

Level of Detail:
##### Local DNS Resolution Process

This will provide a comprehensive view of the system while maintaining clarity at each level of abstraction.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Client Layer"
        Client["Client DNS Query"]
    end

    subgraph "Main Service Layer"
        DNS["DNS Server"]:::core
        click DNS "https://github.com/vvm2/shiddns/blob/main/dns.py"
        Parser["Message Parser"]:::core
        click Parser "https://github.com/vvm2/shiddns/blob/main/message.py"
        ConfigMgr["Configuration Manager"]:::config
        click ConfigMgr "https://github.com/vvm2/shiddns/blob/main/config.json"
    end

    subgraph "Resolution Layer"
        LocalDNS["Local DNS Resolver"]:::resolver
        UpstreamDNS["Upstream DNS Forwarder"]:::resolver
    end

    subgraph "Filter System"
        FilterSystem["Filter Processor"]:::filter
        click FilterSystem "https://github.com/vvm2/shiddns/tree/main/sample/block_rx"
        BlockLists["Block Lists"]:::storage
        AllowLists["Allow Lists"]:::storage
        RegexPatterns["Regex Patterns"]:::storage
    end

    subgraph "Configuration"
        Config["Service Configuration"]:::config
        click Config "https://github.com/vvm2/shiddns/blob/main/sample/config.json"
        NetworkSettings["Network Settings"]:::config
        LocalEntries["Local DNS Entries"]:::config
    end

    subgraph "External Services"
        UpstreamServer["Upstream DNS Server\n(e.g., 1.1.1.1)"]:::external
    end

    %% Connections
    Client --> DNS
    DNS --> Parser
    Parser --> FilterSystem
    FilterSystem --> LocalDNS
    LocalDNS --> UpstreamDNS
    UpstreamDNS --> UpstreamServer
    
    %% Configuration Connections
    Config -.-> DNS
    Config -.-> FilterSystem
    NetworkSettings -.-> DNS
    LocalEntries -.-> LocalDNS
    
    %% Filter System Connections
    BlockLists --> FilterSystem
    AllowLists --> FilterSystem
    RegexPatterns --> FilterSystem
    
    %% Return Path
    UpstreamServer --> UpstreamDNS
    UpstreamDNS --> LocalDNS
    LocalDNS --> FilterSystem
    FilterSystem --> Parser
    Parser --> DNS
    DNS --> Client

    %% Styles
    classDef core fill:#3498db,stroke:#2980b9,color:white
    classDef resolver fill:#2ecc71,stroke:#27ae60,color:white
    classDef filter fill:#e74c3c,stroke:#c0392b,color:white
    classDef config fill:#f1c40f,stroke:#f39c12,color:black
    classDef storage fill:#95a5a6,stroke:#7f8c8d,color:white
    classDef external fill:#bdc3c7,stroke:#95a5a6,color:black

    %% Legend
    subgraph Legend
        L1["Core Components"]:::core
        L2["Resolution Components"]:::resolver
        L3["Filter Components"]:::filter
        L4["Configuration"]:::config
        L5["Storage"]:::storage
        L6["External Services"]:::external
    end
```
