# serverless-dns/serverless-dns architecture

> Architecture diagram of the GitHub repository serverless-dns/serverless-dns, 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/serverless-dns/serverless-dns
- Repository: https://github.com/serverless-dns/serverless-dns

## Overview

##### Main System Components

a) Entry Points (Multiple Runtimes):
- Cloudflare Workers (server-workers.js)
- Deno Deploy (server-deno.ts)
- Fastly Compute@Edge (server-fastly.js)
- Node.js/Fly.io (server-node.js)

b) Core Components:
- DNS Handler (core/doh.js)
- Plugin System (core/plugin.js)
- Configuration Management (core/cfg.js)
- Environment Management (core/env.js)

c) Plugin Chain:

##### Architectural Patterns to Highlight

a) Multi-Platform Architecture:
- How the system adapts to different cloud platforms
- Platform-specific configurations
- Demonstrate shared core functionality

b) Plugin System:
- Plugin chain flow
- How plugins interact with core components
- Extensibility points

##### Important Elements

a) Storage Components:
- Cache implementations (platform-specific)
- Blocklist storage (Cloudflare R2)
- In-memory LFU cache

b) External Services:
- Upstream DNS resolvers
- Blocklist sources
- Analytics/Logging systems

##### Specific Implementation Details

- Runtime environments (Workers, Deno, Node.js, Fastly)
- Core components vs Plugins
- Synchronous vs Asynchronous operations
- Platform-specific implementations

##### External Service Layer (Upstream DNS, Storage, Analytics)

Remember to maintain a balance between detail and clarity, focusing on the serverless nature of the system while showing how it maintains state and handles DNS operations across different cloud platforms.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Client Layer"
        Client["DNS Clients"]
    end

    subgraph "Platform Layer"
        CF["Cloudflare Workers"]:::platform
        Deno["Deno Deploy"]:::platform
        Fastly["Fastly Compute@Edge"]:::platform
        Node["Node.js/Fly.io"]:::platform
    end

    subgraph "Core Service Layer"
        DNS["DNS Handler"]:::core
        Plugin["Plugin System"]:::core
        Config["Configuration Management"]:::core
        Env["Environment Management"]:::core
        Log["Logging System"]:::core
        Svc["Service Core"]:::core
    end

    subgraph "Platform Config"
        CFConfig["Cloudflare Config"]:::config
        DenoConfig["Deno Config"]:::config
        FastlyConfig["Fastly Config"]:::config
        NodeConfig["Node Config"]:::config
    end

    subgraph "Plugin Layer"
        Users["User Operations"]:::plugin
        Cache["Cache Resolution"]:::plugin
        CC["Command Control"]:::plugin
        Resolver["DNS Resolution"]:::plugin
        Blocker["Blocklist Implementation"]:::plugin
        CacheImpl["Cache Implementation"]:::plugin
    end

    subgraph "DNS Operations"
        DNSTrans["DNS Transactions"]:::dns
        DNSConn["DNS Connections"]:::dns
        DNSOp["DNS Operations"]:::dns
    end

    subgraph "External Layer"
        UpDNS["Upstream DNS"]:::external
        Storage["Storage (R2/Cache)"]:::external
        Analytics["Analytics"]:::external
    end

    Client --> CF & Deno & Fastly & Node
    CF & Deno & Fastly & Node --> DNS
    DNS --> Plugin
    Plugin --> Users --> Cache --> CC --> Resolver
    Resolver --> DNSOp
    DNSOp --> DNSTrans
    DNSTrans --> DNSConn
    DNSConn --> UpDNS
    
    CF --> CFConfig
    Deno --> DenoConfig
    Fastly --> FastlyConfig
    Node --> NodeConfig
    
    Resolver --> Blocker
    Cache --> CacheImpl
    CacheImpl --> Storage
    Log --> Analytics

    %% Click Events
    click CF "https://github.com/serverless-dns/serverless-dns/blob/main/src/server-workers.js"
    click Deno "https://github.com/serverless-dns/serverless-dns/blob/main/src/server-deno.ts"
    click Fastly "https://github.com/serverless-dns/serverless-dns/blob/main/src/server-fastly.js"
    click Node "https://github.com/serverless-dns/serverless-dns/blob/main/src/server-node.js"
    click DNS "https://github.com/serverless-dns/serverless-dns/blob/main/src/core/doh.js"
    click Plugin "https://github.com/serverless-dns/serverless-dns/blob/main/src/core/plugin.js"
    click Config "https://github.com/serverless-dns/serverless-dns/blob/main/src/core/cfg.js"
    click Env "https://github.com/serverless-dns/serverless-dns/blob/main/src/core/env.js"
    click Users "https://github.com/serverless-dns/serverless-dns/tree/main/src/plugins/users"
    click Cache "https://github.com/serverless-dns/serverless-dns/blob/main/src/plugins/dns-op/cache-resolver.js"
    click CC "https://github.com/serverless-dns/serverless-dns/blob/main/src/plugins/command-control/cc.js"
    click Resolver "https://github.com/serverless-dns/serverless-dns/blob/main/src/plugins/dns-op/resolver.js"
    click CFConfig "https://github.com/serverless-dns/serverless-dns/blob/main/src/core/workers/config.js"
    click DenoConfig "https://github.com/serverless-dns/serverless-dns/blob/main/src/core/deno/config.ts"
    click FastlyConfig "https://github.com/serverless-dns/serverless-dns/blob/main/src/core/fastly/config.js"
    click NodeConfig "https://github.com/serverless-dns/serverless-dns/blob/main/src/core/node/config.js"
    click DNSTrans "https://github.com/serverless-dns/serverless-dns/blob/main/src/core/dns/transact.js"
    click DNSConn "https://github.com/serverless-dns/serverless-dns/blob/main/src/core/dns/conns.js"
    click DNSOp "https://github.com/serverless-dns/serverless-dns/blob/main/src/plugins/dns-op/dns-op.js"
    click Blocker "https://github.com/serverless-dns/serverless-dns/blob/main/src/plugins/dns-op/blocker.js"
    click CacheImpl "https://github.com/serverless-dns/serverless-dns/blob/main/src/plugins/dns-op/cache.js"
    click Log "https://github.com/serverless-dns/serverless-dns/blob/main/src/core/log.js"
    click Svc "https://github.com/serverless-dns/serverless-dns/blob/main/src/core/svc.js"

    %% Styling
    classDef platform fill:#b8d4ff,stroke:#2d6bef
    classDef core fill:#ffd7b5,stroke:#ff8533
    classDef config fill:#d9f2d9,stroke:#5cd65c
    classDef plugin fill:#ffb3b3,stroke:#ff4d4d
    classDef dns fill:#e6ccff,stroke:#9933ff
    classDef external fill:#f2f2f2,stroke:#808080

    %% Legend
    subgraph Legend
        P[Platform]:::platform
        C[Core]:::core
        CF[Config]:::config
        PL[Plugin]:::plugin
        D[DNS]:::dns
        E[External]:::external
    end
```
