# cbeuw/cloak architecture

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

- Interactive diagram: https://gitdiagram.com/cbeuw/cloak
- Repository: https://github.com/cbeuw/cloak

## Overview

Cloak is a pluggable transport that disguises proxy traffic as web traffic, authenticates clients, and carries proxy streams over multiplexed connections. The main workflow runs from a local proxy client through Cloak’s client to the server, which authenticates and dispatches traffic to an upstream proxy; the server can also serve an admin panel. README capabilities include TLS/WebSocket and CDN transport, multi-user credit and bandwidth controls, and multiplexing. Some runtime paths are unsampled, so those branches are included only where documented, without inferring unshown calls.

Main entry points: [`internal/server/dispatcher.go`](https://github.com/cbeuw/cloak/blob/master/internal/server/dispatcher.go) (Connection dispatcher), [`cmd/ck-client/ck-client.go`](https://github.com/cbeuw/cloak/blob/master/cmd/ck-client/ck-client.go) (Cloak client), [`internal/client/auth.go`](https://github.com/cbeuw/cloak/blob/master/internal/client/auth.go) (Client authentication), [`internal/multiplex/session.go`](https://github.com/cbeuw/cloak/blob/master/internal/multiplex/session.go) (Multiplex session)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client transport"]
  node_ck_client["Cloak client<br/>[ck-client.go]"]
  node_client_config["Client configuration<br/>[state.go]"]
  node_client_auth["Client authentication<br/>[auth.go]"]
  node_client_tls["TLS camouflage<br/>[TLS.go]"]
  node_client_connector["Session connector<br/>[connector.go]"]
end

subgraph group_wire["Wire protocol"]
  node_mux_session["Multiplex session<br/>[session.go]"]
  node_frame_obfs["Frame obfuscation<br/>[obfs.go]"]
end

subgraph group_server["Server runtime"]
  node_server_listener["Server listener<br/>[ck-server.go]"]
  node_dispatcher["Connection dispatcher<br/>[dispatcher.go]"]
  node_server_auth["Server authentication<br/>[auth.go]"]
  node_proxy_bridge["Upstream proxy bridge<br/>[dispatcher.go]"]
  node_admin_panel["Admin panel<br/>[userpanel.go]"]
end

subgraph group_users["User management"]
  node_user_manager[("User manager<br/>[localmanager.go]")]
  node_manager_api["Manager API<br/>[api_router.go]"]
end

subgraph group_shared["Shared primitives"]
  node_crypto["Crypto helpers<br/>[crypto.go]"]
  node_ecdh["Curve25519 keys<br/>[curve25519.go]"]
end

node_proxy_client(("Proxy client"))
node_upstream_proxy(("Upstream proxy"))

node_proxy_client -->|"opens local connection"| node_ck_client
node_ck_client -.->|"loads configuration"| node_client_config
node_ck_client -->|"creates sessions"| node_client_connector
node_client_config -.->|"provides auth settings"| node_client_auth
node_client_auth -->|"derives shared secret"| node_ecdh
node_client_auth -->|"encrypts credentials"| node_crypto
node_client_connector -->|"uses multiplexing"| node_mux_session
node_client_tls -->|"uses record helpers"| node_crypto
node_ck_client -.->|"starts camouflage transport"| node_client_tls
node_server_listener -->|"serves connections"| node_dispatcher
node_dispatcher -.->|"authenticates first packet"| node_server_auth
node_dispatcher -->|"creates session"| node_mux_session
node_mux_session -->|"obfuscates frames"| node_frame_obfs
node_dispatcher -->|"checks user access"| node_user_manager
node_dispatcher -->|"bridges proxy streams"| node_proxy_bridge
node_proxy_bridge -->|"forwards traffic"| node_upstream_proxy
node_dispatcher -->|"serves admin requests"| node_admin_panel
node_admin_panel -.->|"uses manager API"| node_manager_api
node_manager_api -.->|"manages user records"| node_user_manager
node_user_manager -.->|"applies usage limits"| node_upstream_proxy

click node_ck_client "https://github.com/cbeuw/cloak/blob/master/cmd/ck-client/ck-client.go"
click node_client_config "https://github.com/cbeuw/cloak/blob/master/internal/client/state.go"
click node_client_auth "https://github.com/cbeuw/cloak/blob/master/internal/client/auth.go"
click node_client_tls "https://github.com/cbeuw/cloak/blob/master/internal/client/TLS.go"
click node_client_connector "https://github.com/cbeuw/cloak/blob/master/internal/client/connector.go"
click node_mux_session "https://github.com/cbeuw/cloak/blob/master/internal/multiplex/session.go"
click node_frame_obfs "https://github.com/cbeuw/cloak/blob/master/internal/multiplex/obfs.go"
click node_server_listener "https://github.com/cbeuw/cloak/blob/master/cmd/ck-server/ck-server.go"
click node_dispatcher "https://github.com/cbeuw/cloak/blob/master/internal/server/dispatcher.go"
click node_server_auth "https://github.com/cbeuw/cloak/blob/master/internal/server/auth.go"
click node_proxy_bridge "https://github.com/cbeuw/cloak/blob/master/internal/server/dispatcher.go"
click node_admin_panel "https://github.com/cbeuw/cloak/blob/master/internal/server/userpanel.go"
click node_user_manager "https://github.com/cbeuw/cloak/blob/master/internal/server/usermanager/localmanager.go"
click node_manager_api "https://github.com/cbeuw/cloak/blob/master/internal/server/usermanager/api_router.go"
click node_crypto "https://github.com/cbeuw/cloak/blob/master/internal/common/crypto.go"
click node_ecdh "https://github.com/cbeuw/cloak/blob/master/internal/ecdh/curve25519.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_ck_client,node_client_config,node_client_auth,node_client_tls,node_client_connector,node_proxy_client toneBlue
class node_mux_session,node_frame_obfs toneAmber
class node_server_listener,node_dispatcher,node_server_auth,node_proxy_bridge,node_admin_panel toneMint
class node_user_manager,node_manager_api toneRose
class node_crypto,node_ecdh,node_upstream_proxy toneIndigo
```

## Components

### Client transport

- [Cloak client](https://github.com/cbeuw/cloak/blob/master/cmd/ck-client/ck-client.go): `cmd/ck-client/ck-client.go`
- [Client configuration](https://github.com/cbeuw/cloak/blob/master/internal/client/state.go): `internal/client/state.go`
- [Client authentication](https://github.com/cbeuw/cloak/blob/master/internal/client/auth.go): `internal/client/auth.go`
- [TLS camouflage](https://github.com/cbeuw/cloak/blob/master/internal/client/TLS.go): `internal/client/TLS.go`
- [Session connector](https://github.com/cbeuw/cloak/blob/master/internal/client/connector.go): `internal/client/connector.go`

### Wire protocol

- [Multiplex session](https://github.com/cbeuw/cloak/blob/master/internal/multiplex/session.go): `internal/multiplex/session.go`
- [Frame obfuscation](https://github.com/cbeuw/cloak/blob/master/internal/multiplex/obfs.go): `internal/multiplex/obfs.go`

### Server runtime

- [Server listener](https://github.com/cbeuw/cloak/blob/master/cmd/ck-server/ck-server.go): `cmd/ck-server/ck-server.go`
- [Connection dispatcher](https://github.com/cbeuw/cloak/blob/master/internal/server/dispatcher.go): `internal/server/dispatcher.go`
- [Server authentication](https://github.com/cbeuw/cloak/blob/master/internal/server/auth.go): `internal/server/auth.go`
- [Upstream proxy bridge](https://github.com/cbeuw/cloak/blob/master/internal/server/dispatcher.go): `internal/server/dispatcher.go`
- [Admin panel](https://github.com/cbeuw/cloak/blob/master/internal/server/userpanel.go): `internal/server/userpanel.go`

### User management

- [User manager](https://github.com/cbeuw/cloak/blob/master/internal/server/usermanager/localmanager.go): `internal/server/usermanager/localmanager.go`
- [Manager API](https://github.com/cbeuw/cloak/blob/master/internal/server/usermanager/api_router.go): `internal/server/usermanager/api_router.go`

### Shared primitives

- [Crypto helpers](https://github.com/cbeuw/cloak/blob/master/internal/common/crypto.go): `internal/common/crypto.go`
- [Curve25519 keys](https://github.com/cbeuw/cloak/blob/master/internal/ecdh/curve25519.go): `internal/ecdh/curve25519.go`

### Other components

- **Proxy client**
- **Upstream proxy**

## Connections

- Proxy client → Cloak client: opens local connection
- Cloak client → Client configuration: loads configuration
- Cloak client → Session connector: creates sessions (evidence: `cmd/ck-client/ck-client.go`)
- Client configuration → Client authentication: provides auth settings
- Client authentication → Curve25519 keys: derives shared secret (evidence: `internal/client/auth.go`)
- Client authentication → Crypto helpers: encrypts credentials (evidence: `internal/client/auth.go`)
- Session connector → Multiplex session: uses multiplexing (evidence: `internal/client/connector.go`)
- TLS camouflage → Crypto helpers: uses record helpers (evidence: `internal/client/TLS.go`)
- Cloak client → TLS camouflage: starts camouflage transport
- Server listener → Connection dispatcher: serves connections (evidence: `cmd/ck-server/ck-server.go`)
- Connection dispatcher → Server authentication: authenticates first packet
- Connection dispatcher → Multiplex session: creates session (evidence: `internal/server/dispatcher.go`)
- Multiplex session → Frame obfuscation: obfuscates frames (evidence: `internal/multiplex/session.go`)
- Connection dispatcher → User manager: checks user access (evidence: `internal/server/dispatcher.go`)
- Connection dispatcher → Upstream proxy bridge: bridges proxy streams (evidence: `internal/server/dispatcher.go`)
- Upstream proxy bridge → Upstream proxy: forwards traffic
- Connection dispatcher → Admin panel: serves admin requests (evidence: `internal/server/dispatcher.go`)
- Admin panel → Manager API: uses manager API
- Manager API → User manager: manages user records
- User manager → Upstream proxy: applies usage limits
