# dmitriykuptsov/soho-vpn-over-tls architecture

> Architecture diagram of the GitHub repository dmitriykuptsov/soho-vpn-over-tls, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dmitriykuptsov/soho-vpn-over-tls
- Repository: https://github.com/dmitriykuptsov/soho-vpn-over-tls

## Overview

SOHO VPN over TLS creates an encrypted tunnel between a client box on the local network and a VPN server. The client authenticates, receives tunnel parameters, changes routing and DNS, then relays traffic between a TUN interface and TLS; the server authenticates, assigns an address, and forwards tunnel traffic. The graph includes the shared protocol and connection state plus network setup capabilities. Relationships follow the excerpts and README; some server-side networking details are documented but their implementation calls were not sampled.

Main entry points: [`src/client/client.py`](https://github.com/dmitriykuptsov/soho-vpn-over-tls/blob/master/src/client/client.py) (Client session), [`src/server/server.py`](https://github.com/dmitriykuptsov/soho-vpn-over-tls/blob/master/src/server/server.py) (Server session), [`src/common/database.py`](https://github.com/dmitriykuptsov/soho-vpn-over-tls/blob/master/src/common/database.py) (File authentication), [`src/common/tun.py`](https://github.com/dmitriykuptsov/soho-vpn-over-tls/blob/master/src/common/tun.py) (Client TUN interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["VPN client"]
  node_client_app["Client session<br/>[client.py]"]
  node_client_config["Client settings<br/>[config.py]"]
end

subgraph group_server["VPN server"]
  node_server_app["Server session<br/>[server.py]"]
  node_server_config["Server settings<br/>[config.py]"]
  node_credentials[("Credential records<br/>[database.dat]")]
  node_address_pool["Client IP pool<br/>[pool.py]"]
  node_auth_database["File authentication<br/>[database.py]"]
end

subgraph group_network["Tunnel networking"]
  node_client_tun["Client TUN interface<br/>[tun.py]"]
  node_server_tun["Server TUN interface<br/>[tun.py]"]
  node_routing["Route configuration<br/>[routing.py]"]
  node_dns["DNS configuration<br/>[dns.py]"]
  node_nat["Forwarding and NAT<br/>[nat.py]"]
end

subgraph group_shared["Shared runtime"]
  node_wire_protocol["VPN packet protocol<br/>[packet.py]"]
  node_connection_state["Connection state<br/>[state.py]"]
end

node_user(("SOHO network"))
node_status_user(("Local status client"))
node_tls_peer{{"TLS connection"}}
node_external_network(("Internet"))

node_user -->|"starts VPN"| node_client_app
node_client_app -->|"reads settings"| node_client_config
node_client_app -->|"opens TLS"| node_tls_peer
node_server_app -->|"accepts TLS"| node_tls_peer
node_client_app -->|"encodes and parses"| node_wire_protocol
node_server_app -->|"encodes and parses"| node_wire_protocol
node_client_app -->|"updates state"| node_connection_state
node_server_app -->|"updates state"| node_connection_state
node_server_app -->|"reads settings"| node_server_config
node_server_app -->|"checks credentials"| node_auth_database
node_auth_database -->|"loads records"| node_credentials
node_server_app -->|"leases address"| node_address_pool
node_server_app -->|"creates and relays"| node_server_tun
node_client_app -->|"creates and relays"| node_client_tun
node_client_app -->|"configures routes"| node_routing
node_client_app -->|"configures DNS"| node_dns
node_client_app -->|"restores networking"| node_nat
node_status_user -->|"requests status"| node_client_app
node_server_app -.->|"uses forwarding"| node_nat
node_client_tun -.->|"carries network traffic"| node_user
node_server_tun -.->|"forwards traffic"| node_external_network

click node_client_app "https://github.com/dmitriykuptsov/soho-vpn-over-tls/blob/master/src/client/client.py"
click node_client_config "https://github.com/dmitriykuptsov/soho-vpn-over-tls/blob/master/src/client/config.py"
click node_server_app "https://github.com/dmitriykuptsov/soho-vpn-over-tls/blob/master/src/server/server.py"
click node_server_config "https://github.com/dmitriykuptsov/soho-vpn-over-tls/blob/master/src/server/config.py"
click node_credentials "https://github.com/dmitriykuptsov/soho-vpn-over-tls/blob/master/src/server/database.dat"
click node_wire_protocol "https://github.com/dmitriykuptsov/soho-vpn-over-tls/blob/master/src/common/packet.py"
click node_connection_state "https://github.com/dmitriykuptsov/soho-vpn-over-tls/blob/master/src/common/state.py"
click node_address_pool "https://github.com/dmitriykuptsov/soho-vpn-over-tls/blob/master/src/common/pool.py"
click node_auth_database "https://github.com/dmitriykuptsov/soho-vpn-over-tls/blob/master/src/common/database.py"
click node_client_tun "https://github.com/dmitriykuptsov/soho-vpn-over-tls/blob/master/src/common/tun.py"
click node_server_tun "https://github.com/dmitriykuptsov/soho-vpn-over-tls/blob/master/src/common/tun.py"
click node_routing "https://github.com/dmitriykuptsov/soho-vpn-over-tls/blob/master/src/common/routing.py"
click node_dns "https://github.com/dmitriykuptsov/soho-vpn-over-tls/blob/master/src/common/dns.py"
click node_nat "https://github.com/dmitriykuptsov/soho-vpn-over-tls/blob/master/src/common/nat.py"

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_client_app,node_client_config,node_status_user toneBlue
class node_server_app,node_server_config,node_credentials,node_address_pool,node_auth_database toneAmber
class node_client_tun,node_server_tun,node_routing,node_dns,node_nat toneMint
class node_wire_protocol,node_connection_state toneRose
class node_user,node_tls_peer,node_external_network toneIndigo
```

## Components

### VPN client

- [Client session](https://github.com/dmitriykuptsov/soho-vpn-over-tls/blob/master/src/client/client.py): `src/client/client.py`
- [Client settings](https://github.com/dmitriykuptsov/soho-vpn-over-tls/blob/master/src/client/config.py): `src/client/config.py`

### VPN server

- [Server session](https://github.com/dmitriykuptsov/soho-vpn-over-tls/blob/master/src/server/server.py): `src/server/server.py`
- [Server settings](https://github.com/dmitriykuptsov/soho-vpn-over-tls/blob/master/src/server/config.py): `src/server/config.py`
- [Credential records](https://github.com/dmitriykuptsov/soho-vpn-over-tls/blob/master/src/server/database.dat): `src/server/database.dat`
- [Client IP pool](https://github.com/dmitriykuptsov/soho-vpn-over-tls/blob/master/src/common/pool.py): `src/common/pool.py`
- [File authentication](https://github.com/dmitriykuptsov/soho-vpn-over-tls/blob/master/src/common/database.py): `src/common/database.py`

### Tunnel networking

- [Client TUN interface](https://github.com/dmitriykuptsov/soho-vpn-over-tls/blob/master/src/common/tun.py): `src/common/tun.py`
- [Server TUN interface](https://github.com/dmitriykuptsov/soho-vpn-over-tls/blob/master/src/common/tun.py): `src/common/tun.py`
- [Route configuration](https://github.com/dmitriykuptsov/soho-vpn-over-tls/blob/master/src/common/routing.py): `src/common/routing.py`
- [DNS configuration](https://github.com/dmitriykuptsov/soho-vpn-over-tls/blob/master/src/common/dns.py): `src/common/dns.py`
- [Forwarding and NAT](https://github.com/dmitriykuptsov/soho-vpn-over-tls/blob/master/src/common/nat.py): `src/common/nat.py`

### Shared runtime

- [VPN packet protocol](https://github.com/dmitriykuptsov/soho-vpn-over-tls/blob/master/src/common/packet.py): `src/common/packet.py`
- [Connection state](https://github.com/dmitriykuptsov/soho-vpn-over-tls/blob/master/src/common/state.py): `src/common/state.py`

### Other components

- **SOHO network**
- **Local status client**
- **TLS connection**
- **Internet**

## Connections

- SOHO network → Client session: starts VPN (evidence: `README.md`)
- Client session → Client settings: reads settings (evidence: `src/client/client.py`)
- Client session → TLS connection: opens TLS (evidence: `src/client/client.py`)
- Server session → TLS connection: accepts TLS (evidence: `src/server/server.py`)
- Client session → VPN packet protocol: encodes and parses (evidence: `src/client/client.py`)
- Server session → VPN packet protocol: encodes and parses (evidence: `src/server/server.py`)
- Client session → Connection state: updates state (evidence: `src/client/client.py`)
- Server session → Connection state: updates state (evidence: `src/server/server.py`)
- Server session → Server settings: reads settings (evidence: `src/server/server.py`)
- Server session → File authentication: checks credentials (evidence: `src/server/server.py`)
- File authentication → Credential records: loads records
- Server session → Client IP pool: leases address (evidence: `src/server/server.py`)
- Server session → Server TUN interface: creates and relays (evidence: `src/server/server.py`)
- Client session → Client TUN interface: creates and relays (evidence: `src/client/client.py`)
- Client session → Route configuration: configures routes (evidence: `src/client/client.py`)
- Client session → DNS configuration: configures DNS (evidence: `src/client/client.py`)
- Client session → Forwarding and NAT: restores networking (evidence: `src/client/client.py`)
- Local status client → Client session: requests status (evidence: `src/client/client.py`)
- Server session → Forwarding and NAT: uses forwarding (evidence: `README.md`)
- Client TUN interface → SOHO network: carries network traffic (evidence: `README.md`)
- Server TUN interface → Internet: forwards traffic (evidence: `README.md`)