# smolkar/wireguard_surf architecture

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

- Interactive diagram: https://gitdiagram.com/smolkar/wireguard_surf
- Repository: https://github.com/smolkar/wireguard_surf

## Overview

WireGuard_Surf is a small WireGuard VPN server with an HTTP API for identifying users and managing client peers. Its main workflow is to load or create server configuration, bring up a WireGuard interface, apply peer configuration, and serve client-management requests. Client creation allocates an IP and generates keys; client configuration can be returned as text or a QR code. The README also documents manual NAT setup and flags DNS and authentication as unfinished. The source excerpts are partial, so uncertain lifecycle and persistence links are omitted.

Main entry points: [`api.go`](https://github.com/smolkar/wireguard_surf/blob/master/api.go) (Client management), [`main.go`](https://github.com/smolkar/wireguard_surf/blob/master/main.go) (Server process), [`Configuration.go`](https://github.com/smolkar/wireguard_surf/blob/master/Configuration.go) (Key generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["VPN server"]
  node_server_app["Server process<br/>[main.go]"]
  node_lifecycle["Server lifecycle<br/>[main.go]"]
  node_peer_setup["Peer configuration<br/>[main.go]"]
end

subgraph group_api["HTTP API"]
  node_api_server["HTTP API server<br/>[api.go]"]
  node_user_context["User context<br/>[api.go]"]
  node_client_management["Client management<br/>[api.go]"]
  node_client_export["Client config export<br/>[api.go]"]
end

subgraph group_config["Configuration"]
  node_client_record["Client records<br/>[Configuration.go]"]
  node_config_store[("Server config file<br/>[Configuration.go]")]
  node_key_generation["Key generation<br/>[Configuration.go]"]
end

subgraph group_network["Network setup"]
  node_ip_allocator["Client IP allocation<br/>[main.go]"]
  node_interface_setup["WireGuard interface<br/>[main.go]"]
  node_nat_setup["NAT setup<br/>[main.go]"]
end

node_operator(("Server operator"))
node_vpn_client(("VPN client"))
node_host_network["Linux network host"]
node_wireguard["WireGuard device"]
node_http_user(("API user"))

node_operator -->|"starts"| node_server_app
node_server_app -->|"loads or creates"| node_config_store
node_server_app -->|"starts"| node_lifecycle
node_lifecycle -->|"brings up"| node_interface_setup
node_interface_setup -->|"configures link"| node_host_network
node_lifecycle -->|"configures peers"| node_peer_setup
node_peer_setup -->|"applies peers"| node_wireguard
node_server_app -->|"starts"| node_api_server
node_http_user -->|"sends requests"| node_api_server
node_api_server -->|"wraps requests"| node_user_context
node_user_context -->|"dispatches"| node_client_management
node_client_management -->|"reads or changes"| node_client_record
node_client_management -->|"allocates address"| node_ip_allocator
node_client_management -->|"creates keys"| node_key_generation
node_client_management -->|"reconfigures peers"| node_peer_setup
node_client_management -->|"serves client"| node_client_export
node_client_export -->|"returns config or QR"| node_vpn_client
node_key_generation -->|"fills key fields"| node_client_record
node_operator -.->|"configures manually"| node_nat_setup
node_nat_setup -.->|"sets masquerading"| node_host_network

click node_server_app "https://github.com/smolkar/wireguard_surf/blob/master/main.go"
click node_lifecycle "https://github.com/smolkar/wireguard_surf/blob/master/main.go"
click node_peer_setup "https://github.com/smolkar/wireguard_surf/blob/master/main.go"
click node_api_server "https://github.com/smolkar/wireguard_surf/blob/master/api.go"
click node_user_context "https://github.com/smolkar/wireguard_surf/blob/master/api.go"
click node_client_management "https://github.com/smolkar/wireguard_surf/blob/master/api.go"
click node_client_export "https://github.com/smolkar/wireguard_surf/blob/master/api.go"
click node_client_record "https://github.com/smolkar/wireguard_surf/blob/master/Configuration.go"
click node_config_store "https://github.com/smolkar/wireguard_surf/blob/master/Configuration.go"
click node_key_generation "https://github.com/smolkar/wireguard_surf/blob/master/Configuration.go"
click node_ip_allocator "https://github.com/smolkar/wireguard_surf/blob/master/main.go"
click node_interface_setup "https://github.com/smolkar/wireguard_surf/blob/master/main.go"
click node_nat_setup "https://github.com/smolkar/wireguard_surf/blob/master/main.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_server_app,node_lifecycle,node_peer_setup,node_vpn_client,node_http_user toneBlue
class node_api_server,node_user_context,node_client_management,node_client_export toneAmber
class node_client_record,node_config_store,node_key_generation,node_operator toneMint
class node_ip_allocator,node_interface_setup,node_nat_setup toneRose
class node_host_network,node_wireguard toneIndigo
```

## Components

### VPN server

- [Server process](https://github.com/smolkar/wireguard_surf/blob/master/main.go): `main.go`
- [Server lifecycle](https://github.com/smolkar/wireguard_surf/blob/master/main.go): `main.go`
- [Peer configuration](https://github.com/smolkar/wireguard_surf/blob/master/main.go): `main.go`

### HTTP API

- [HTTP API server](https://github.com/smolkar/wireguard_surf/blob/master/api.go): `api.go`
- [User context](https://github.com/smolkar/wireguard_surf/blob/master/api.go): `api.go`
- [Client management](https://github.com/smolkar/wireguard_surf/blob/master/api.go): `api.go`
- [Client config export](https://github.com/smolkar/wireguard_surf/blob/master/api.go): `api.go`

### Configuration

- [Client records](https://github.com/smolkar/wireguard_surf/blob/master/Configuration.go): `Configuration.go`
- [Server config file](https://github.com/smolkar/wireguard_surf/blob/master/Configuration.go): `Configuration.go`
- [Key generation](https://github.com/smolkar/wireguard_surf/blob/master/Configuration.go): `Configuration.go`

### Network setup

- [Client IP allocation](https://github.com/smolkar/wireguard_surf/blob/master/main.go): `main.go`
- [WireGuard interface](https://github.com/smolkar/wireguard_surf/blob/master/main.go): `main.go`
- [NAT setup](https://github.com/smolkar/wireguard_surf/blob/master/main.go): `main.go`

### Other components

- **Server operator**
- **VPN client**
- **Linux network host**
- **WireGuard device**
- **API user**

## Connections

- Server operator → Server process: starts
- Server process → Server config file: loads or creates
- Server process → Server lifecycle: starts
- Server lifecycle → WireGuard interface: brings up
- WireGuard interface → Linux network host: configures link
- Server lifecycle → Peer configuration: configures peers
- Peer configuration → WireGuard device: applies peers
- Server process → HTTP API server: starts
- API user → HTTP API server: sends requests
- HTTP API server → User context: wraps requests
- User context → Client management: dispatches
- Client management → Client records: reads or changes
- Client management → Client IP allocation: allocates address
- Client management → Key generation: creates keys
- Client management → Peer configuration: reconfigures peers
- Client management → Client config export: serves client
- Client config export → VPN client: returns config or QR
- Key generation → Client records: fills key fields
- Server operator → NAT setup: configures manually
- NAT setup → Linux network host: sets masquerading