# ehang-io/nps architecture

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

- Interactive diagram: https://gitdiagram.com/ehang-io/nps
- Repository: https://github.com/ehang-io/nps

## Overview

NPS is an intranet-penetration proxy with a server, connecting NPC clients, and a web management interface. The main workflow is: an operator configures a client and tunnel or host rule in the web UI; the server starts the corresponding proxy; the NPC client maintains a bridge connection and carries traffic between the server and a local target. The README also documents multiple proxy protocols, HTTPS/domain routing, monitoring, and optional transport features. Some subsystem links are based on documented capabilities because their implementation was not sampled.

Main entry points: [`server/server.go`](https://github.com/ehang-io/nps/blob/master/server/server.go) (NPS server), [`bridge/bridge.go`](https://github.com/ehang-io/nps/blob/master/bridge/bridge.go) (Client bridge), [`client/client.go`](https://github.com/ehang-io/nps/blob/master/client/client.go) (NPC client), [`web/routers/router.go`](https://github.com/ehang-io/nps/blob/master/web/routers/router.go) (Web UI/API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_management["Management"]
  node_web["Web UI/API<br/>[router.go]"]
  node_auth["Login and auth<br/>[auth.go]"]
  node_clientctl["Client management<br/>[client.go]"]
  node_tunnelctl["Tunnel and host rules<br/>[index.go]"]
  node_dashboard["Dashboard<br/>[index.go]"]
end

subgraph group_control["Client Control"]
  node_client["NPC client<br/>[client.go]"]
  node_clientconfig["Client configuration<br/>[local.go]"]
  node_bridge["Client bridge<br/>[bridge.go]"]
  node_server["NPS server<br/>[server.go]"]
end

subgraph group_proxy["Proxy Services"]
  node_tcp["TCP and file proxy<br/>[tcp.go]"]
  node_udp["UDP proxy<br/>[udp.go]"]
  node_socks["SOCKS5 proxy<br/>[socks5.go]"]
  node_http["HTTP and HTTPS<br/>[http.go]"]
  node_https["TLS proxy<br/>[https.go]"]
  node_p2p["P2P proxy<br/>[p2p.go]"]
end

subgraph group_transport["Transport and State"]
  node_state[("Persistent configuration<br/>[db.go]")]
  node_transport["Connection transport<br/>[conn.go]"]
  node_features["Transport features<br/>[crypt.go]"]
end

node_operator(("Operator"))
node_target(("Local services"))

node_operator -->|"manages"| node_web
node_web -->|"routes auth"| node_auth
node_web -->|"routes client requests"| node_clientctl
node_web -->|"routes rule requests"| node_tunnelctl
node_clientctl -->|"reads and writes"| node_state
node_clientctl -->|"controls clients"| node_server
node_tunnelctl -->|"reads and writes"| node_state
node_tunnelctl -->|"starts and stops"| node_server
node_dashboard -->|"reads status"| node_server
node_dashboard -->|"reads records"| node_state
node_clientconfig -->|"configures"| node_client
node_client -->|"connects"| node_bridge
node_bridge -->|"reads client and task data"| node_state
node_server -->|"uses bridge"| node_bridge
node_server -->|"starts mode"| node_tcp
node_server -->|"starts mode"| node_udp
node_server -->|"starts mode"| node_socks
node_server -->|"starts mode"| node_http
node_server -->|"starts mode"| node_https
node_server -->|"starts mode"| node_p2p
node_tcp -->|"forwards traffic"| node_bridge
node_udp -->|"forwards traffic"| node_bridge
node_socks -->|"forwards traffic"| node_bridge
node_http -->|"forwards traffic"| node_bridge
node_https -->|"forwards traffic"| node_bridge
node_p2p -->|"coordinates peers"| node_bridge
node_bridge -->|"dispatches traffic"| node_client
node_client -->|"forwards to"| node_target
node_tcp -->|"uses"| node_transport
node_client -->|"uses"| node_transport
node_transport -.->|"supports"| node_features

click node_web "https://github.com/ehang-io/nps/blob/master/web/routers/router.go"
click node_auth "https://github.com/ehang-io/nps/blob/master/web/controllers/auth.go"
click node_clientctl "https://github.com/ehang-io/nps/blob/master/web/controllers/client.go"
click node_tunnelctl "https://github.com/ehang-io/nps/blob/master/web/controllers/index.go"
click node_dashboard "https://github.com/ehang-io/nps/blob/master/web/controllers/index.go"
click node_state "https://github.com/ehang-io/nps/blob/master/lib/file/db.go"
click node_client "https://github.com/ehang-io/nps/blob/master/client/client.go"
click node_clientconfig "https://github.com/ehang-io/nps/blob/master/client/local.go"
click node_bridge "https://github.com/ehang-io/nps/blob/master/bridge/bridge.go"
click node_server "https://github.com/ehang-io/nps/blob/master/server/server.go"
click node_tcp "https://github.com/ehang-io/nps/blob/master/server/proxy/tcp.go"
click node_udp "https://github.com/ehang-io/nps/blob/master/server/proxy/udp.go"
click node_socks "https://github.com/ehang-io/nps/blob/master/server/proxy/socks5.go"
click node_http "https://github.com/ehang-io/nps/blob/master/server/proxy/http.go"
click node_https "https://github.com/ehang-io/nps/blob/master/server/proxy/https.go"
click node_p2p "https://github.com/ehang-io/nps/blob/master/server/proxy/p2p.go"
click node_transport "https://github.com/ehang-io/nps/blob/master/lib/conn/conn.go"
click node_features "https://github.com/ehang-io/nps/blob/master/lib/crypt/crypt.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_web,node_auth,node_clientctl,node_tunnelctl,node_dashboard toneBlue
class node_client,node_clientconfig,node_bridge,node_server toneAmber
class node_tcp,node_udp,node_socks,node_http,node_https,node_p2p toneMint
class node_state,node_transport,node_features toneRose
class node_operator,node_target toneIndigo
```

## Components

### Management

- [Web UI/API](https://github.com/ehang-io/nps/blob/master/web/routers/router.go): `web/routers/router.go`
- [Login and auth](https://github.com/ehang-io/nps/blob/master/web/controllers/auth.go): `web/controllers/auth.go`
- [Client management](https://github.com/ehang-io/nps/blob/master/web/controllers/client.go): `web/controllers/client.go`
- [Tunnel and host rules](https://github.com/ehang-io/nps/blob/master/web/controllers/index.go): `web/controllers/index.go`
- [Dashboard](https://github.com/ehang-io/nps/blob/master/web/controllers/index.go): `web/controllers/index.go`

### Client Control

- [NPC client](https://github.com/ehang-io/nps/blob/master/client/client.go): `client/client.go`
- [Client configuration](https://github.com/ehang-io/nps/blob/master/client/local.go): `client/local.go`
- [Client bridge](https://github.com/ehang-io/nps/blob/master/bridge/bridge.go): `bridge/bridge.go`
- [NPS server](https://github.com/ehang-io/nps/blob/master/server/server.go): `server/server.go`

### Proxy Services

- [TCP and file proxy](https://github.com/ehang-io/nps/blob/master/server/proxy/tcp.go): `server/proxy/tcp.go`
- [UDP proxy](https://github.com/ehang-io/nps/blob/master/server/proxy/udp.go): `server/proxy/udp.go`
- [SOCKS5 proxy](https://github.com/ehang-io/nps/blob/master/server/proxy/socks5.go): `server/proxy/socks5.go`
- [HTTP and HTTPS](https://github.com/ehang-io/nps/blob/master/server/proxy/http.go): `server/proxy/http.go`
- [TLS proxy](https://github.com/ehang-io/nps/blob/master/server/proxy/https.go): `server/proxy/https.go`
- [P2P proxy](https://github.com/ehang-io/nps/blob/master/server/proxy/p2p.go): `server/proxy/p2p.go`

### Transport and State

- [Persistent configuration](https://github.com/ehang-io/nps/blob/master/lib/file/db.go): `lib/file/db.go`
- [Connection transport](https://github.com/ehang-io/nps/blob/master/lib/conn/conn.go): `lib/conn/conn.go`
- [Transport features](https://github.com/ehang-io/nps/blob/master/lib/crypt/crypt.go): `lib/crypt/crypt.go`

### Other components

- **Operator**
- **Local services**

## Connections

- Operator → Web UI/API: manages
- Web UI/API → Login and auth: routes auth
- Web UI/API → Client management: routes client requests
- Web UI/API → Tunnel and host rules: routes rule requests
- Client management → Persistent configuration: reads and writes
- Client management → NPS server: controls clients
- Tunnel and host rules → Persistent configuration: reads and writes
- Tunnel and host rules → NPS server: starts and stops
- Dashboard → NPS server: reads status
- Dashboard → Persistent configuration: reads records
- Client configuration → NPC client: configures
- NPC client → Client bridge: connects
- Client bridge → Persistent configuration: reads client and task data
- NPS server → Client bridge: uses bridge
- NPS server → TCP and file proxy: starts mode
- NPS server → UDP proxy: starts mode
- NPS server → SOCKS5 proxy: starts mode
- NPS server → HTTP and HTTPS: starts mode
- NPS server → TLS proxy: starts mode
- NPS server → P2P proxy: starts mode
- TCP and file proxy → Client bridge: forwards traffic
- UDP proxy → Client bridge: forwards traffic
- SOCKS5 proxy → Client bridge: forwards traffic
- HTTP and HTTPS → Client bridge: forwards traffic
- TLS proxy → Client bridge: forwards traffic
- P2P proxy → Client bridge: coordinates peers
- Client bridge → NPC client: dispatches traffic
- NPC client → Local services: forwards to
- TCP and file proxy → Connection transport: uses
- NPC client → Connection transport: uses
- Connection transport → Transport features: supports