# neonredwood/redtun architecture

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

## Overview

##### Main Components

a. Client-Side Components:
- Local Development Server (user's application)
- Redtun Client (CLI tool)
- WebSocket Tunnel Client
- HTTP Reverse Proxy

b. Server-Side Components:
- Nginx Reverse Proxy (with SSL termination)
- Redtun Server
- WebSocket Tunnel Server
- Client Manager
- Authentication System

**[Developer Environment] <---> [Public Internet] <---> [Server Infrastructure]**

##### Key Relationships to Highlight

a. Data Flow:
- WebSocket tunnel connection between Client and Server
- HTTP/HTTPS traffic flow from public internet through the entire stack

b. Authentication Flow:
- API key validation path
- Secure WebSocket connection establishment

##### Specific Implementation Details

- Rectangles: Main services (Redtun Server, Nginx)
- Hexagons: Protocol handlers (WebSocket, HTTP)

##### Component Details

**[Developer Environment]**
- Local Dev Server (Port 3000)
- Redtun Client
- CLI Interface
- Tunnel Client
- Config Manager

**[Public Internet]**
- HTTPS Traffic (*.dev.yourdomain.com)

**[Server Infrastructure]**
- Nginx Reverse Proxy
- SSL Termination
- Redtun Server
- Authentication Handler
- Client Manager
- WebSocket Tunnel
- HTTP Proxy

##### Important Architectural Notes

- How the wildcard SSL certificate (*.dev.yourdomain.com) is handled at the Nginx level
- Subdomain-based routing mechanism
- API key authentication flow

##### Technical Specifications

- Port mappings (3000 for local server, configurable server port)
- Protocol transitions (HTTP → HTTPS → WebSocket)
- Authentication points (API key validation)
- Subdomain handling

##### Environmental Boundaries

Use clear boundaries to separate:
- Local development environment
- Public internet
- Server infrastructure
- Security perimeters

##### Additional Elements

- Notes about scalability limitations (single-server deployment recommendation)
- Configuration points (API keys, server addresses)
- Version compatibility information

##### Deployment Context

- Container boundaries for dockerized components
- Kubernetes deployment options
- Load balancer limitations

Remember to include a note about the current limitation regarding subdomain reservation in distributed deployments, as this is a critical architectural consideration mentioned in the README.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Developer
        LocalDev["Local Dev Server<br/>(Port 3000)"]
        CLI["Redtun CLI"]:::cli
        TunnelClient["WebSocket<br/>Tunnel Client"]:::tunnelclient
        Display["Client Display<br/>Interface"]:::display
        HTTPProxy["HTTP Reverse Proxy"]
    end

    subgraph Internet
        HTTPS["HTTPS Traffic<br/>(*.dev.yourdomain.com)"]
    end

    subgraph Server
        direction TB
        Nginx["Nginx Reverse Proxy<br/>(SSL Termination)"]
        
        subgraph RedtunServer["Redtun Server"]
            direction TB
            Auth["Authentication<br/>Handler"]:::auth
            ClientMgr["Client Manager"]:::clientmgr
            WSTunnel["WebSocket<br/>Tunnel Server"]:::wstunnel
            HTTPHandler["HTTP Proxy"]:::httpproxy
            WSProxy["WebSocket Proxy"]:::wsproxy
            Protocol["Tunnel Protocol"]:::protocol
            ServerEntry["Server Main Entry"]:::server
        end

        subgraph Deployment
            Docker["Docker Container"]:::docker
            K8s["Kubernetes Pod"]:::k8s
        end
    end

    LocalDev --> CLI
    CLI --> TunnelClient
    TunnelClient --> Display
    TunnelClient <-.->|WebSocket| WSTunnel
    LocalDev --> HTTPProxy
    HTTPProxy --> TunnelClient
    
    HTTPS --> Nginx
    Nginx --> Auth
    Auth --> ClientMgr
    ClientMgr --> WSTunnel
    WSTunnel --> HTTPHandler
    WSTunnel --> WSProxy
    WSTunnel --> Protocol
    ServerEntry --> Auth
    
    RedtunServer --> Docker
    RedtunServer --> K8s

    %% Click events for component mapping
    click CLI "https://github.com/neonredwood/redtun/blob/master/packages/redtun/src/cli/index.ts"
    click TunnelClient "https://github.com/neonredwood/redtun/blob/master/packages/redtun/src/client/tunnel.ts"
    click Display "https://github.com/neonredwood/redtun/blob/master/packages/redtun/src/client/display.ts"
    click Auth "https://github.com/neonredwood/redtun/blob/master/packages/redtun-server/src/server/auth.ts"
    click ClientMgr "https://github.com/neonredwood/redtun/blob/master/packages/redtun-server/src/server/client-manager.ts"
    click WSTunnel "https://github.com/neonredwood/redtun/blob/master/packages/redtun-server/src/server/ws-tunnel.ts"
    click HTTPHandler "https://github.com/neonredwood/redtun/blob/master/packages/redtun-server/src/server/http-proxy.ts"
    click WSProxy "https://github.com/neonredwood/redtun/blob/master/packages/redtun-server/src/server/ws-proxy.ts"
    click Protocol "https://github.com/neonredwood/redtun/tree/master/packages/redtun-common/src/tunnel/"
    click ServerEntry "https://github.com/neonredwood/redtun/blob/master/packages/redtun-server/src/server/server.ts"
    click Docker "https://github.com/neonredwood/redtun/blob/master/docker/redtun-server.dockerfile"
    click K8s "https://github.com/neonredwood/redtun/blob/master/k8s/redtun-server.yaml"

    %% Styling
    classDef cli fill:#f9f,stroke:#333
    classDef tunnelclient fill:#bbf,stroke:#333
    classDef display fill:#dfd,stroke:#333
    classDef auth fill:#fdd,stroke:#333
    classDef clientmgr fill:#ddf,stroke:#333
    classDef wstunnel fill:#ffd,stroke:#333
    classDef httpproxy fill:#dff,stroke:#333
    classDef wsproxy fill:#fdf,stroke:#333
    classDef protocol fill:#ddd,stroke:#333
    classDef server fill:#fdb,stroke:#333
    classDef docker fill:#bfd,stroke:#333
    classDef k8s fill:#dbf,stroke:#333
```
