# 1catai/1cat-tunnel architecture

> Architecture diagram of the GitHub repository 1catai/1cat-tunnel, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/1catai/1cat-tunnel
- Repository: https://github.com/1catai/1cat-tunnel

## Overview

1Cat Tunnel is a reverse-access tunnel: an administrator issues a node credential, a client registers its local TCP/UDP presets over an outbound control connection, and the server allocates public listeners. External traffic triggers a client-side connection to the local service and is forwarded through a separate data channel. The README also documents a Web console, restart-restored mappings and counters, and platform-specific client setup and management. The root server/client are explicitly historical 0.1.2 code; the newer client lives under `client/`. Server internals were only partially sampled, so uncertain handler and persistence wiring is not shown.

Main entry points: [`internal/client/client.go`](https://github.com/1catai/1cat-tunnel/blob/main/internal/client/client.go) (Client session runtime), [`internal/server/server.go`](https://github.com/1catai/1cat-tunnel/blob/main/internal/server/server.go) (Server control and tunnels), [`cmd/tunnel-client/main.go`](https://github.com/1catai/1cat-tunnel/blob/main/cmd/tunnel-client/main.go) (Client entry), [`internal/server/tunnel.go`](https://github.com/1catai/1cat-tunnel/blob/main/internal/server/tunnel.go) (Public tunnel listeners)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client runtime"]
  node_cliententry["Client entry<br/>[main.go]"]
  node_clientruntime["Client session runtime<br/>[client.go]"]
  node_clientconfig["Client configuration<br/>[config.go]"]
  node_clientwizard["First-run setup<br/>[client.go]"]
  node_winservice["Windows service<br/>[service_windows.go]"]
  node_launcher["Config and logging utilities<br/>[launcher.go]"]
end

subgraph group_server["Server runtime"]
  node_serverentry["Server entry<br/>[main.go]"]
  node_servercore["Server control and tunnels<br/>[server.go]"]
  node_serverconfig["Server configuration<br/>[config.go]"]
  node_tunnel["Public tunnel listeners<br/>[tunnel.go]"]
end

subgraph group_protocol["Tunnel protocol"]
  node_wireprotocol["Control and attach messages<br/>[protocol.go]"]
end

subgraph group_management["Management and state"]
  node_serverhttp["Server HTTP console<br/>[http.go]"]
  node_dashboard["Admin dashboard<br/>[dashboard.go]"]
  node_serverstate[("Persisted server state<br/>[state.go]")]
  node_clientweb["Local management panel<br/>[management_web.go]"]
  node_clientauth["Panel authentication<br/>[management_auth.go]"]
end

node_operator(("Administrator"))
node_clientuser(("Client operator"))
node_outside(("External TCP/UDP users"))
node_localservice(("Local services"))

node_operator -->|"manages nodes"| node_serverhttp
node_serverentry -->|"loads configuration"| node_serverconfig
node_serverentry -->|"starts server"| node_servercore
node_servercore -->|"serves console"| node_serverhttp
node_serverhttp -->|"renders console"| node_dashboard
node_servercore -->|"restores and saves"| node_serverstate
node_servercore -->|"exchanges messages"| node_wireprotocol
node_servercore -->|"creates listeners"| node_tunnel
node_outside -->|"connects to ports"| node_tunnel
node_clientuser -->|"starts client"| node_cliententry
node_cliententry -->|"resolves configuration"| node_launcher
node_cliententry -->|"loads configuration"| node_clientconfig
node_cliententry -->|"starts setup"| node_clientwizard
node_clientwizard -->|"saves presets"| node_clientconfig
node_cliententry -->|"runs client"| node_clientruntime
node_winservice -.->|"runs as service"| node_clientruntime
node_clientruntime -->|"registers and reconnects"| node_servercore
node_clientruntime -->|"exchanges control and attach"| node_wireprotocol
node_servercore -->|"requests connections"| node_clientruntime
node_clientruntime -->|"dials local preset"| node_localservice
node_tunnel -->|"forwards data channel"| node_clientruntime
node_clientruntime -->|"starts local panel"| node_clientweb
node_clientweb -->|"authenticates requests"| node_clientauth
node_clientuser -->|"views status"| node_clientweb

click node_serverentry "https://github.com/1catai/1cat-tunnel/blob/main/cmd/tunnel-server/main.go"
click node_servercore "https://github.com/1catai/1cat-tunnel/blob/main/internal/server/server.go"
click node_serverhttp "https://github.com/1catai/1cat-tunnel/blob/main/internal/server/http.go"
click node_dashboard "https://github.com/1catai/1cat-tunnel/blob/main/internal/server/dashboard.go"
click node_serverconfig "https://github.com/1catai/1cat-tunnel/blob/main/internal/server/config.go"
click node_serverstate "https://github.com/1catai/1cat-tunnel/blob/main/internal/server/state.go"
click node_tunnel "https://github.com/1catai/1cat-tunnel/blob/main/internal/server/tunnel.go"
click node_cliententry "https://github.com/1catai/1cat-tunnel/blob/main/cmd/tunnel-client/main.go"
click node_clientruntime "https://github.com/1catai/1cat-tunnel/blob/main/internal/client/client.go"
click node_clientconfig "https://github.com/1catai/1cat-tunnel/blob/main/internal/client/config.go"
click node_clientwizard "https://github.com/1catai/1cat-tunnel/blob/main/internal/client/client.go"
click node_clientweb "https://github.com/1catai/1cat-tunnel/blob/main/client/internal/client/management_web.go"
click node_clientauth "https://github.com/1catai/1cat-tunnel/blob/main/client/internal/client/management_auth.go"
click node_winservice "https://github.com/1catai/1cat-tunnel/blob/main/client/internal/winclient/service_windows.go"
click node_wireprotocol "https://github.com/1catai/1cat-tunnel/blob/main/internal/common/protocol.go"
click node_launcher "https://github.com/1catai/1cat-tunnel/blob/main/internal/launcher/launcher.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_cliententry,node_clientruntime,node_clientconfig,node_clientwizard,node_winservice,node_launcher,node_clientuser,node_outside toneBlue
class node_serverentry,node_servercore,node_serverconfig,node_tunnel toneAmber
class node_wireprotocol toneMint
class node_serverhttp,node_dashboard,node_serverstate,node_clientweb,node_clientauth toneRose
class node_operator,node_localservice toneIndigo
```

## Components

### Client runtime

- [Client entry](https://github.com/1catai/1cat-tunnel/blob/main/cmd/tunnel-client/main.go): `cmd/tunnel-client/main.go`
- [Client session runtime](https://github.com/1catai/1cat-tunnel/blob/main/internal/client/client.go): `internal/client/client.go`
- [Client configuration](https://github.com/1catai/1cat-tunnel/blob/main/internal/client/config.go): `internal/client/config.go`
- [First-run setup](https://github.com/1catai/1cat-tunnel/blob/main/internal/client/client.go): `internal/client/client.go`
- [Windows service](https://github.com/1catai/1cat-tunnel/blob/main/client/internal/winclient/service_windows.go): `client/internal/winclient/service_windows.go`
- [Config and logging utilities](https://github.com/1catai/1cat-tunnel/blob/main/internal/launcher/launcher.go): `internal/launcher/launcher.go`

### Server runtime

- [Server entry](https://github.com/1catai/1cat-tunnel/blob/main/cmd/tunnel-server/main.go): `cmd/tunnel-server/main.go`
- [Server control and tunnels](https://github.com/1catai/1cat-tunnel/blob/main/internal/server/server.go): `internal/server/server.go`
- [Server configuration](https://github.com/1catai/1cat-tunnel/blob/main/internal/server/config.go): `internal/server/config.go`
- [Public tunnel listeners](https://github.com/1catai/1cat-tunnel/blob/main/internal/server/tunnel.go): `internal/server/tunnel.go`

### Tunnel protocol

- [Control and attach messages](https://github.com/1catai/1cat-tunnel/blob/main/internal/common/protocol.go): `internal/common/protocol.go`

### Management and state

- [Server HTTP console](https://github.com/1catai/1cat-tunnel/blob/main/internal/server/http.go): `internal/server/http.go`
- [Admin dashboard](https://github.com/1catai/1cat-tunnel/blob/main/internal/server/dashboard.go): `internal/server/dashboard.go`
- [Persisted server state](https://github.com/1catai/1cat-tunnel/blob/main/internal/server/state.go): `internal/server/state.go`
- [Local management panel](https://github.com/1catai/1cat-tunnel/blob/main/client/internal/client/management_web.go): `client/internal/client/management_web.go`
- [Panel authentication](https://github.com/1catai/1cat-tunnel/blob/main/client/internal/client/management_auth.go): `client/internal/client/management_auth.go`

### Other components

- **Administrator**
- **Client operator**
- **External TCP/UDP users**
- **Local services**

## Connections

- Administrator → Server HTTP console: manages nodes
- Server entry → Server configuration: loads configuration
- Server entry → Server control and tunnels: starts server
- Server control and tunnels → Server HTTP console: serves console
- Server HTTP console → Admin dashboard: renders console
- Server control and tunnels → Persisted server state: restores and saves
- Server control and tunnels → Control and attach messages: exchanges messages
- Server control and tunnels → Public tunnel listeners: creates listeners
- External TCP/UDP users → Public tunnel listeners: connects to ports
- Client operator → Client entry: starts client
- Client entry → Config and logging utilities: resolves configuration
- Client entry → Client configuration: loads configuration
- Client entry → First-run setup: starts setup
- First-run setup → Client configuration: saves presets
- Client entry → Client session runtime: runs client
- Windows service → Client session runtime: runs as service
- Client session runtime → Server control and tunnels: registers and reconnects
- Client session runtime → Control and attach messages: exchanges control and attach
- Server control and tunnels → Client session runtime: requests connections
- Client session runtime → Local services: dials local preset
- Public tunnel listeners → Client session runtime: forwards data channel
- Client session runtime → Local management panel: starts local panel
- Local management panel → Panel authentication: authenticates requests
- Client operator → Local management panel: views status