# lowkruc/warp-proxy-manager architecture

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

- Interactive diagram: https://gitdiagram.com/lowkruc/warp-proxy-manager
- Repository: https://github.com/lowkruc/warp-proxy-manager

## Overview

Warp Proxy Manager operates a SOCKS5 forward proxy over managed Cloudflare WARP containers. A client request enters the proxy, which selects a backend and forwards traffic; separately, the manager monitors backends and scales the container pool. Operators use the CLI or REST API to manage containers, scaling, configuration, and monitoring. The graph includes the documented load-balancing, health, rolling-update, and metrics capabilities. Some runtime wiring is only partially excerpted, so unverified links are dashed rather than inferred as direct calls.

Main entry points: [`cmd/manager/main.go`](https://github.com/lowkruc/warp-proxy-manager/blob/master/cmd/manager/main.go) (Manager Runtime), [`internal/api/handlers.go`](https://github.com/lowkruc/warp-proxy-manager/blob/master/internal/api/handlers.go) (REST API), [`internal/proxy/proxy.go`](https://github.com/lowkruc/warp-proxy-manager/blob/master/internal/proxy/proxy.go) (SOCKS5 Proxy), [`internal/store/metrics.go`](https://github.com/lowkruc/warp-proxy-manager/blob/master/internal/store/metrics.go) (Metrics Collector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Operator and API"]
  node_cli["warpctl CLI<br/>[main.go]"]
  node_api["REST API<br/>[handlers.go]"]
  node_manager["Manager Runtime<br/>[main.go]"]
  node_config["Configuration<br/>[config.go]"]
end

subgraph group_traffic["Proxy Traffic"]
  node_socks["SOCKS5 Proxy<br/>[proxy.go]"]
  node_balancer["Load Balancer<br/>[balancer.go]"]
  node_tracker["Connection Tracking<br/>[tracker.go]"]
  node_health["Health Checker<br/>[health.go]"]
end

subgraph group_operations["Pool Operations"]
  node_docker["Docker Client<br/>[client.go]"]
  node_scaler["Auto Scaler<br/>[scaler.go]"]
  node_rolling["Rolling Updater<br/>[rolling.go]"]
  node_alerts["Scaling Alerts<br/>[alerts.go]"]
end

subgraph group_observability["Metrics and State"]
  node_collector["Metrics Collector<br/>[metrics.go]"]
  node_store[("Metrics and History<br/>[store.go]")]
end

node_client(("Proxy Client"))
node_operator(("Operator"))
node_containers["WARP Containers"]
node_prometheus(("Monitoring System"))

node_operator -->|"runs commands"| node_cli
node_cli -.->|"manages via API"| node_api
node_operator -->|"calls endpoints"| node_api
node_manager -->|"loads settings"| node_config
node_manager -->|"initializes"| node_docker
node_manager -->|"starts"| node_socks
node_manager -->|"syncs backends"| node_balancer
node_manager -->|"starts"| node_scaler
node_manager -->|"registers routes"| node_api
node_manager -->|"initializes"| node_store
node_manager -->|"starts"| node_collector
node_client -->|"sends SOCKS5"| node_socks
node_socks -->|"selects backend"| node_balancer
node_socks -->|"forwards traffic"| node_containers
node_balancer -->|"balances across"| node_containers
node_manager -.->|"starts checker"| node_health
node_health -->|"checks health"| node_containers
node_socks -->|"tracks connections"| node_tracker
node_api -->|"manages containers"| node_docker
node_api -->|"requests scaling"| node_scaler
node_scaler -->|"scales pool"| node_docker
node_scaler -->|"reads backend load"| node_balancer
node_rolling -->|"replaces containers"| node_docker
node_collector -->|"reads healthy backends"| node_balancer
node_collector -->|"saves metrics"| node_store
node_api -->|"serves metrics"| node_collector
node_api -->|"reads history"| node_store
node_prometheus -->|"scrapes metrics"| node_api
node_socks -.->|"reports responses"| node_collector

click node_cli "https://github.com/lowkruc/warp-proxy-manager/blob/master/cmd/cli/main.go"
click node_api "https://github.com/lowkruc/warp-proxy-manager/blob/master/internal/api/handlers.go"
click node_manager "https://github.com/lowkruc/warp-proxy-manager/blob/master/cmd/manager/main.go"
click node_config "https://github.com/lowkruc/warp-proxy-manager/blob/master/internal/config/config.go"
click node_socks "https://github.com/lowkruc/warp-proxy-manager/blob/master/internal/proxy/proxy.go"
click node_balancer "https://github.com/lowkruc/warp-proxy-manager/blob/master/internal/proxy/balancer.go"
click node_tracker "https://github.com/lowkruc/warp-proxy-manager/blob/master/internal/proxy/tracker.go"
click node_health "https://github.com/lowkruc/warp-proxy-manager/blob/master/internal/proxy/health.go"
click node_docker "https://github.com/lowkruc/warp-proxy-manager/blob/master/internal/docker/client.go"
click node_scaler "https://github.com/lowkruc/warp-proxy-manager/blob/master/internal/scaler/scaler.go"
click node_rolling "https://github.com/lowkruc/warp-proxy-manager/blob/master/internal/scaler/rolling.go"
click node_alerts "https://github.com/lowkruc/warp-proxy-manager/blob/master/internal/scaler/alerts.go"
click node_collector "https://github.com/lowkruc/warp-proxy-manager/blob/master/internal/store/metrics.go"
click node_store "https://github.com/lowkruc/warp-proxy-manager/blob/master/internal/store/store.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_cli,node_api,node_manager,node_config,node_client toneBlue
class node_socks,node_balancer,node_tracker,node_health toneAmber
class node_docker,node_scaler,node_rolling,node_alerts toneMint
class node_collector,node_store toneRose
class node_operator,node_containers,node_prometheus toneIndigo
```

## Components

### Operator and API

- [warpctl CLI](https://github.com/lowkruc/warp-proxy-manager/blob/master/cmd/cli/main.go): `cmd/cli/main.go`
- [REST API](https://github.com/lowkruc/warp-proxy-manager/blob/master/internal/api/handlers.go): `internal/api/handlers.go`
- [Manager Runtime](https://github.com/lowkruc/warp-proxy-manager/blob/master/cmd/manager/main.go): `cmd/manager/main.go`
- [Configuration](https://github.com/lowkruc/warp-proxy-manager/blob/master/internal/config/config.go): `internal/config/config.go`

### Proxy Traffic

- [SOCKS5 Proxy](https://github.com/lowkruc/warp-proxy-manager/blob/master/internal/proxy/proxy.go): `internal/proxy/proxy.go`
- [Load Balancer](https://github.com/lowkruc/warp-proxy-manager/blob/master/internal/proxy/balancer.go): `internal/proxy/balancer.go`
- [Connection Tracking](https://github.com/lowkruc/warp-proxy-manager/blob/master/internal/proxy/tracker.go): `internal/proxy/tracker.go`
- [Health Checker](https://github.com/lowkruc/warp-proxy-manager/blob/master/internal/proxy/health.go): `internal/proxy/health.go`

### Pool Operations

- [Docker Client](https://github.com/lowkruc/warp-proxy-manager/blob/master/internal/docker/client.go): `internal/docker/client.go`
- [Auto Scaler](https://github.com/lowkruc/warp-proxy-manager/blob/master/internal/scaler/scaler.go): `internal/scaler/scaler.go`
- [Rolling Updater](https://github.com/lowkruc/warp-proxy-manager/blob/master/internal/scaler/rolling.go): `internal/scaler/rolling.go`
- [Scaling Alerts](https://github.com/lowkruc/warp-proxy-manager/blob/master/internal/scaler/alerts.go): `internal/scaler/alerts.go`

### Metrics and State

- [Metrics Collector](https://github.com/lowkruc/warp-proxy-manager/blob/master/internal/store/metrics.go): `internal/store/metrics.go`
- [Metrics and History](https://github.com/lowkruc/warp-proxy-manager/blob/master/internal/store/store.go): `internal/store/store.go`

### Other components

- **Proxy Client**
- **Operator**
- **WARP Containers**
- **Monitoring System**

## Connections

- Operator → warpctl CLI: runs commands (evidence: `README.md`)
- warpctl CLI → REST API: manages via API
- Operator → REST API: calls endpoints (evidence: `README.md`)
- Manager Runtime → Configuration: loads settings (evidence: `cmd/manager/main.go`)
- Manager Runtime → Docker Client: initializes (evidence: `cmd/manager/main.go`)
- Manager Runtime → SOCKS5 Proxy: starts (evidence: `cmd/manager/main.go`)
- Manager Runtime → Load Balancer: syncs backends (evidence: `cmd/manager/main.go`)
- Manager Runtime → Auto Scaler: starts (evidence: `cmd/manager/main.go`)
- Manager Runtime → REST API: registers routes (evidence: `cmd/manager/main.go`)
- Manager Runtime → Metrics and History: initializes (evidence: `cmd/manager/main.go`)
- Manager Runtime → Metrics Collector: starts (evidence: `cmd/manager/main.go`)
- Proxy Client → SOCKS5 Proxy: sends SOCKS5 (evidence: `README.md`)
- SOCKS5 Proxy → Load Balancer: selects backend (evidence: `README.md`)
- SOCKS5 Proxy → WARP Containers: forwards traffic (evidence: `README.md`)
- Load Balancer → WARP Containers: balances across (evidence: `README.md`)
- Manager Runtime → Health Checker: starts checker
- Health Checker → WARP Containers: checks health (evidence: `README.md`)
- SOCKS5 Proxy → Connection Tracking: tracks connections (evidence: `internal/proxy/proxy.go`)
- REST API → Docker Client: manages containers (evidence: `internal/api/handlers.go`)
- REST API → Auto Scaler: requests scaling (evidence: `internal/api/handlers.go`)
- Auto Scaler → Docker Client: scales pool (evidence: `internal/scaler/scaler.go`)
- Auto Scaler → Load Balancer: reads backend load (evidence: `internal/scaler/scaler.go`)
- Rolling Updater → Docker Client: replaces containers (evidence: `internal/scaler/rolling.go`)
- Metrics Collector → Load Balancer: reads healthy backends (evidence: `internal/store/metrics.go`)
- Metrics Collector → Metrics and History: saves metrics (evidence: `internal/store/metrics.go`)
- REST API → Metrics Collector: serves metrics (evidence: `internal/api/handlers.go`)
- REST API → Metrics and History: reads history (evidence: `internal/api/handlers.go`)
- Monitoring System → REST API: scrapes metrics (evidence: `README.md`)
- SOCKS5 Proxy → Metrics Collector: reports responses
