# n8n-io/localtunnel architecture

> Architecture diagram of the GitHub repository n8n-io/localtunnel, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/n8n-io/localtunnel
- Repository: https://github.com/n8n-io/localtunnel

## Overview

##### Project type and purpose
- This is a Node.js-based CLI tool *and* library (“localtunnel”) whose job is to expose a local HTTP(S) endpoint to the internet by opening a tunnel through an upstream proxy server. Users invoke it as a global CLI (`lt`) or import it as a module (`localtunnel(port, options)`) in their own scripts.

##### File structure
- Top-level files (`package.json`, `localtunnel.js`) and configs (`.eslintrc.js`, `.travis.yml`, etc.) set up the CLI and build/test environment.
- `lib/` contains three core modules:
- `Tunnel.js` – encapsulates a single tunnel connection (EventEmitter, handles socket setup and data piping).
- `TunnelCluster.js` – manages one or more `Tunnel` instances, handles reconnection logic if the local server restarts or the socket drops.
- `HeaderHostTransformer.js` – a small transform stream that rewrites HTTP Host headers to match the requested `--local-host` or default “localhost.”
- `localtunnel.js` is the main entry point for both CLI and programmatic API.
- `localtunnel.spec.js` holds unit tests.
- `index.d.ts` provides TypeScript typings for the API.

##### README for additional insights
- Confirms a dual-mode interface (CLI vs. JS API).
- Describes the lifecycle: connect to upstream proxy, negotiate a subdomain, pipe remote requests to the local port, emit events on request/error/close.
- Mentions TLS/HTTP options and environment variable overrides.

##### Detail checklist
- Where Host header rewriting happens (inside `HeaderHostTransformer`)
- Call out optional TLS config for local HTTPS tunnels

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend: CLI/API Layer"
        CLI["CLI / Programmatic API\n(localtunnel.js)"]:::cliapi
    end

    subgraph "Core Modules"
        TC["TunnelCluster\n(lib/TunnelCluster.js)"]:::core
        T["Tunnel Instance\n(lib/Tunnel.js)"]:::core
        HT["HeaderHostTransformer\n(lib/HeaderHostTransformer.js)"]:::core
    end

    subgraph "External Systems"
        US["Upstream Tunnel Server"]:::external
        LS["Local Server\n(user’s app)"]:::external
    end

    subgraph "Project Config & Docs"
        Package["package.json"]:::meta
        ESLint[".eslintrc.js"]:::meta
        CI[".travis.yml"]:::meta
        README["README.md"]:::meta
        Tests["localtunnel.spec.js"]:::meta
        Types["index.d.ts"]:::meta
    end

    CLI -->|"instantiate"| TC
    TC -->|"open socket (WS/TCP)"| US
    US -->|"forward request"| T
    T -->|"rewrites Host"| HT
    HT -->|"HTTP →"| LS
    LS -->|"response"| T
    T -->|"pipe back"| TC
    TC -->|"send to Upstream"| US
    TC -.->|"error/close"| TC

    click CLI "https://github.com/n8n-io/localtunnel/blob/master/localtunnel.js"
    click TC "https://github.com/n8n-io/localtunnel/blob/master/lib/TunnelCluster.js"
    click T "https://github.com/n8n-io/localtunnel/blob/master/lib/Tunnel.js"
    click HT "https://github.com/n8n-io/localtunnel/blob/master/lib/HeaderHostTransformer.js"
    click Package "https://github.com/n8n-io/localtunnel/blob/master/package.json"
    click ESLint "https://github.com/n8n-io/localtunnel/blob/master/.eslintrc.js"
    click CI "https://github.com/n8n-io/localtunnel/blob/master/.travis.yml"
    click README "https://github.com/n8n-io/localtunnel/blob/master/README.md"
    click Tests "https://github.com/n8n-io/localtunnel/blob/master/localtunnel.spec.js"
    click Types "https://github.com/n8n-io/localtunnel/blob/master/index.d.ts"

    classDef cliapi fill:#e0f7fa,stroke:#006064,color:#004d40
    classDef core fill:#fff3e0,stroke:#bf360c,color:#e65100
    classDef external fill:#e8f5e9,stroke:#1b5e20,color:#2e7d32
    classDef meta fill:#eceff1,stroke:#37474f,color:#263238
```
