# musixal/backhaul architecture

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

- Interactive diagram: https://gitdiagram.com/musixal/backhaul
- Repository: https://github.com/musixal/backhaul

## Overview

Backhaul is a reverse-tunneling application with client and server roles. The main workflow loads TOML configuration, selects a role and transport, then establishes tunnel connections that carry traffic between configured local ports and the remote side. The README also documents UDP forwarding, multiplexing, WebSocket/TLS transports, traffic monitoring, and configuration reload. Transport internals are only partly excerpted, so links inferred solely from the source index are limited to its recorded module references.

Main entry points: [`internal/client/client.go`](https://github.com/musixal/backhaul/blob/main/internal/client/client.go) (Client dispatcher), [`internal/server/server.go`](https://github.com/musixal/backhaul/blob/main/internal/server/server.go) (Server dispatcher), [`cmd/cmd.go`](https://github.com/musixal/backhaul/blob/main/cmd/cmd.go) (Config loading), [`internal/utils/handlers/tcp_handler.go`](https://github.com/musixal/backhaul/blob/main/internal/utils/handlers/tcp_handler.go) (TCP relay)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Application runtime"]
  node_main["Process and reload<br/>[main.go]"]
  node_config_flow["Config loading<br/>[cmd.go]"]
  node_config_schema["Config schema<br/>[config.go]"]
  node_client_runtime["Client dispatcher<br/>[client.go]"]
  node_server_runtime["Server dispatcher<br/>[server.go]"]
end

subgraph group_client["Client transports"]
  node_client_tcp["Client TCP<br/>[tcp.go]"]
  node_client_mux["Client TCP mux<br/>[tcpmux.go]"]
  node_client_udp["Client UDP<br/>[udp.go]"]
  node_client_ws["Client WebSocket<br/>[ws.go]"]
  node_client_wsmux["Client WS mux<br/>[wsmux.go]"]
  node_client_udp_accept["Client UDP accept<br/>[accept_udp.go]"]
end

subgraph group_server["Server transports"]
  node_server_tcp["Server TCP<br/>[tcp.go]"]
  node_server_mux["Server TCP mux<br/>[tcpmux.go]"]
  node_server_udp["Server UDP<br/>[udp.go]"]
  node_server_ws["Server WebSocket<br/>[ws.go]"]
  node_server_wsmux["Server WS mux<br/>[wsmux.go]"]
  node_server_udp_accept["Server UDP accept<br/>[accept_udp.go]"]
end

subgraph group_shared["Shared services"]
  node_tcp_handler["TCP relay<br/>[tcp_handler.go]"]
  node_ws_handler["WebSocket relay<br/>[ws_handler.go]"]
  node_network["Network dialers"]
  node_web_monitor["Traffic monitor<br/>[sniffer.go]"]
end

node_operator(("Operator"))
node_config_file["TOML configuration"]

node_operator -->|"starts"| node_main
node_main -->|"runs"| node_config_flow
node_main -->|"reloads"| node_config_flow
node_config_file -->|"provides settings"| node_config_flow
node_config_flow -->|"decodes into"| node_config_schema
node_config_flow -->|"starts client"| node_client_runtime
node_config_flow -->|"starts server"| node_server_runtime
node_client_runtime -->|"selects TCP"| node_client_tcp
node_client_runtime -->|"selects TCP mux"| node_client_mux
node_client_runtime -->|"selects UDP"| node_client_udp
node_client_runtime -->|"selects WS"| node_client_ws
node_client_runtime -->|"selects WS mux"| node_client_wsmux
node_server_runtime -->|"selects TCP"| node_server_tcp
node_server_runtime -->|"selects TCP mux"| node_server_mux
node_server_runtime -->|"selects UDP"| node_server_udp
node_server_runtime -->|"selects WS"| node_server_ws
node_server_runtime -->|"selects WS mux"| node_server_wsmux
node_client_tcp -->|"uses dialing"| node_network
node_client_mux -->|"uses dialing"| node_network
node_client_udp -.->|"delegates UDP handling"| node_client_udp_accept
node_server_udp -.->|"delegates UDP handling"| node_server_udp_accept
node_client_tcp -->|"uses relay"| node_tcp_handler
node_client_mux -->|"uses relay"| node_tcp_handler
node_client_ws -->|"uses relay"| node_ws_handler
node_client_wsmux -->|"uses relay"| node_ws_handler
node_server_tcp -->|"uses relay"| node_tcp_handler
node_server_mux -->|"uses relay"| node_tcp_handler
node_server_ws -->|"uses relay"| node_ws_handler
node_server_wsmux -->|"uses relay"| node_ws_handler
node_tcp_handler -->|"updates usage"| node_web_monitor
node_ws_handler -->|"updates usage"| node_web_monitor

click node_main "https://github.com/musixal/backhaul/blob/main/main.go"
click node_config_flow "https://github.com/musixal/backhaul/blob/main/cmd/cmd.go"
click node_config_schema "https://github.com/musixal/backhaul/blob/main/config/config.go"
click node_client_runtime "https://github.com/musixal/backhaul/blob/main/internal/client/client.go"
click node_server_runtime "https://github.com/musixal/backhaul/blob/main/internal/server/server.go"
click node_client_tcp "https://github.com/musixal/backhaul/blob/main/internal/client/transport/tcp.go"
click node_client_mux "https://github.com/musixal/backhaul/blob/main/internal/client/transport/tcpmux.go"
click node_client_udp "https://github.com/musixal/backhaul/blob/main/internal/client/transport/udp.go"
click node_client_ws "https://github.com/musixal/backhaul/blob/main/internal/client/transport/ws.go"
click node_client_wsmux "https://github.com/musixal/backhaul/blob/main/internal/client/transport/wsmux.go"
click node_client_udp_accept "https://github.com/musixal/backhaul/blob/main/internal/client/transport/accept_udp.go"
click node_server_tcp "https://github.com/musixal/backhaul/blob/main/internal/server/transport/tcp.go"
click node_server_mux "https://github.com/musixal/backhaul/blob/main/internal/server/transport/tcpmux.go"
click node_server_udp "https://github.com/musixal/backhaul/blob/main/internal/server/transport/udp.go"
click node_server_ws "https://github.com/musixal/backhaul/blob/main/internal/server/transport/ws.go"
click node_server_wsmux "https://github.com/musixal/backhaul/blob/main/internal/server/transport/wsmux.go"
click node_server_udp_accept "https://github.com/musixal/backhaul/blob/main/internal/server/transport/accept_udp.go"
click node_tcp_handler "https://github.com/musixal/backhaul/blob/main/internal/utils/handlers/tcp_handler.go"
click node_ws_handler "https://github.com/musixal/backhaul/blob/main/internal/utils/handlers/ws_handler.go"
click node_network "https://github.com/musixal/backhaul/tree/main/internal/utils/network"
click node_web_monitor "https://github.com/musixal/backhaul/blob/main/internal/web/sniffer.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_config_flow,node_config_schema,node_client_runtime,node_server_runtime toneBlue
class node_client_tcp,node_client_mux,node_client_udp,node_client_ws,node_client_wsmux,node_client_udp_accept toneAmber
class node_server_tcp,node_server_mux,node_server_udp,node_server_ws,node_server_wsmux,node_server_udp_accept toneMint
class node_tcp_handler,node_ws_handler,node_network,node_web_monitor toneRose
class node_operator,node_config_file toneIndigo
```

## Components

### Application runtime

- [Process and reload](https://github.com/musixal/backhaul/blob/main/main.go): `main.go`
- [Config loading](https://github.com/musixal/backhaul/blob/main/cmd/cmd.go): `cmd/cmd.go`
- [Config schema](https://github.com/musixal/backhaul/blob/main/config/config.go): `config/config.go`
- [Client dispatcher](https://github.com/musixal/backhaul/blob/main/internal/client/client.go): `internal/client/client.go`
- [Server dispatcher](https://github.com/musixal/backhaul/blob/main/internal/server/server.go): `internal/server/server.go`

### Client transports

- [Client TCP](https://github.com/musixal/backhaul/blob/main/internal/client/transport/tcp.go): `internal/client/transport/tcp.go`
- [Client TCP mux](https://github.com/musixal/backhaul/blob/main/internal/client/transport/tcpmux.go): `internal/client/transport/tcpmux.go`
- [Client UDP](https://github.com/musixal/backhaul/blob/main/internal/client/transport/udp.go): `internal/client/transport/udp.go`
- [Client WebSocket](https://github.com/musixal/backhaul/blob/main/internal/client/transport/ws.go): `internal/client/transport/ws.go`
- [Client WS mux](https://github.com/musixal/backhaul/blob/main/internal/client/transport/wsmux.go): `internal/client/transport/wsmux.go`
- [Client UDP accept](https://github.com/musixal/backhaul/blob/main/internal/client/transport/accept_udp.go): `internal/client/transport/accept_udp.go`

### Server transports

- [Server TCP](https://github.com/musixal/backhaul/blob/main/internal/server/transport/tcp.go): `internal/server/transport/tcp.go`
- [Server TCP mux](https://github.com/musixal/backhaul/blob/main/internal/server/transport/tcpmux.go): `internal/server/transport/tcpmux.go`
- [Server UDP](https://github.com/musixal/backhaul/blob/main/internal/server/transport/udp.go): `internal/server/transport/udp.go`
- [Server WebSocket](https://github.com/musixal/backhaul/blob/main/internal/server/transport/ws.go): `internal/server/transport/ws.go`
- [Server WS mux](https://github.com/musixal/backhaul/blob/main/internal/server/transport/wsmux.go): `internal/server/transport/wsmux.go`
- [Server UDP accept](https://github.com/musixal/backhaul/blob/main/internal/server/transport/accept_udp.go): `internal/server/transport/accept_udp.go`

### Shared services

- [TCP relay](https://github.com/musixal/backhaul/blob/main/internal/utils/handlers/tcp_handler.go): `internal/utils/handlers/tcp_handler.go`
- [WebSocket relay](https://github.com/musixal/backhaul/blob/main/internal/utils/handlers/ws_handler.go): `internal/utils/handlers/ws_handler.go`
- [Network dialers](https://github.com/musixal/backhaul/tree/main/internal/utils/network): `internal/utils/network`
- [Traffic monitor](https://github.com/musixal/backhaul/blob/main/internal/web/sniffer.go): `internal/web/sniffer.go`

### Other components

- **Operator**
- **TOML configuration**

## Connections

- Operator → Process and reload: starts (evidence: `main.go`)
- Process and reload → Config loading: runs (evidence: `main.go`)
- Process and reload → Config loading: reloads (evidence: `main.go`)
- TOML configuration → Config loading: provides settings (evidence: `cmd/cmd.go`)
- Config loading → Config schema: decodes into (evidence: `cmd/cmd.go`)
- Config loading → Client dispatcher: starts client (evidence: `cmd/cmd.go`)
- Config loading → Server dispatcher: starts server (evidence: `cmd/cmd.go`)
- Client dispatcher → Client TCP: selects TCP (evidence: `internal/client/client.go`)
- Client dispatcher → Client TCP mux: selects TCP mux (evidence: `internal/client/client.go`)
- Client dispatcher → Client UDP: selects UDP (evidence: `internal/client/client.go`)
- Client dispatcher → Client WebSocket: selects WS (evidence: `internal/client/client.go`)
- Client dispatcher → Client WS mux: selects WS mux (evidence: `internal/client/client.go`)
- Server dispatcher → Server TCP: selects TCP (evidence: `internal/server/server.go`)
- Server dispatcher → Server TCP mux: selects TCP mux (evidence: `internal/server/server.go`)
- Server dispatcher → Server UDP: selects UDP (evidence: `internal/server/server.go`)
- Server dispatcher → Server WebSocket: selects WS (evidence: `internal/server/server.go`)
- Server dispatcher → Server WS mux: selects WS mux (evidence: `internal/server/server.go`)
- Client TCP → Network dialers: uses dialing (evidence: `internal/client/transport/tcp.go`)
- Client TCP mux → Network dialers: uses dialing (evidence: `internal/client/transport/tcpmux.go`)
- Client UDP → Client UDP accept: delegates UDP handling
- Server UDP → Server UDP accept: delegates UDP handling
- Client TCP → TCP relay: uses relay (evidence: `internal/client/transport/tcp.go`)
- Client TCP mux → TCP relay: uses relay (evidence: `internal/client/transport/tcpmux.go`)
- Client WebSocket → WebSocket relay: uses relay (evidence: `internal/client/transport/ws.go`)
- Client WS mux → WebSocket relay: uses relay (evidence: `internal/client/transport/wsmux.go`)
- Server TCP → TCP relay: uses relay (evidence: `internal/server/transport/tcp.go`)
- Server TCP mux → TCP relay: uses relay (evidence: `internal/server/transport/tcpmux.go`)
- Server WebSocket → WebSocket relay: uses relay (evidence: `internal/server/transport/ws.go`)
- Server WS mux → WebSocket relay: uses relay (evidence: `internal/server/transport/wsmux.go`)
- TCP relay → Traffic monitor: updates usage (evidence: `internal/utils/handlers/tcp_handler.go`)
- WebSocket relay → Traffic monitor: updates usage (evidence: `internal/utils/handlers/ws_handler.go`)
