# faulpeltz/dertunnel architecture

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

## Overview

##### Main Components

A. Server-side Components:
- DNS Server (src/server/dns-server.ts)
- ACME Client (src/server/acme.ts)
- API Server (src/server/api-server.ts)
- Authentication System (src/server/auth.ts)
- Tunnel Dispatcher (src/server/dispatcher.ts)
- Admin UI Server

B. Client-side Components:
- CLI Interface (src/client/cli.ts)
- Tunnel Client (src/client/client.ts)
- Protocol Handlers (src/client/protocols.ts)
- Terminal UI (src/client/tui.ts)

C. Storage Components:
- Server Configuration Store (data/server.json)
- Client Tokens Store (data/clients.json)
- Certificate Storage (data/acme_tunnel.crt/key)

- DNS Layer    |     |  Server Core  |     |  Client Layer  |

##### Connection Flows to Illustrate

a. DNS Flow:
**External DNS → NS Record → DerTunnel DNS Server → A Record**

b. Tunnel Flow:
**Client App → Local TCP → Tunnel Client → TLS → Server → Public Endpoint**

c. Admin Flow:
**Browser → HTTPS → Admin UI → API Server → Authentication → Configuration**

##### Key Elements to Highlight

- Blue: TLS connections
- Green: TCP connections
- Orange: DNS queries
- Purple: Admin/API connections

- Rectangles: Core services
- Hexagons: External interfaces
- Circles: Connection points

##### Important Details

a. Port Configurations:
- Main service port (service.<domain>)
- Public endpoint ports (demo-1234.<domain>)
- Admin UI port (admin.<domain>)

b. Security Layer:
- TLS termination points
- ACME certificate management flow
- Token-based authentication paths

##### Specific Implementation Notes

a. Certificate Management:
**ACME Client → DNS-01 Challenge → DNS Server → Let's Encrypt → Wildcard Cert**

b. Token Management:
**Admin UI → Token Creation → Hash Storage → Client Authentication**

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph DNS
        DNS["DNS Server"]:::dns
        ACME["ACME Client"]:::security
        LetsEncrypt["Let's Encrypt"]:::external
    end

    subgraph Core
        DISP["Tunnel Dispatcher"]:::core
        AUTH["Authentication System"]:::security
        API["API Server"]:::api
        CONF["Server Configuration"]:::storage
        HASH["Auth Utilities"]:::security
        MSG["Message Handler"]:::core
        APIUTIL["API Utilities"]:::api
    end

    subgraph Client
        CLI["CLI Interface"]:::client
        TCLIENT["Tunnel Client"]:::client
        PROTO["Protocol Handlers"]:::client
        TUI["Terminal UI"]:::client
    end

    subgraph Frontend
        AUI["Admin UI Server"]:::ui
        AUIF["Admin UI Frontend"]:::ui
    end

    subgraph Storage
        CERT[("Certificate Storage")]:::storage
        TOKENS[("Client Tokens")]:::storage
        SCONF[("Server Config")]:::storage
    end

    %% Connections
    DNS --> ACME
    ACME --> LetsEncrypt
    ACME --> CERT
    
    DISP --> AUTH
    DISP --> MSG
    API --> AUTH
    API --> APIUTIL
    AUTH --> HASH
    AUTH --> TOKENS
    
    TCLIENT --> PROTO
    TCLIENT --> MSG
    CLI --> TCLIENT
    CLI --> TUI
    
    AUI --> API
    AUIF --> AUI
    
    CONF --> SCONF
    API --> CONF

    %% Click Events
    click DNS "https://github.com/faulpeltz/dertunnel/blob/main/src/server/dns-server.ts"
    click ACME "https://github.com/faulpeltz/dertunnel/blob/main/src/server/acme.ts"
    click API "https://github.com/faulpeltz/dertunnel/blob/main/src/server/api-server.ts"
    click AUTH "https://github.com/faulpeltz/dertunnel/blob/main/src/server/auth.ts"
    click DISP "https://github.com/faulpeltz/dertunnel/blob/main/src/server/dispatcher.ts"
    click AUI "https://github.com/faulpeltz/dertunnel/blob/main/src/ui/index.tsx"
    click CLI "https://github.com/faulpeltz/dertunnel/blob/main/src/client/cli.ts"
    click TCLIENT "https://github.com/faulpeltz/dertunnel/blob/main/src/client/client.ts"
    click PROTO "https://github.com/faulpeltz/dertunnel/blob/main/src/client/protocols.ts"
    click TUI "https://github.com/faulpeltz/dertunnel/blob/main/src/client/tui.ts"
    click AUIF "https://github.com/faulpeltz/dertunnel/blob/main/public/index.html"
    click CONF "https://github.com/faulpeltz/dertunnel/blob/main/src/server/config.ts"
    click APIUTIL "https://github.com/faulpeltz/dertunnel/blob/main/src/server/api-util.ts"
    click MSG "https://github.com/faulpeltz/dertunnel/blob/main/src/shared/messages.ts"
    click HASH "https://github.com/faulpeltz/dertunnel/blob/main/src/shared/hash.ts"

    %% Styles
    classDef dns fill:#f96,stroke:#333
    classDef security fill:#c9f,stroke:#333
    classDef core fill:#9cf,stroke:#333
    classDef api fill:#9fc,stroke:#333
    classDef client fill:#fc9,stroke:#333
    classDef ui fill:#f9f,stroke:#333
    classDef storage fill:#ccc,stroke:#333
    classDef external fill:#fff,stroke:#333,stroke-dasharray: 5 5

    %% Legend
    subgraph Legend
        L1["DNS Services"]:::dns
        L2["Security Components"]:::security
        L3["Core Services"]:::core
        L4["API Components"]:::api
        L5["Client Components"]:::client
        L6["UI Components"]:::ui
        L7["Storage"]:::storage
        L8["External Services"]:::external
    end
```
