# yusing/godoxy architecture

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

- Interactive diagram: https://gitdiagram.com/yusing/godoxy
- Repository: https://github.com/yusing/godoxy

## Overview

GoDoxy is a reverse proxy with a WebUI for configuring and operating HTTP and TCP/UDP routes. The main lifecycle loads configuration, discovers route inputs, activates routes and listeners, then serves and manages traffic; changes are watched and applied at runtime. Documented branches include authentication, certificates, access control, Docker and Proxmox management, idle sleep, health, metrics, and homepage integrations. Several subsystem implementations were not sampled, so those capabilities and links are based on README documentation rather than inspected call paths.

Main entry points: [`internal/api/handler.go`](https://github.com/yusing/godoxy/blob/main/internal/api/handler.go) (WebUI API), [`internal/route/provider`](https://github.com/yusing/godoxy/tree/main/internal/route/provider) (Route Providers), [`internal/entrypoint`](https://github.com/yusing/godoxy/tree/main/internal/entrypoint) (Listeners and Routes), [`internal/config/runtime_manager.go`](https://github.com/yusing/godoxy/blob/main/internal/config/runtime_manager.go) (Runtime Manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime and Configuration"]
  node_main["Server Startup<br/>[main.go]"]
  node_config["Runtime Manager<br/>[runtime_manager.go]"]
  node_watchers["Change Watchers"]
end

subgraph group_traffic["Routing and Traffic"]
  node_providers["Route Providers"]
  node_eventhandler["Route Updates<br/>[event_handler.go]"]
  node_routes["Route Construction"]
  node_entrypoint["Listeners and Routes"]
  node_proxy["HTTP and Stream Proxy"]
  node_middleware["HTTP Middleware"]
  node_loadbalancer["Load Balancing"]
end

subgraph group_management["Management API"]
  node_api["WebUI API<br/>[handler.go]"]
  node_auth["Authentication"]
  node_webui["WebUI Configuration<br/>[webui_prod.go]"]
end

subgraph group_integrations["Providers and Integrations"]
  node_docker["Docker Discovery"]
  node_agent["Remote Agent<br/>[main.go]"]
  node_proxmox["Proxmox Management"]
  node_certs["Certificate Providers"]
end

subgraph group_operations["Operations"]
  node_idle["Idle Sleep<br/>[watcher.go]"]
  node_health["Health Monitoring"]
  node_metrics["Metrics"]
  node_access["Access Rules and Logs"]
  node_homepage["Homepage Integrations"]
end

node_operator(("Operator"))

node_operator -.->|"manages"| node_api
node_main -->|"loads runtime"| node_config
node_main -->|"registers handlers"| node_api
node_config -->|"starts pollers"| node_metrics
node_config -.->|"activates providers"| node_providers
node_watchers -.->|"sends changes"| node_eventhandler
node_eventhandler -->|"reloads routes"| node_providers
node_eventhandler -->|"starts routes"| node_routes
node_routes -.->|"registers routes"| node_entrypoint
node_entrypoint -.->|"dispatches traffic"| node_proxy
node_proxy -.->|"applies middleware"| node_middleware
node_proxy -.->|"balances requests"| node_loadbalancer
node_api -->|"checks identity"| node_auth
node_api -.->|"serves configuration"| node_webui
node_providers -.->|"discovers containers"| node_docker
node_providers -.->|"discovers remote hosts"| node_agent
node_providers -.->|"binds resources"| node_proxmox
node_entrypoint -.->|"uses certificates"| node_certs
node_idle -.->|"wakes containers"| node_docker
node_idle -.->|"wakes containers"| node_proxmox
node_entrypoint -.->|"checks upstreams"| node_health
node_api -.->|"exposes metrics"| node_metrics
node_middleware -.->|"enforces access"| node_access
node_api -.->|"serves homepage data"| node_homepage

click node_main "https://github.com/yusing/godoxy/blob/main/cmd/main.go"
click node_config "https://github.com/yusing/godoxy/blob/main/internal/config/runtime_manager.go"
click node_watchers "https://github.com/yusing/godoxy/tree/main/internal/watcher"
click node_providers "https://github.com/yusing/godoxy/tree/main/internal/route/provider"
click node_eventhandler "https://github.com/yusing/godoxy/blob/main/internal/route/provider/event_handler.go"
click node_routes "https://github.com/yusing/godoxy/tree/main/internal/route"
click node_entrypoint "https://github.com/yusing/godoxy/tree/main/internal/entrypoint"
click node_proxy "https://github.com/yusing/godoxy/tree/main/internal/routeimpl"
click node_middleware "https://github.com/yusing/godoxy/tree/main/internal/net/gphttp/middleware"
click node_loadbalancer "https://github.com/yusing/godoxy/tree/main/internal/net/gphttp/loadbalancer"
click node_api "https://github.com/yusing/godoxy/blob/main/internal/api/handler.go"
click node_auth "https://github.com/yusing/godoxy/tree/main/internal/auth"
click node_webui "https://github.com/yusing/godoxy/blob/main/internal/config/webui_prod.go"
click node_docker "https://github.com/yusing/godoxy/tree/main/internal/docker"
click node_agent "https://github.com/yusing/godoxy/blob/main/agent/cmd/main.go"
click node_proxmox "https://github.com/yusing/godoxy/tree/main/internal/proxmox"
click node_certs "https://github.com/yusing/godoxy/tree/main/internal/autocert"
click node_idle "https://github.com/yusing/godoxy/blob/main/internal/idlewatcher/watcher.go"
click node_health "https://github.com/yusing/godoxy/tree/main/internal/health"
click node_metrics "https://github.com/yusing/godoxy/tree/main/internal/metrics"
click node_access "https://github.com/yusing/godoxy/tree/main/internal/acl"
click node_homepage "https://github.com/yusing/godoxy/tree/main/internal/homepage"

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_main,node_config,node_watchers toneBlue
class node_providers,node_eventhandler,node_routes,node_entrypoint,node_proxy,node_middleware,node_loadbalancer toneAmber
class node_api,node_auth,node_webui toneMint
class node_docker,node_agent,node_proxmox,node_certs toneRose
class node_idle,node_health,node_metrics,node_access,node_homepage,node_operator toneIndigo
```

## Components

### Runtime and Configuration

- [Server Startup](https://github.com/yusing/godoxy/blob/main/cmd/main.go): `cmd/main.go`
- [Runtime Manager](https://github.com/yusing/godoxy/blob/main/internal/config/runtime_manager.go): `internal/config/runtime_manager.go`
- [Change Watchers](https://github.com/yusing/godoxy/tree/main/internal/watcher): `internal/watcher`

### Routing and Traffic

- [Route Providers](https://github.com/yusing/godoxy/tree/main/internal/route/provider): `internal/route/provider`
- [Route Updates](https://github.com/yusing/godoxy/blob/main/internal/route/provider/event_handler.go): `internal/route/provider/event_handler.go`
- [Route Construction](https://github.com/yusing/godoxy/tree/main/internal/route): `internal/route`
- [Listeners and Routes](https://github.com/yusing/godoxy/tree/main/internal/entrypoint): `internal/entrypoint`
- [HTTP and Stream Proxy](https://github.com/yusing/godoxy/tree/main/internal/routeimpl): `internal/routeimpl`
- [HTTP Middleware](https://github.com/yusing/godoxy/tree/main/internal/net/gphttp/middleware): `internal/net/gphttp/middleware`
- [Load Balancing](https://github.com/yusing/godoxy/tree/main/internal/net/gphttp/loadbalancer): `internal/net/gphttp/loadbalancer`

### Management API

- [WebUI API](https://github.com/yusing/godoxy/blob/main/internal/api/handler.go): `internal/api/handler.go`
- [Authentication](https://github.com/yusing/godoxy/tree/main/internal/auth): `internal/auth`
- [WebUI Configuration](https://github.com/yusing/godoxy/blob/main/internal/config/webui_prod.go): `internal/config/webui_prod.go`

### Providers and Integrations

- [Docker Discovery](https://github.com/yusing/godoxy/tree/main/internal/docker): `internal/docker`
- [Remote Agent](https://github.com/yusing/godoxy/blob/main/agent/cmd/main.go): `agent/cmd/main.go`
- [Proxmox Management](https://github.com/yusing/godoxy/tree/main/internal/proxmox): `internal/proxmox`
- [Certificate Providers](https://github.com/yusing/godoxy/tree/main/internal/autocert): `internal/autocert`

### Operations

- [Idle Sleep](https://github.com/yusing/godoxy/blob/main/internal/idlewatcher/watcher.go): `internal/idlewatcher/watcher.go`
- [Health Monitoring](https://github.com/yusing/godoxy/tree/main/internal/health): `internal/health`
- [Metrics](https://github.com/yusing/godoxy/tree/main/internal/metrics): `internal/metrics`
- [Access Rules and Logs](https://github.com/yusing/godoxy/tree/main/internal/acl): `internal/acl`
- [Homepage Integrations](https://github.com/yusing/godoxy/tree/main/internal/homepage): `internal/homepage`

### Other components

- **Operator**

## Connections

- Operator → WebUI API: manages
- Server Startup → Runtime Manager: loads runtime (evidence: `cmd/main.go`)
- Server Startup → WebUI API: registers handlers (evidence: `cmd/main.go`)
- Runtime Manager → Metrics: starts pollers (evidence: `internal/config/runtime_manager.go`)
- Runtime Manager → Route Providers: activates providers
- Change Watchers → Route Updates: sends changes (evidence: `internal/route/provider/event_handler.go`)
- Route Updates → Route Providers: reloads routes (evidence: `internal/route/provider/event_handler.go`)
- Route Updates → Route Construction: starts routes (evidence: `internal/route/provider/event_handler.go`)
- Route Construction → Listeners and Routes: registers routes
- Listeners and Routes → HTTP and Stream Proxy: dispatches traffic
- HTTP and Stream Proxy → HTTP Middleware: applies middleware
- HTTP and Stream Proxy → Load Balancing: balances requests
- WebUI API → Authentication: checks identity (evidence: `internal/api/handler.go`)
- WebUI API → WebUI Configuration: serves configuration
- Route Providers → Docker Discovery: discovers containers
- Route Providers → Remote Agent: discovers remote hosts
- Route Providers → Proxmox Management: binds resources (evidence: `internal/route/provider/event_handler.go`)
- Listeners and Routes → Certificate Providers: uses certificates
- Idle Sleep → Docker Discovery: wakes containers (evidence: `internal/idlewatcher/watcher.go`)
- Idle Sleep → Proxmox Management: wakes containers
- Listeners and Routes → Health Monitoring: checks upstreams (evidence: `internal/entrypoint/query.go`)
- WebUI API → Metrics: exposes metrics
- HTTP Middleware → Access Rules and Logs: enforces access
- WebUI API → Homepage Integrations: serves homepage data
