# syss-research/turnado architecture

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

- Interactive diagram: https://gitdiagram.com/syss-research/turnado
- Repository: https://github.com/syss-research/turnado

## Overview

TURNado is a command-line suite for assessing TURN servers and relaying traffic through them. The user selects a mode; the CLI dispatches it to probes such as server inspection and TCP scanning, or to traffic-relay modes such as SOCKS, IP tunneling, and UDP forwarding. Shared control-connection setup supports TURN operations, while paired tunnels add peer exchange, secure transport, and reliability. The README documents these capabilities, but several mode implementations were not excerpted, so internal links to them are left unverified.

Main entry points: [`internal/app/modes.go`](https://github.com/syss-research/turnado/blob/main/internal/app/modes.go) (Mode registry), [`internal/app/tunnel.go`](https://github.com/syss-research/turnado/blob/main/internal/app/tunnel.go) (IP tunnel mode), [`internal/app/tunnel_transport.go`](https://github.com/syss-research/turnado/blob/main/internal/app/tunnel_transport.go) (Peer transport), [`internal/app/tunnel_reliable.go`](https://github.com/syss-research/turnado/blob/main/internal/app/tunnel_reliable.go) (SOCKS mode)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and modes"]
  node_cli["Command entry<br/>[main.go]"]
  node_registry["Mode registry<br/>[modes.go]"]
end

subgraph group_probes["TURN assessment"]
  node_info["Server inspection<br/>[info.go]"]
  node_report["Probe reporting<br/>[info_report.go]"]
  node_scan["TCP target scan<br/>[scan.go]"]
  node_dos["Allocation load test<br/>[dos.go]"]
end

subgraph group_relay["Traffic relaying"]
  node_forward["UDP forwarding<br/>[forward.go]"]
  node_socks["SOCKS mode<br/>[tunnel_reliable.go]"]
  node_direct["Direct SOCKS<br/>[direct_socks.go]"]
  node_tunnel["IP tunnel mode<br/>[tunnel.go]"]
end

subgraph group_tunnel["Tunnel internals"]
  node_common["TURN control setup<br/>[common.go]"]
  node_pairing["Peer pairing<br/>[tunnel_auto.go]"]
  node_connection["Connection strings<br/>[connstr.go]"]
  node_transport["Peer transport"]
  node_security["DTLS and SRTP<br/>[tunnel_secure.go]"]
  node_reliable["Reliable streams<br/>[tunnel_reliable.go]"]
  node_udp["SOCKS UDP<br/>[tunnel_udp.go]"]
  node_tun["TUN packet relay<br/>[tunnel_tun.go]"]
  node_tun_device["Platform TUN device<br/>[tun_linux.go]"]
end

node_user(("Operator"))
node_turn_server(("TURN server"))
node_socks_client(("SOCKS client"))
node_target(("TCP or UDP target"))
node_network(("IP network"))

node_user -->|"selects mode"| node_cli
node_cli -->|"looks up and runs"| node_registry
node_registry -.->|"dispatches"| node_info
node_registry -.->|"dispatches"| node_scan
node_registry -.->|"dispatches"| node_socks
node_registry -.->|"dispatches"| node_tunnel
node_registry -.->|"dispatches"| node_forward
node_registry -.->|"dispatches"| node_dos
node_info -->|"probes"| node_turn_server
node_info -.->|"reports results"| node_report
node_scan -->|"sends CONNECT"| node_turn_server
node_turn_server -->|"attempts TCP connection"| node_target
node_dos -->|"creates allocations"| node_turn_server
node_forward -->|"relays UDP through"| node_turn_server
node_forward -->|"forwards traffic"| node_target
node_socks_client -->|"opens SOCKS proxy"| node_socks
node_socks -->|"uses TURN"| node_turn_server
node_socks -->|"relays TCP to"| node_target
node_direct -->|"uses RFC 6062"| node_turn_server
node_tunnel -->|"allocates relay"| node_turn_server
node_tunnel -->|"tunnels IP traffic"| node_network
node_tunnel -.->|"pairs peers"| node_pairing
node_pairing -.->|"exchanges strings"| node_connection
node_pairing -.->|"pairs relay"| node_transport
node_transport -.->|"secures peer traffic"| node_security
node_transport -.->|"carries reliable data"| node_reliable
node_reliable -.->|"handles UDP associate"| node_udp
node_transport -.->|"carries IP packets"| node_tun
node_tun -.->|"reads and writes"| node_tun_device

click node_cli "https://github.com/syss-research/turnado/blob/main/cmd/turnado/main.go"
click node_registry "https://github.com/syss-research/turnado/blob/main/internal/app/modes.go"
click node_common "https://github.com/syss-research/turnado/blob/main/internal/app/common.go"
click node_info "https://github.com/syss-research/turnado/blob/main/internal/app/info.go"
click node_report "https://github.com/syss-research/turnado/blob/main/internal/app/info_report.go"
click node_scan "https://github.com/syss-research/turnado/blob/main/internal/app/scan.go"
click node_dos "https://github.com/syss-research/turnado/blob/main/internal/app/dos.go"
click node_forward "https://github.com/syss-research/turnado/blob/main/internal/app/forward.go"
click node_socks "https://github.com/syss-research/turnado/blob/main/internal/app/tunnel_reliable.go"
click node_direct "https://github.com/syss-research/turnado/blob/main/internal/app/direct_socks.go"
click node_tunnel "https://github.com/syss-research/turnado/blob/main/internal/app/tunnel.go"
click node_pairing "https://github.com/syss-research/turnado/blob/main/internal/app/tunnel_auto.go"
click node_connection "https://github.com/syss-research/turnado/blob/main/internal/app/connstr.go"
click node_transport "https://github.com/syss-research/turnado/blob/main/internal/app/tunnel_transport.go"
click node_security "https://github.com/syss-research/turnado/blob/main/internal/app/tunnel_secure.go"
click node_reliable "https://github.com/syss-research/turnado/blob/main/internal/app/tunnel_reliable.go"
click node_udp "https://github.com/syss-research/turnado/blob/main/internal/app/tunnel_udp.go"
click node_tun "https://github.com/syss-research/turnado/blob/main/internal/app/tunnel_tun.go"
click node_tun_device "https://github.com/syss-research/turnado/blob/main/internal/app/tun_linux.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_cli,node_registry,node_socks_client toneBlue
class node_info,node_report,node_scan,node_dos toneAmber
class node_forward,node_socks,node_direct,node_tunnel,node_turn_server toneMint
class node_common,node_pairing,node_connection,node_transport,node_security,node_reliable,node_udp,node_tun,node_tun_device toneRose
class node_user,node_target,node_network toneIndigo
```

## Components

### CLI and modes

- [Command entry](https://github.com/syss-research/turnado/blob/main/cmd/turnado/main.go): `cmd/turnado/main.go`
- [Mode registry](https://github.com/syss-research/turnado/blob/main/internal/app/modes.go): `internal/app/modes.go`

### TURN assessment

- [Server inspection](https://github.com/syss-research/turnado/blob/main/internal/app/info.go): `internal/app/info.go`
- [Probe reporting](https://github.com/syss-research/turnado/blob/main/internal/app/info_report.go): `internal/app/info_report.go`
- [TCP target scan](https://github.com/syss-research/turnado/blob/main/internal/app/scan.go): `internal/app/scan.go`
- [Allocation load test](https://github.com/syss-research/turnado/blob/main/internal/app/dos.go): `internal/app/dos.go`

### Traffic relaying

- [UDP forwarding](https://github.com/syss-research/turnado/blob/main/internal/app/forward.go): `internal/app/forward.go`
- [SOCKS mode](https://github.com/syss-research/turnado/blob/main/internal/app/tunnel_reliable.go): `internal/app/tunnel_reliable.go`
- [Direct SOCKS](https://github.com/syss-research/turnado/blob/main/internal/app/direct_socks.go): `internal/app/direct_socks.go`
- [IP tunnel mode](https://github.com/syss-research/turnado/blob/main/internal/app/tunnel.go): `internal/app/tunnel.go`

### Tunnel internals

- [TURN control setup](https://github.com/syss-research/turnado/blob/main/internal/app/common.go): `internal/app/common.go`
- [Peer pairing](https://github.com/syss-research/turnado/blob/main/internal/app/tunnel_auto.go): `internal/app/tunnel_auto.go`
- [Connection strings](https://github.com/syss-research/turnado/blob/main/internal/app/connstr.go): `internal/app/connstr.go`
- [Peer transport](https://github.com/syss-research/turnado/blob/main/internal/app/tunnel_transport.go): `internal/app/tunnel_transport.go`
- [DTLS and SRTP](https://github.com/syss-research/turnado/blob/main/internal/app/tunnel_secure.go): `internal/app/tunnel_secure.go`
- [Reliable streams](https://github.com/syss-research/turnado/blob/main/internal/app/tunnel_reliable.go): `internal/app/tunnel_reliable.go`
- [SOCKS UDP](https://github.com/syss-research/turnado/blob/main/internal/app/tunnel_udp.go): `internal/app/tunnel_udp.go`
- [TUN packet relay](https://github.com/syss-research/turnado/blob/main/internal/app/tunnel_tun.go): `internal/app/tunnel_tun.go`
- [Platform TUN device](https://github.com/syss-research/turnado/blob/main/internal/app/tun_linux.go): `internal/app/tun_linux.go`

### Other components

- **Operator**
- **TURN server**
- **SOCKS client**
- **TCP or UDP target**
- **IP network**

## Connections

- Operator → Command entry: selects mode (evidence: `README.md`)
- Command entry → Mode registry: looks up and runs (evidence: `cmd/turnado/main.go`)
- Mode registry → Server inspection: dispatches
- Mode registry → TCP target scan: dispatches
- Mode registry → SOCKS mode: dispatches
- Mode registry → IP tunnel mode: dispatches
- Mode registry → UDP forwarding: dispatches
- Mode registry → Allocation load test: dispatches
- Server inspection → TURN server: probes (evidence: `README.md`)
- Server inspection → Probe reporting: reports results
- TCP target scan → TURN server: sends CONNECT (evidence: `README.md`)
- TURN server → TCP or UDP target: attempts TCP connection (evidence: `README.md`)
- Allocation load test → TURN server: creates allocations (evidence: `README.md`)
- UDP forwarding → TURN server: relays UDP through (evidence: `README.md`)
- UDP forwarding → TCP or UDP target: forwards traffic (evidence: `README.md`)
- SOCKS client → SOCKS mode: opens SOCKS proxy (evidence: `README.md`)
- SOCKS mode → TURN server: uses TURN (evidence: `README.md`)
- SOCKS mode → TCP or UDP target: relays TCP to (evidence: `README.md`)
- Direct SOCKS → TURN server: uses RFC 6062 (evidence: `README.md`)
- IP tunnel mode → TURN server: allocates relay (evidence: `README.md`)
- IP tunnel mode → IP network: tunnels IP traffic (evidence: `README.md`)
- IP tunnel mode → Peer pairing: pairs peers
- Peer pairing → Connection strings: exchanges strings
- Peer pairing → Peer transport: pairs relay
- Peer transport → DTLS and SRTP: secures peer traffic
- Peer transport → Reliable streams: carries reliable data
- Reliable streams → SOCKS UDP: handles UDP associate
- Peer transport → TUN packet relay: carries IP packets
- TUN packet relay → Platform TUN device: reads and writes
