# vpn-vendor/vpn architecture

> Architecture diagram of the GitHub repository vpn-vendor/vpn, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vpn-vendor/vpn
- Repository: https://github.com/vpn-vendor/vpn

## Overview

##### Project type and purpose
- This is a server-provisioning automation script (vpn.sh) written in Bash.
- Its goal is to install, configure, and manage VPN services (WireGuard, OpenVPN), network tools, a local web interface, and an optional Telegram bot for remote control.

##### High-level architecture
- The entire system is driven by a single Bash script (`vpn.sh`) that executes in sequence on an Ubuntu 22.04 host.
- It interacts with:
- The OS package manager (apt) to install/remove packages.
- System services (systemd, iptables).
- Networking components (WireGuard, OpenVPN, DHCP).
- A local web server (Apache2) for VPN selection.
- An optional Python-based Telegram bot.

##### Main components and relationships
A. Orchestrator (vpn.sh) – central component
- Executed with root privileges.
- Calls apt, systemctl, iptables, resolvconf, etc.
B. Package Manager & System
- apt / dpkg: installs packages listed in the script.
- systemd: enables & starts services (isc-dhcp-server, network-manager, openvpn, wg-quick@…).
- iptables-persistent: stores firewall rules applied by the script.
C. Networking Services
- wireguard: VPN tunnel interface(s).
- openvpn: VPN daemon(s).
- isc-dhcp-server: DHCP assignments on internal nets (if used).
- network-manager: optional, for GUI networks.
D. Local Web Interface
- apache2 serves a simple site letting users switch between VPN configs.
- The script deploys config files to `/var/www/html` (or similar) and adjusts Apache vhosts.
E. Telegram Bot (optional)
- A small Python utility installed via apt.
- Interacts with Telegram’s API to allow remote server commands.

Interactions:
User → vpn.sh CLI
vpn.sh → apt → install/remove packages
vpn.sh → systemctl → enable/start services
vpn.sh → iptables → apply firewall rules
vpn.sh → writes configs → /etc/openvpn/, /etc/wireguard/, /var/www/html/
apache2 ← serves UI ← User’s browser
python-telegram-bot ← communicates ← Telegram API

##### Architectural patterns and principles
- Imperative provisioning script (no agents, one-shot).
- Separation of concerns: package installation, service configuration, UI deployment, cleanup.
- Idempotence emphasis: check before installing/removing packages.
- Optional components guarded by OS checks (Ubuntu 22.04 vs others).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Users
    UserCLI["User (CLI)"]:::external
    UserWeb["User (Web Browser)"]:::external

    %% Orchestration Layer
    subgraph "Orchestration"
        Orch["vpn.sh (Bash script)"]:::orchestration
    end

    %% OS & Package Management
    subgraph "OS & Package Management"
        APT["apt / dpkg"]:::os
        SYSTEMD["systemd"]:::os
        IPT["iptables"]:::os
    end

    %% Service Layer
    subgraph "VPN & Networking Services"
        WG["WireGuard service"]:::service
        OV["OpenVPN service"]:::service
        DHCP["isc-dhcp-server"]:::service
        NM["network-manager"]:::service
    end

    subgraph "Web UI Service"
        APACHE["Apache2 Web UI"]:::service
    end

    %% Configuration Storage
    subgraph "Configuration Storage"
        ETC["/etc/openvpn/, /etc/wireguard/"]:::storage
        WWW["/var/www/html/"]:::storage
    end

    %% Optional Telegram Bot
    subgraph "Optional: Telegram Bot"
        BOT["python-telegram-bot"]:::external
        API["Telegram API"]:::external
    end

    %% Documentation
    DOC["Project Documentation (README)"]:::docs

    %% Connections
    UserCLI -->|"executes"| Orch
    Orch -->|"install/remove packages"| APT
    Orch -->|"enable/start services"| SYSTEMD
    Orch -->|"apply firewall rules"| IPT
    Orch -->|"write configs"| ETC
    Orch -->|"deploy web UI"| WWW
    Orch -->|"install bot (optional)"| APT
    APT --> WG
    APT --> OV
    APT --> DHCP
    APT --> NM
    APT --> APACHE
    SYSTEMD --> WG
    SYSTEMD --> OV
    SYSTEMD --> DHCP
    SYSTEMD --> NM
    SYSTEMD --> APACHE
    IPT --> WG
    IPT --> OV
    WWW --> APACHE
    UserWeb -->|"HTTP requests"| APACHE
    BOT -->|"polls & commands"| API
    API --> BOT
    DOC -.-> Orch

    %% Click Events
    click Orch "https://github.com/vpn-vendor/vpn/blob/main/./vpn.sh"
    click DOC "https://github.com/vpn-vendor/vpn/blob/main/./README.md"

    %% Styles
    classDef orchestration fill:#FFD700,stroke:#333,stroke-width:1px
    classDef os fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef service fill:#90EE90,stroke:#333,stroke-width:1px
    classDef storage fill:#FFA07A,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef docs fill:#F5DEB3,stroke:#333,stroke-width:1px
```
