# thevickypedia/vpn-server architecture

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

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

## Overview

Step 1: Identify Project Type and Purpose
- This is an open-source Python SDK/CLI tool (“vpn-server”) for provisioning OpenVPN servers on AWS EC2 on demand.
- Primary use case: programmatically create, test, and delete VPN servers via a Python interface (`vpn.VPNServer`), leveraging AWS services (EC2, Route53).

Step 2: Analyze the File Structure
- Top-level:
- `.github/workflows` – CI pipelines for docs, PyPI publishing, markdown validation
- `doc_gen/` – custom Sphinx configuration for generating docs
- `docs/` – built documentation site
- `vpn/` – core Python package
- Inside `vpn/`:
- `main.py` – entry point that exposes `VPNServer`
- `models/` – domain modules:
– `config.py` – holds configuration schema/validation
– `server.py` – logic for EC2 instance provisioning, teardown
– `route53.py` – DNS management
– `image_factory.py` – chooses AMI images
– `logger.py` – logging abstraction
– `util.py` & `exceptions.py` – helper functions & custom errors
- `pyproject.toml` & `requirements.txt` – packaging and dependencies (boto3, Sphinx, etc.)
- CI & Release: GitHub Actions workflows, pre-commit hooks for linting and docs generation.

Step 3: Examine README for Insights
- Key operations: `create_vpn_server()`, `test_vpn()`, `delete_vpn_server()`
- External dependencies: AWS SDK (boto3), OpenVPN AMI
- Docs build via Sphinx; code quality via flake8/isort

a. Main Components:
1. Client Layer: User’s Python script or CLI
2. vpn.VPNServer API: orchestrator class
3. Models Package:
- Config Loader
- ImageFactory (AMI selection)
- Server Manager (EC2 provisioning, OpenVPN setup)
- Route53 Manager (DNS records)
- Logger & Utils
4. AWS Services:
- EC2 (Instances, Security Groups)
- Route53 (DNS zones & records)
5. External Tools:
- OpenVPN software on AMI
- GitHub Actions (CI/CD)
- Sphinx (docs build)

b. Relationships & Data Flow:
- Client → VPNServer.create_vpn_server()
- VPNServer reads config → calls Config model
- VPNServer → ImageFactory to select AMI
- VPNServer → Server model → AWS EC2 API calls to launch instance & configure OpenVPN
- VPNServer → Route53 model → AWS Route53 API calls to create DNS entry
- Throughout: Logger logs status; exceptions bubble up
- GitHub Actions pipelines trigger on commit: run pre-commit, build & publish docs, publish package to PyPI

c. Architectural Patterns & Principles:
- Modular separation: each concern in its own model
- Factory pattern in `ImageFactory`
- Single-responsibility: `VPNServer` orchestrates, models implement details
- Configuration-driven provisioning

d. Key Technologies/Frameworks:
- Python 3.8+
- AWS SDK (boto3)
- Sphinx for documentation
- GitHub Actions for CI/CD
- flake8/isort pre-commit hooks

- For this SDK/CLI tool:
- Orchestration flow from client call to AWS service interactions.
- Model as a distinct module block.
- External dependencies (OpenVPN AMI, AWS endpoints).
- CI/CD pipeline as a side process.

Step 6: Diagramming Guidelines
- Use clear labels for each component block (e.g., “ImageFactory”, “ServerManager”).
– Blue rectangles for in-process modules (Python package).
– Gray parallelograms for external tools (OpenVPN AMI, GitHub Actions).

