# robbie-cahill/tunnelmole-service architecture

> Architecture diagram of the GitHub repository robbie-cahill/tunnelmole-service, 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/robbie-cahill/tunnelmole-service
- Repository: https://github.com/robbie-cahill/tunnelmole-service

## Overview

##### Main Components

a) Client-Side Components:
- Tunnelmole Client (external component that connects to the service)
- Local Web Application (the user's application being tunneled)

b) Service-Side Components:
- WebSocket Server (src/websocket/host-ip-websocket.ts)
- HTTP Proxy Server (src/proxy.ts)
- Authentication System (src/authentication/)
- Domain Management System (src/reserved-domain/)
- Database Layer (src/mysql/)
- Telemetry System (src/telemetry/)

**[Client Layer]**

**[Communication Layer]**

**[Service Layer]**

**[Persistence Layer]**

##### Key Elements to Highlight

a) Connection Flow:
- WebSocket connection establishment
- HTTP/HTTPS request routing
- Domain reservation process
- Authentication checkpoints

b) Data Flow:
- Client initialization messages
- Request forwarding
- Response handling
- Telemetry logging

##### Specific Implementation Details

**[Local Web App] ←→ [Tunnelmole Client]**
- ↓
**[WebSocket Connection]**
- ↓
**[Tunnelmole Service]**
- Domain Manager
- Request Handler
- Authentication
- Database

##### Important Architectural Patterns to Highlight

- WebSocket-based persistent connections
- Message-based communication (src/messages/)
- Repository pattern (src/repository/)
- Handler pattern (src/handlers/)

##### Technical Details

- Port configurations (80/443 for HTTP/HTTPS, 81 for WebSocket)
- Database connections
- Security checkpoints
- Domain reservation system

##### Implementation Notes

- The TypeScript/Node.js runtime environment
- Functional programming patterns used
- Hot reload capability for development
- Security boundaries and checkpoints

Remember to include the monitoring endpoint (/tunnelmole-connections) and show how it interfaces with the main system.

- Clear component hierarchy
- Different line styles for different types of connections
- Proper grouping of related components
- Detailed annotations where needed

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client
        LocalApp["Local Web Application"]
        TMClient["Tunnelmole Client"]
    end

    subgraph Communication
        WS["WebSocket Server"]:::websocket
        HTTP["HTTP Proxy Server"]:::proxy
    end

    subgraph Core
        Auth["Authentication System"]:::auth
        DomainMgr["Domain Management"]:::domain
        ReqHandler["Request Handler"]:::handler
        ConnMgr["Connection Manager"]:::manager
    end

    subgraph Security
        IPBan["IP Banning"]:::security
        HostBan["Hostname Banning"]:::security
        ClientBan["Client Banning"]:::security
    end

    subgraph Persistence
        DB[(Database)]:::database
        TelemetryStore["Telemetry System"]:::telemetry
    end

    subgraph MessageSystem
        MsgDef["Message Definitions"]:::message
        MsgHandler["Message Handlers"]:::message
    end

    %% Connections
    LocalApp --> TMClient
    TMClient --> WS
    WS --> ReqHandler
    HTTP --> ReqHandler
    ReqHandler --> Auth
    ReqHandler --> DomainMgr
    Auth --> DB
    DomainMgr --> DB
    ReqHandler --> ConnMgr
    ConnMgr --> TelemetryStore
    Auth --> IPBan
    Auth --> HostBan
    Auth --> ClientBan
    ReqHandler --> MsgHandler
    MsgHandler --> MsgDef

    %% Click Events
    click WS "https://github.com/robbie-cahill/tunnelmole-service/blob/main/src/websocket/host-ip-websocket.ts"
    click HTTP "https://github.com/robbie-cahill/tunnelmole-service/blob/main/src/proxy.ts"
    click Auth "https://github.com/robbie-cahill/tunnelmole-service/tree/main/src/authentication/"
    click DomainMgr "https://github.com/robbie-cahill/tunnelmole-service/tree/main/src/reserved-domain/"
    click DB "https://github.com/robbie-cahill/tunnelmole-service/tree/main/src/mysql/"
    click TelemetryStore "https://github.com/robbie-cahill/tunnelmole-service/tree/main/src/telemetry/"
    click MsgDef "https://github.com/robbie-cahill/tunnelmole-service/tree/main/src/messages/"
    click MsgHandler "https://github.com/robbie-cahill/tunnelmole-service/tree/main/src/message-handlers/"
    click IPBan "https://github.com/robbie-cahill/tunnelmole-service/blob/main/security/banned-ips.ts"
    click HostBan "https://github.com/robbie-cahill/tunnelmole-service/blob/main/security/banned-hostnames.ts"
    click ClientBan "https://github.com/robbie-cahill/tunnelmole-service/blob/main/security/banned-client-ids.ts"
    click ReqHandler "https://github.com/robbie-cahill/tunnelmole-service/blob/main/src/handlers/handle-request.ts"
    click ConnMgr "https://github.com/robbie-cahill/tunnelmole-service/blob/main/src/handlers/tunnelmole-connections.ts"

    %% Styles
    classDef websocket fill:#3498db
    classDef proxy fill:#2ecc71
    classDef auth fill:#f1c40f
    classDef domain fill:#9b59b6
    classDef handler fill:#e74c3c
    classDef manager fill:#1abc9c
    classDef database fill:#34495e
    classDef telemetry fill:#95a5a6
    classDef message fill:#e67e22
    classDef security fill:#c0392b

    %% Legend
    subgraph Legend
        L1["WebSocket Component"]:::websocket
        L2["Proxy Component"]:::proxy
        L3["Auth Component"]:::auth
        L4["Domain Component"]:::domain
        L5["Handler Component"]:::handler
        L6["Manager Component"]:::manager
        L7["Database Component"]:::database
        L8["Telemetry Component"]:::telemetry
        L9["Message Component"]:::message
        L10["Security Component"]:::security
    end
```
