# diniboy1123/usque architecture

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

- Interactive diagram: https://gitdiagram.com/diniboy1123/usque
- Repository: https://github.com/diniboy1123/usque

## Overview

Usque registers and enrolls a Cloudflare WARP device, saves its credentials and tunnel settings, then exposes WARP connectivity through native TUN, SOCKS5, HTTP proxy, TCP-only L4 proxy, or port forwarding modes. The graph also shows account management and shared MASQUE/tunnel, configuration, and proxy-server layers. Connections among modes and runtime layers are documented or supported by the indexed imports; unsampled implementation details are not inferred.

Main entry points: [`main.go`](https://github.com/diniboy1123/usque/blob/main/main.go) (CLI entry), [`config/config.go`](https://github.com/diniboy1123/usque/blob/main/config/config.go) (Saved settings), [`cmd/socks.go`](https://github.com/diniboy1123/usque/blob/main/cmd/socks.go) (SOCKS5 proxy), [`cmd/nativetun.go`](https://github.com/diniboy1123/usque/blob/main/cmd/nativetun.go) (Native TUN)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_account["Account lifecycle"]
  node_registration["Register device<br/>[register.go]"]
  node_enrollment["Enroll key<br/>[enroll.go]"]
  node_account_ops["Account tools<br/>[account.go]"]
  node_cloudflare_api["Cloudflare API<br/>[cloudflare.go]"]
end

subgraph group_runtime["Tunnel runtime"]
  node_masque["MASQUE transport<br/>[masque.go]"]
  node_tunnel["Tunnel forwarding<br/>[tunnel.go]"]
end

subgraph group_modes["Traffic modes"]
  node_native["Native TUN<br/>[nativetun.go]"]
  node_socks["SOCKS5 proxy<br/>[socks.go]"]
  node_http_proxy["HTTP proxy<br/>[httpproxy.go]"]
  node_l4_proxy["L4 proxies<br/>[l4_helpers.go]"]
  node_l4_http["L4 HTTP handler<br/>[l4_http_proxy.go]"]
  node_port_forward["Port forwarding<br/>[portfw.go]"]
end

subgraph group_shared["Shared services"]
  node_config["Saved settings<br/>[config.go]"]
  node_endpoints["Endpoint selection<br/>[endpoints.go]"]
  node_socks_server["SOCKS5 server<br/>[socks5.go]"]
end

node_user(("CLI user"))
node_entry["CLI entry<br/>[main.go]"]
node_cloudflare(("Cloudflare WARP"))

node_user -->|"runs"| node_entry
node_entry -.->|"dispatches"| node_registration
node_entry -.->|"dispatches"| node_enrollment
node_entry -.->|"dispatches"| node_account_ops
node_entry -.->|"dispatches"| node_native
node_entry -.->|"dispatches"| node_socks
node_entry -.->|"dispatches"| node_http_proxy
node_entry -.->|"dispatches"| node_l4_proxy
node_entry -.->|"dispatches"| node_port_forward
node_registration -->|"registers and enrolls"| node_cloudflare_api
node_enrollment -->|"enrolls key"| node_cloudflare_api
node_account_ops -->|"queries account"| node_cloudflare_api
node_cloudflare_api -->|"sends requests"| node_cloudflare
node_registration -->|"saves settings"| node_config
node_enrollment -->|"updates settings"| node_config
node_native -.->|"reads settings"| node_config
node_socks -->|"reads settings"| node_config
node_http_proxy -.->|"reads settings"| node_config
node_port_forward -->|"reads settings"| node_config
node_socks -->|"selects endpoint"| node_endpoints
node_native -->|"selects endpoint"| node_endpoints
node_masque -.->|"connects to"| node_cloudflare
node_native -.->|"forwards packets"| node_tunnel
node_socks -.->|"uses tunnel"| node_tunnel
node_http_proxy -.->|"uses tunnel"| node_tunnel
node_port_forward -.->|"uses tunnel"| node_tunnel
node_socks -->|"starts server"| node_socks_server
node_l4_proxy -->|"supports handler"| node_l4_http

click node_entry "https://github.com/diniboy1123/usque/blob/main/main.go"
click node_registration "https://github.com/diniboy1123/usque/blob/main/cmd/register.go"
click node_enrollment "https://github.com/diniboy1123/usque/blob/main/cmd/enroll.go"
click node_account_ops "https://github.com/diniboy1123/usque/blob/main/cmd/account.go"
click node_cloudflare_api "https://github.com/diniboy1123/usque/blob/main/api/cloudflare.go"
click node_config "https://github.com/diniboy1123/usque/blob/main/config/config.go"
click node_endpoints "https://github.com/diniboy1123/usque/blob/main/config/endpoints.go"
click node_masque "https://github.com/diniboy1123/usque/blob/main/api/masque.go"
click node_tunnel "https://github.com/diniboy1123/usque/blob/main/api/tunnel.go"
click node_native "https://github.com/diniboy1123/usque/blob/main/cmd/nativetun.go"
click node_socks "https://github.com/diniboy1123/usque/blob/main/cmd/socks.go"
click node_socks_server "https://github.com/diniboy1123/usque/blob/main/internal/socks5.go"
click node_http_proxy "https://github.com/diniboy1123/usque/blob/main/cmd/httpproxy.go"
click node_l4_proxy "https://github.com/diniboy1123/usque/blob/main/cmd/l4_helpers.go"
click node_l4_http "https://github.com/diniboy1123/usque/blob/main/cmd/l4_http_proxy.go"
click node_port_forward "https://github.com/diniboy1123/usque/blob/main/cmd/portfw.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_registration,node_enrollment,node_account_ops,node_cloudflare_api,node_user toneBlue
class node_masque,node_tunnel toneAmber
class node_native,node_socks,node_http_proxy,node_l4_proxy,node_l4_http,node_port_forward toneMint
class node_config,node_endpoints,node_socks_server toneRose
class node_entry toneTeal
class node_cloudflare toneIndigo
```

## Components

### Account lifecycle

- [Register device](https://github.com/diniboy1123/usque/blob/main/cmd/register.go): `cmd/register.go`
- [Enroll key](https://github.com/diniboy1123/usque/blob/main/cmd/enroll.go): `cmd/enroll.go`
- [Account tools](https://github.com/diniboy1123/usque/blob/main/cmd/account.go): `cmd/account.go`
- [Cloudflare API](https://github.com/diniboy1123/usque/blob/main/api/cloudflare.go): `api/cloudflare.go`

### Tunnel runtime

- [MASQUE transport](https://github.com/diniboy1123/usque/blob/main/api/masque.go): `api/masque.go`
- [Tunnel forwarding](https://github.com/diniboy1123/usque/blob/main/api/tunnel.go): `api/tunnel.go`

### Traffic modes

- [Native TUN](https://github.com/diniboy1123/usque/blob/main/cmd/nativetun.go): `cmd/nativetun.go`
- [SOCKS5 proxy](https://github.com/diniboy1123/usque/blob/main/cmd/socks.go): `cmd/socks.go`
- [HTTP proxy](https://github.com/diniboy1123/usque/blob/main/cmd/httpproxy.go): `cmd/httpproxy.go`
- [L4 proxies](https://github.com/diniboy1123/usque/blob/main/cmd/l4_helpers.go): `cmd/l4_helpers.go`
- [L4 HTTP handler](https://github.com/diniboy1123/usque/blob/main/cmd/l4_http_proxy.go): `cmd/l4_http_proxy.go`
- [Port forwarding](https://github.com/diniboy1123/usque/blob/main/cmd/portfw.go): `cmd/portfw.go`

### Shared services

- [Saved settings](https://github.com/diniboy1123/usque/blob/main/config/config.go): `config/config.go`
- [Endpoint selection](https://github.com/diniboy1123/usque/blob/main/config/endpoints.go): `config/endpoints.go`
- [SOCKS5 server](https://github.com/diniboy1123/usque/blob/main/internal/socks5.go): `internal/socks5.go`

### Other components

- **CLI user**
- [CLI entry](https://github.com/diniboy1123/usque/blob/main/main.go): `main.go`
- **Cloudflare WARP**

## Connections

- CLI user → CLI entry: runs (evidence: `main.go`)
- CLI entry → Register device: dispatches
- CLI entry → Enroll key: dispatches
- CLI entry → Account tools: dispatches
- CLI entry → Native TUN: dispatches
- CLI entry → SOCKS5 proxy: dispatches
- CLI entry → HTTP proxy: dispatches
- CLI entry → L4 proxies: dispatches
- CLI entry → Port forwarding: dispatches
- Register device → Cloudflare API: registers and enrolls (evidence: `cmd/register.go`)
- Enroll key → Cloudflare API: enrolls key (evidence: `cmd/enroll.go`)
- Account tools → Cloudflare API: queries account (evidence: `cmd/account.go`)
- Cloudflare API → Cloudflare WARP: sends requests (evidence: `api/cloudflare.go`)
- Register device → Saved settings: saves settings (evidence: `cmd/register.go`)
- Enroll key → Saved settings: updates settings (evidence: `cmd/enroll.go`)
- Native TUN → Saved settings: reads settings
- SOCKS5 proxy → Saved settings: reads settings (evidence: `cmd/socks.go`)
- HTTP proxy → Saved settings: reads settings
- Port forwarding → Saved settings: reads settings (evidence: `cmd/portfw.go`)
- SOCKS5 proxy → Endpoint selection: selects endpoint (evidence: `cmd/socks.go`)
- Native TUN → Endpoint selection: selects endpoint (evidence: `cmd/nativetun.go`)
- MASQUE transport → Cloudflare WARP: connects to
- Native TUN → Tunnel forwarding: forwards packets
- SOCKS5 proxy → Tunnel forwarding: uses tunnel
- HTTP proxy → Tunnel forwarding: uses tunnel
- Port forwarding → Tunnel forwarding: uses tunnel
- SOCKS5 proxy → SOCKS5 server: starts server (evidence: `cmd/socks.go`)
- L4 proxies → L4 HTTP handler: supports handler (evidence: `cmd/l4_http_proxy.go`)
