# omzsk/proxy-farm architecture

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

- Interactive diagram: https://gitdiagram.com/omzsk/proxy-farm
- Repository: https://github.com/omzsk/proxy-farm

## Overview

Proxy Farm turns VPN accounts or configuration files into independently managed, local SOCKS5/HTTP proxy ports. The main workflow is provider/location resolution in the manager, account binding and per-port Docker tunnel startup, then proxy health and status management through the web UI or CLI. The README also documents HMA certificate and activation onboarding, file imports, rotations, and proxy checks. Node driver internals and UI request wiring were not sampled, so those relationships are shown only where the README or excerpts support them.

Main entry points: [`manager/farm.py`](https://github.com/omzsk/proxy-farm/blob/main/manager/farm.py) (Farm manager), [`node/entrypoint.sh`](https://github.com/omzsk/proxy-farm/blob/main/node/entrypoint.sh) (Tunnel node), [`manager/vendors.py`](https://github.com/omzsk/proxy-farm/blob/main/manager/vendors.py) (Provider registry), [`manager/hma_activation.py`](https://github.com/omzsk/proxy-farm/blob/main/manager/hma_activation.py) (HMA activation check)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_onboard["Provider onboarding"]
  node_hma_import["HMA certificate import<br/>[farm.py]"]
  node_activation["HMA activation check<br/>[hma_activation.py]"]
  node_provider_registry["Provider registry<br/>[vendors.py]"]
  node_server_catalog["Server locations<br/>[vendors.py]"]
end

subgraph group_manager["Farm management"]
  node_farm_manager["Farm manager<br/>[farm.py]"]
  node_account_pool["Account pools<br/>[farm.py]"]
  node_port_lifecycle["Port lifecycle<br/>[farm.py]"]
  node_watchdog["Retry and watchdog<br/>[farm.py]"]
  node_rotation["IP rotation<br/>[farm.py]"]
  node_state[("Farm state<br/>[farm.py]")]
  node_proxy_test["Proxy diagnostics<br/>[farm.py]"]
end

subgraph group_runtime["Tunnel and proxy runtime"]
  node_node_container["Tunnel node<br/>[entrypoint.sh]"]
  node_wireguard["WireGuard driver<br/>[wireguard.sh]"]
  node_ikev2_eap["IKEv2 EAP driver<br/>[ikev2-eap.sh]"]
  node_ikev2_cert["IKEv2 certificate driver<br/>[ikev2-cert.sh]"]
  node_openvpn["OpenVPN driver<br/>[openvpn.sh]"]
  node_proxy_service["SOCKS5 and HTTP<br/>[entrypoint.sh]"]
end

subgraph group_access["User access"]
  node_web_ui["Web UI<br/>[ui.html]"]
  node_cli["CLI<br/>[farm.py]"]
end

node_user(("Local user"))
node_config_files["VPN config files"]
node_vpn_services["VPN providers"]
node_licensing["Avast licensing"]
node_proxy_client(("Proxy clients"))

node_user -->|"manages farm"| node_web_ui
node_user -->|"runs commands"| node_cli
node_config_files -->|"imports configs"| node_farm_manager
node_user -->|"syncs certificate"| node_hma_import
node_user -->|"submits code"| node_activation
node_activation -->|"validates license"| node_licensing
node_user -->|"adds account"| node_provider_registry
node_provider_registry -.->|"fetches server list"| node_vpn_services
node_provider_registry -->|"resolves locations"| node_server_catalog
node_farm_manager -->|"resolves targets"| node_provider_registry
node_farm_manager -->|"binds accounts"| node_account_pool
node_farm_manager -->|"starts and stops"| node_port_lifecycle
node_farm_manager -->|"reads and writes"| node_state
node_farm_manager -->|"runs containers"| node_node_container
node_watchdog -->|"retries ports"| node_farm_manager
node_rotation -->|"restarts ports"| node_farm_manager
node_node_container -.->|"selects driver"| node_wireguard
node_node_container -.->|"selects driver"| node_ikev2_eap
node_node_container -.->|"selects driver"| node_ikev2_cert
node_node_container -.->|"selects driver"| node_openvpn
node_node_container -.->|"runs proxy"| node_proxy_service
node_proxy_client -->|"uses local proxy"| node_proxy_service
node_user -->|"tests proxy"| node_proxy_test
node_proxy_test -->|"executes probe"| node_node_container
node_web_ui -.->|"manages ports"| node_farm_manager
node_cli -->|"runs operations"| node_farm_manager

click node_hma_import "https://github.com/omzsk/proxy-farm/blob/main/manager/farm.py"
click node_activation "https://github.com/omzsk/proxy-farm/blob/main/manager/hma_activation.py"
click node_provider_registry "https://github.com/omzsk/proxy-farm/blob/main/manager/vendors.py"
click node_server_catalog "https://github.com/omzsk/proxy-farm/blob/main/manager/vendors.py"
click node_farm_manager "https://github.com/omzsk/proxy-farm/blob/main/manager/farm.py"
click node_account_pool "https://github.com/omzsk/proxy-farm/blob/main/manager/farm.py"
click node_port_lifecycle "https://github.com/omzsk/proxy-farm/blob/main/manager/farm.py"
click node_watchdog "https://github.com/omzsk/proxy-farm/blob/main/manager/farm.py"
click node_rotation "https://github.com/omzsk/proxy-farm/blob/main/manager/farm.py"
click node_state "https://github.com/omzsk/proxy-farm/blob/main/manager/farm.py"
click node_node_container "https://github.com/omzsk/proxy-farm/blob/main/node/entrypoint.sh"
click node_wireguard "https://github.com/omzsk/proxy-farm/blob/main/node/drivers/wireguard.sh"
click node_ikev2_eap "https://github.com/omzsk/proxy-farm/blob/main/node/drivers/ikev2-eap.sh"
click node_ikev2_cert "https://github.com/omzsk/proxy-farm/blob/main/node/drivers/ikev2-cert.sh"
click node_openvpn "https://github.com/omzsk/proxy-farm/blob/main/node/drivers/openvpn.sh"
click node_proxy_service "https://github.com/omzsk/proxy-farm/blob/main/node/entrypoint.sh"
click node_web_ui "https://github.com/omzsk/proxy-farm/blob/main/manager/ui.html"
click node_cli "https://github.com/omzsk/proxy-farm/blob/main/manager/farm.py"
click node_proxy_test "https://github.com/omzsk/proxy-farm/blob/main/manager/farm.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_hma_import,node_activation,node_provider_registry,node_server_catalog,node_user,node_proxy_client toneBlue
class node_farm_manager,node_account_pool,node_port_lifecycle,node_watchdog,node_rotation,node_state,node_proxy_test toneAmber
class node_node_container,node_wireguard,node_ikev2_eap,node_ikev2_cert,node_openvpn,node_proxy_service toneMint
class node_web_ui,node_cli toneRose
class node_config_files,node_vpn_services,node_licensing toneIndigo
```

## Components

### Provider onboarding

- [HMA certificate import](https://github.com/omzsk/proxy-farm/blob/main/manager/farm.py): `manager/farm.py`
- [HMA activation check](https://github.com/omzsk/proxy-farm/blob/main/manager/hma_activation.py): `manager/hma_activation.py`
- [Provider registry](https://github.com/omzsk/proxy-farm/blob/main/manager/vendors.py): `manager/vendors.py`
- [Server locations](https://github.com/omzsk/proxy-farm/blob/main/manager/vendors.py): `manager/vendors.py`

### Farm management

- [Farm manager](https://github.com/omzsk/proxy-farm/blob/main/manager/farm.py): `manager/farm.py`
- [Account pools](https://github.com/omzsk/proxy-farm/blob/main/manager/farm.py): `manager/farm.py`
- [Port lifecycle](https://github.com/omzsk/proxy-farm/blob/main/manager/farm.py): `manager/farm.py`
- [Retry and watchdog](https://github.com/omzsk/proxy-farm/blob/main/manager/farm.py): `manager/farm.py`
- [IP rotation](https://github.com/omzsk/proxy-farm/blob/main/manager/farm.py): `manager/farm.py`
- [Farm state](https://github.com/omzsk/proxy-farm/blob/main/manager/farm.py): `manager/farm.py`
- [Proxy diagnostics](https://github.com/omzsk/proxy-farm/blob/main/manager/farm.py): `manager/farm.py`

### Tunnel and proxy runtime

- [Tunnel node](https://github.com/omzsk/proxy-farm/blob/main/node/entrypoint.sh): `node/entrypoint.sh`
- [WireGuard driver](https://github.com/omzsk/proxy-farm/blob/main/node/drivers/wireguard.sh): `node/drivers/wireguard.sh`
- [IKEv2 EAP driver](https://github.com/omzsk/proxy-farm/blob/main/node/drivers/ikev2-eap.sh): `node/drivers/ikev2-eap.sh`
- [IKEv2 certificate driver](https://github.com/omzsk/proxy-farm/blob/main/node/drivers/ikev2-cert.sh): `node/drivers/ikev2-cert.sh`
- [OpenVPN driver](https://github.com/omzsk/proxy-farm/blob/main/node/drivers/openvpn.sh): `node/drivers/openvpn.sh`
- [SOCKS5 and HTTP](https://github.com/omzsk/proxy-farm/blob/main/node/entrypoint.sh): `node/entrypoint.sh`

### User access

- [Web UI](https://github.com/omzsk/proxy-farm/blob/main/manager/ui.html): `manager/ui.html`
- [CLI](https://github.com/omzsk/proxy-farm/blob/main/manager/farm.py): `manager/farm.py`

### Other components

- **Local user**
- **VPN config files**
- **VPN providers**
- **Avast licensing**
- **Proxy clients**

## Connections

- Local user → Web UI: manages farm (evidence: `README.md`)
- Local user → CLI: runs commands (evidence: `manager/farm.py`)
- VPN config files → Farm manager: imports configs (evidence: `README.md`)
- Local user → HMA certificate import: syncs certificate (evidence: `README.md`)
- Local user → HMA activation check: submits code (evidence: `README.md`)
- HMA activation check → Avast licensing: validates license (evidence: `manager/hma_activation.py`)
- Local user → Provider registry: adds account (evidence: `README.md`)
- Provider registry → VPN providers: fetches server list
- Provider registry → Server locations: resolves locations (evidence: `manager/vendors.py`)
- Farm manager → Provider registry: resolves targets (evidence: `manager/farm.py`)
- Farm manager → Account pools: binds accounts (evidence: `manager/farm.py`)
- Farm manager → Port lifecycle: starts and stops (evidence: `manager/farm.py`)
- Farm manager → Farm state: reads and writes (evidence: `manager/farm.py`)
- Farm manager → Tunnel node: runs containers (evidence: `manager/farm.py`)
- Retry and watchdog → Farm manager: retries ports (evidence: `manager/farm.py`)
- IP rotation → Farm manager: restarts ports (evidence: `manager/farm.py`)
- Tunnel node → WireGuard driver: selects driver
- Tunnel node → IKEv2 EAP driver: selects driver
- Tunnel node → IKEv2 certificate driver: selects driver
- Tunnel node → OpenVPN driver: selects driver
- Tunnel node → SOCKS5 and HTTP: runs proxy
- Proxy clients → SOCKS5 and HTTP: uses local proxy (evidence: `README.md`)
- Local user → Proxy diagnostics: tests proxy (evidence: `README.md`)
- Proxy diagnostics → Tunnel node: executes probe (evidence: `manager/farm.py`)
- Web UI → Farm manager: manages ports
- CLI → Farm manager: runs operations (evidence: `manager/farm.py`)
