# julioramos0/gopenvpn architecture

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

- Interactive diagram: https://gitdiagram.com/julioramos0/gopenvpn
- Repository: https://github.com/julioramos0/gopenvpn

## Overview

GopenVPN is a web-managed OpenVPN 3 SSO client that also provides VPN-accessible reverse proxies and outbound SSH/AWS SSM tunnels. Users configure and start the VPN through the browser, complete provider authentication, and the UI polls tunnel status; they can then manage proxy rules and tunnel definitions and lifecycles. The Go server routes these requests to VPN, proxy, and tunnel services. The README documents sidecar networking as a deployment capability, but its container wiring is outside the runtime source map. Relationships are limited to shown calls and documented UI flows; unsampled modules are not treated as inspected.

Main entry points: [`pkg/tunnel/manager.go`](https://github.com/julioramos0/gopenvpn/blob/main/pkg/tunnel/manager.go) (Tunnel process manager), [`web/app.js`](https://github.com/julioramos0/gopenvpn/blob/main/web/app.js) (VPN and admin UI), [`pkg/proxy/proxy.go`](https://github.com/julioramos0/gopenvpn/blob/main/pkg/proxy/proxy.go) (Reverse proxy service), [`api/handlers_vpn.go`](https://github.com/julioramos0/gopenvpn/blob/main/api/handlers_vpn.go) (VPN API handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_web_assets["Embedded web assets<br/>[embed.go]"]
  node_web_ui["VPN and admin UI<br/>[app.js]"]
  node_tunnel_ui["Tunnel configuration UI<br/>[app.js]"]
end

subgraph group_server["HTTP server"]
  node_server_main["HTTP server<br/>[main.go]"]
  node_configuration["Environment config<br/>[config.go]"]
  node_vpn_api["VPN API handlers<br/>[handlers_vpn.go]"]
  node_proxy_api["Proxy API handlers<br/>[handlers_proxy.go]"]
  node_tunnel_api["Tunnel API handlers"]
end

subgraph group_vpn["VPN connection"]
  node_vpn_runtime["VPN session runtime<br/>[vpn.go]"]
end

subgraph group_proxy["Reverse proxy"]
  node_proxy_service["Reverse proxy service<br/>[proxy.go]"]
  node_proxy_rules[("Proxy rule storage<br/>[proxy.go]")]
end

subgraph group_tunnels["Outbound tunnels"]
  node_tunnel_runtime["Tunnel process manager<br/>[manager.go]"]
  node_tunnel_definitions[("Tunnel definitions<br/>[models.go]")]
end

node_user(("Operator"))
node_browser(("Browser"))
node_provider(("VPN login portal"))
node_openvpn["OpenVPN 3 and DBus"]
node_tun_interface["tun0 interface"]
node_proxy_targets["VPN-side web targets"]
node_ssh_service["SSH service"]
node_aws_service["AWS EC2 and SSM"]

node_user -->|"uses"| node_browser
node_browser -->|"loads"| node_web_ui
node_server_main -->|"loads config"| node_configuration
node_server_main -->|"serves"| node_web_assets
node_web_assets -->|"embeds"| node_web_ui
node_web_ui -->|"requests VPN"| node_vpn_api
node_web_ui -->|"manages proxies"| node_proxy_api
node_web_ui -->|"manages tunnels"| node_tunnel_api
node_vpn_api -->|"starts and stops"| node_vpn_runtime
node_vpn_api -->|"starts and stops"| node_proxy_service
node_vpn_api -->|"stops all"| node_tunnel_runtime
node_vpn_runtime -->|"runs commands"| node_openvpn
node_vpn_runtime -->|"checks status"| node_tun_interface
node_browser -->|"completes SSO"| node_provider
node_proxy_api -->|"manages rules"| node_proxy_service
node_server_main -->|"loads rules"| node_proxy_service
node_proxy_service -->|"reads and writes"| node_proxy_rules
node_proxy_service -->|"forwards requests"| node_proxy_targets
node_tunnel_api -->|"CRUD operations"| node_tunnel_definitions
node_tunnel_api -->|"starts and stops"| node_tunnel_runtime
node_tunnel_runtime -->|"runs SSH"| node_ssh_service
node_tunnel_runtime -->|"runs AWS CLI"| node_aws_service
node_tunnel_runtime -->|"forwards SSM ports"| node_tunnel_runtime

click node_server_main "https://github.com/julioramos0/gopenvpn/blob/main/cmd/server/main.go"
click node_configuration "https://github.com/julioramos0/gopenvpn/blob/main/config/config.go"
click node_vpn_api "https://github.com/julioramos0/gopenvpn/blob/main/api/handlers_vpn.go"
click node_proxy_api "https://github.com/julioramos0/gopenvpn/blob/main/api/handlers_proxy.go"
click node_tunnel_api "https://github.com/julioramos0/gopenvpn/blob/main/api/handlers_tunnels.go"
click node_web_assets "https://github.com/julioramos0/gopenvpn/blob/main/web/embed.go"
click node_web_ui "https://github.com/julioramos0/gopenvpn/blob/main/web/app.js"
click node_vpn_runtime "https://github.com/julioramos0/gopenvpn/blob/main/pkg/vpn/vpn.go"
click node_proxy_service "https://github.com/julioramos0/gopenvpn/blob/main/pkg/proxy/proxy.go"
click node_proxy_rules "https://github.com/julioramos0/gopenvpn/blob/main/pkg/proxy/proxy.go"
click node_tunnel_ui "https://github.com/julioramos0/gopenvpn/blob/main/web/app.js"
click node_tunnel_runtime "https://github.com/julioramos0/gopenvpn/blob/main/pkg/tunnel/manager.go"
click node_tunnel_definitions "https://github.com/julioramos0/gopenvpn/blob/main/pkg/tunnel/models.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_assets,node_web_ui,node_tunnel_ui,node_browser toneBlue
class node_server_main,node_configuration,node_vpn_api,node_proxy_api,node_tunnel_api toneAmber
class node_vpn_runtime toneMint
class node_proxy_service,node_proxy_rules toneRose
class node_tunnel_runtime,node_tunnel_definitions,node_user,node_provider,node_openvpn,node_tun_interface,node_proxy_targets,node_ssh_service,node_aws_service toneIndigo
```

## Components

### Web interface

- [Embedded web assets](https://github.com/julioramos0/gopenvpn/blob/main/web/embed.go): `web/embed.go`
- [VPN and admin UI](https://github.com/julioramos0/gopenvpn/blob/main/web/app.js): `web/app.js`
- [Tunnel configuration UI](https://github.com/julioramos0/gopenvpn/blob/main/web/app.js): `web/app.js`

### HTTP server

- [HTTP server](https://github.com/julioramos0/gopenvpn/blob/main/cmd/server/main.go): `cmd/server/main.go`
- [Environment config](https://github.com/julioramos0/gopenvpn/blob/main/config/config.go): `config/config.go`
- [VPN API handlers](https://github.com/julioramos0/gopenvpn/blob/main/api/handlers_vpn.go): `api/handlers_vpn.go`
- [Proxy API handlers](https://github.com/julioramos0/gopenvpn/blob/main/api/handlers_proxy.go): `api/handlers_proxy.go`
- [Tunnel API handlers](https://github.com/julioramos0/gopenvpn/blob/main/api/handlers_tunnels.go): `api/handlers_tunnels.go`

### VPN connection

- [VPN session runtime](https://github.com/julioramos0/gopenvpn/blob/main/pkg/vpn/vpn.go): `pkg/vpn/vpn.go`

### Reverse proxy

- [Reverse proxy service](https://github.com/julioramos0/gopenvpn/blob/main/pkg/proxy/proxy.go): `pkg/proxy/proxy.go`
- [Proxy rule storage](https://github.com/julioramos0/gopenvpn/blob/main/pkg/proxy/proxy.go): `pkg/proxy/proxy.go`

### Outbound tunnels

- [Tunnel process manager](https://github.com/julioramos0/gopenvpn/blob/main/pkg/tunnel/manager.go): `pkg/tunnel/manager.go`
- [Tunnel definitions](https://github.com/julioramos0/gopenvpn/blob/main/pkg/tunnel/models.go): `pkg/tunnel/models.go`

### Other components

- **Operator**
- **Browser**
- **VPN login portal**
- **OpenVPN 3 and DBus**
- **tun0 interface**
- **VPN-side web targets**
- **SSH service**
- **AWS EC2 and SSM**

## Connections

- Operator → Browser: uses (evidence: `README.md`)
- Browser → VPN and admin UI: loads (evidence: `README.md`)
- HTTP server → Environment config: loads config (evidence: `cmd/server/main.go`)
- HTTP server → Embedded web assets: serves (evidence: `cmd/server/main.go`)
- Embedded web assets → VPN and admin UI: embeds (evidence: `web/embed.go`)
- VPN and admin UI → VPN API handlers: requests VPN (evidence: `web/app.js`)
- VPN and admin UI → Proxy API handlers: manages proxies (evidence: `web/app.js`)
- VPN and admin UI → Tunnel API handlers: manages tunnels (evidence: `web/app.js`)
- VPN API handlers → VPN session runtime: starts and stops (evidence: `api/handlers_vpn.go`)
- VPN API handlers → Reverse proxy service: starts and stops (evidence: `api/handlers_vpn.go`)
- VPN API handlers → Tunnel process manager: stops all (evidence: `api/handlers_vpn.go`)
- VPN session runtime → OpenVPN 3 and DBus: runs commands (evidence: `pkg/vpn/vpn.go`)
- VPN session runtime → tun0 interface: checks status (evidence: `pkg/vpn/vpn.go`)
- Browser → VPN login portal: completes SSO (evidence: `README.md`)
- Proxy API handlers → Reverse proxy service: manages rules (evidence: `api/handlers_proxy.go`)
- HTTP server → Reverse proxy service: loads rules (evidence: `cmd/server/main.go`)
- Reverse proxy service → Proxy rule storage: reads and writes (evidence: `pkg/proxy/proxy.go`)
- Reverse proxy service → VPN-side web targets: forwards requests (evidence: `pkg/proxy/proxy.go`)
- Tunnel API handlers → Tunnel definitions: CRUD operations (evidence: `api/handlers_tunnels.go`)
- Tunnel API handlers → Tunnel process manager: starts and stops (evidence: `api/handlers_tunnels.go`)
- Tunnel process manager → SSH service: runs SSH (evidence: `pkg/tunnel/manager.go`)
- Tunnel process manager → AWS EC2 and SSM: runs AWS CLI (evidence: `pkg/tunnel/manager.go`)
- Tunnel process manager → Tunnel process manager: forwards SSM ports (evidence: `pkg/tunnel/manager.go`)