Step 7: Detail & Labels
- Call out config inputs (e.g., VPC, subnet IDs, DNS name).
- Error handling path: exceptions thrown back to client.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Layer"
        Client["User Script / CLI"]:::code
    end

    subgraph "VPN SDK (vpn/)"
        VPNServer["VPNServer"]:::code
        Config["Config Loader"]:::code
        ImageFactory["ImageFactory"]:::code
        ServerMgr["Server Manager"]:::code
        RouteMgr["Route53 Manager"]:::code
        Logger["Logger"]:::code
        Util["Utilities"]:::code
        Exceptions["Exceptions"]:::code
    end

    subgraph "AWS Services"
        EC2["EC2 (RunInstances)"]:::aws
        R53["Route53 (ChangeResourceRecordSets)"]:::aws
    end

    subgraph "External Tools"
        OpenVPN["OpenVPN AMI"]:::ext
        ActionsMd["Markdown CI"]:::ext
        ActionsPy["Publish CI"]:::ext
        PreCommit["Pre-commit Hooks"]:::ext
        Sphinx["Sphinx Docs"]:::ext
    end

    subgraph "Documentation"
        DocSource["Sphinx Source"]:::code
        DocIndex["index.rst"]:::code
        BuiltDocs["Built Site (docs/)"]:::ext
    end

    subgraph "Packaging & Config"
        Requirements["requirements.txt"]:::code
        Pyproject["pyproject.toml"]:::code
        PreCommitCfg[".pre-commit-config.yaml"]:::code
        PreCommitScript["pre_commit.sh"]:::code
    end

    Client -->|"create_vpn_server()"| VPNServer
    VPNServer -->|"load_config()"| Config
    VPNServer -->|"select_ami()"| ImageFactory
    VPNServer -->|"provision()"| ServerMgr
    VPNServer -->|"create_dns()"| RouteMgr
    ServerMgr -->|"RunInstances()"| EC2
    ServerMgr -->|"install/configure"| OpenVPN
    RouteMgr -->|"ChangeResourceRecordSets()"| R53
    VPNServer -.->|"logs"| Logger
    VPNServer -.->|"uses"| Util
    Config -.->|"raises"| Exceptions

    ActionsMd -->|"on_commit"| PreCommit
    PreCommit -->|"lint/docs"| ActionsMd
    ActionsMd -->|"trigger_build"| DocSource
    ActionsMd -->|"trigger_build"| DocIndex
    DocSource -->|"build"| BuiltDocs
    ActionsPy -->|"reads_deps"| Requirements
    ActionsPy -->|"reads_config"| Pyproject
    PreCommit -->|"reads_config"| PreCommitCfg
    PreCommit -->|"runs_script"| PreCommitScript

    classDef code fill:#D0E6FF,stroke:#0366d6,color:#0366d6;
    classDef aws fill:#FFE3B8,stroke:#E09E00,color:#E09E00;
    classDef ext fill:#E2E2E2,stroke:#A8A8A8,color:#333;

    click Client "https://github.com/thevickypedia/vpn-server/blob/main/vpn/main.py"
    click VPNServer "https://github.com/thevickypedia/vpn-server/blob/main/vpn/main.py"
    click Config "https://github.com/thevickypedia/vpn-server/blob/main/vpn/models/config.py"
    click ImageFactory "https://github.com/thevickypedia/vpn-server/blob/main/vpn/models/image_factory.py"
    click ServerMgr "https://github.com/thevickypedia/vpn-server/blob/main/vpn/models/server.py"
    click RouteMgr "https://github.com/thevickypedia/vpn-server/blob/main/vpn/models/route53.py"
    click Logger "https://github.com/thevickypedia/vpn-server/blob/main/vpn/models/logger.py"
    click Util "https://github.com/thevickypedia/vpn-server/blob/main/vpn/models/util.py"
    click Exceptions "https://github.com/thevickypedia/vpn-server/blob/main/vpn/models/exceptions.py"
    click Requirements "https://github.com/thevickypedia/vpn-server/blob/main/vpn/requirements.txt"
    click Pyproject "https://github.com/thevickypedia/vpn-server/blob/main/pyproject.toml"
    click PreCommitCfg "https://github.com/thevickypedia/vpn-server/blob/main/.pre-commit-config.yaml"
    click PreCommitScript "https://github.com/thevickypedia/vpn-server/blob/main/pre_commit.sh"
    click ActionsMd "https://github.com/thevickypedia/vpn-server/blob/main/.github/workflows/markdown.yml"
    click ActionsPy "https://github.com/thevickypedia/vpn-server/blob/main/.github/workflows/python-publish.yml"
    click DocSource "https://github.com/thevickypedia/vpn-server/blob/main/doc_gen/conf.py"
    click DocIndex "https://github.com/thevickypedia/vpn-server/blob/main/doc_gen/index.rst"
```
