# vignol-yw/loadbalancer architecture

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

- Interactive diagram: https://gitdiagram.com/vignol-yw/loadbalancer
- Repository: https://github.com/vignol-yw/loadbalancer

## Overview

This Go TCP load balancer reads listener, backend, and strategy settings, accepts client connections, selects a backend, and proxies traffic bidirectionally. Routing supports round-robin and least-connections; the latter reads each backend server’s atomic active-connection count, which is updated during proxy handling. The README also describes high-concurrency operation and a Node.js workload demo; the sampled app implements health-check and delayed-work endpoints, but its deployment wiring is not shown.

Main entry points: [`cmd/loadbalancer/main.go`](https://github.com/vignol-yw/loadbalancer/blob/main/cmd/loadbalancer/main.go) (Load balancer process), [`internal/loadbalancer/server.go`](https://github.com/vignol-yw/loadbalancer/blob/main/internal/loadbalancer/server.go) (Backend server state), [`internal/algorithms/least-connections.go`](https://github.com/vignol-yw/loadbalancer/blob/main/internal/algorithms/least-connections.go) (Least connections), [`internal/algorithms/balancing_strategy.go`](https://github.com/vignol-yw/loadbalancer/blob/main/internal/algorithms/balancing_strategy.go) (Strategy interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Configuration & startup"]
  node_entry["Load balancer process<br/>[main.go]"]
  node_config_loader["Config loader<br/>[config.go]"]
  node_config_file["Load balancer config<br/>[loadbalancer.yaml]"]
  node_injector["Strategy injector<br/>[injection.go]"]
end

subgraph group_routing["Backend routing"]
  node_strategy["Strategy interface"]
  node_round_robin["Round robin<br/>[round-robin.go]"]
  node_least_connections["Least connections"]
  node_backend_server["Backend server state<br/>[server.go]"]
end

subgraph group_proxy["TCP proxy"]
  node_client_wrapper["Client connection<br/>[client.go]"]
  node_handler["Connection handler<br/>[server.go]"]
end

node_operator(("Operator"))
node_client(("TCP clients"))
node_backends["Backend instances"]

node_operator -->|"starts"| node_entry
node_entry -->|"loads settings"| node_config_loader
node_config_loader -->|"reads"| node_config_file
node_entry -->|"selects strategy"| node_injector
node_injector -->|"creates"| node_round_robin
node_injector -->|"creates"| node_least_connections
node_round_robin -->|"implements"| node_strategy
node_least_connections -->|"implements"| node_strategy
node_entry -->|"creates servers"| node_backend_server
node_entry -->|"registers servers"| node_strategy
node_entry -->|"accepts connections"| node_client
node_entry -->|"selects backend"| node_strategy
node_round_robin -->|"returns selection"| node_backend_server
node_least_connections -->|"reads counts"| node_backend_server
node_least_connections -->|"returns selection"| node_backend_server
node_entry -->|"wraps connection"| node_client_wrapper
node_entry -->|"dispatches connection"| node_handler
node_handler -->|"dials address"| node_backend_server
node_handler -->|"proxies TCP traffic"| node_backends
node_handler -->|"proxies TCP traffic"| node_client

click node_entry "https://github.com/vignol-yw/loadbalancer/blob/main/cmd/loadbalancer/main.go"
click node_config_loader "https://github.com/vignol-yw/loadbalancer/blob/main/cmd/config/config.go"
click node_config_file "https://github.com/vignol-yw/loadbalancer/blob/main/loadbalancer.yaml"
click node_injector "https://github.com/vignol-yw/loadbalancer/blob/main/cmd/dependencies/injection.go"
click node_strategy "https://github.com/vignol-yw/loadbalancer/blob/main/internal/algorithms/balancing_strategy.go"
click node_round_robin "https://github.com/vignol-yw/loadbalancer/blob/main/internal/algorithms/round-robin.go"
click node_least_connections "https://github.com/vignol-yw/loadbalancer/blob/main/internal/algorithms/least-connections.go"
click node_backend_server "https://github.com/vignol-yw/loadbalancer/blob/main/internal/loadbalancer/server.go"
click node_client_wrapper "https://github.com/vignol-yw/loadbalancer/blob/main/internal/loadbalancer/client.go"
click node_handler "https://github.com/vignol-yw/loadbalancer/blob/main/internal/loadbalancer/server.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_entry,node_config_loader,node_config_file,node_injector,node_client toneBlue
class node_strategy,node_round_robin,node_least_connections,node_backend_server toneAmber
class node_client_wrapper,node_handler toneMint
class node_operator,node_backends toneIndigo
```

## Components

### Configuration & startup

- [Load balancer process](https://github.com/vignol-yw/loadbalancer/blob/main/cmd/loadbalancer/main.go): `cmd/loadbalancer/main.go`
- [Config loader](https://github.com/vignol-yw/loadbalancer/blob/main/cmd/config/config.go): `cmd/config/config.go`
- [Load balancer config](https://github.com/vignol-yw/loadbalancer/blob/main/loadbalancer.yaml): `loadbalancer.yaml`
- [Strategy injector](https://github.com/vignol-yw/loadbalancer/blob/main/cmd/dependencies/injection.go): `cmd/dependencies/injection.go`

### Backend routing

- [Strategy interface](https://github.com/vignol-yw/loadbalancer/blob/main/internal/algorithms/balancing_strategy.go): `internal/algorithms/balancing_strategy.go`
- [Round robin](https://github.com/vignol-yw/loadbalancer/blob/main/internal/algorithms/round-robin.go): `internal/algorithms/round-robin.go`
- [Least connections](https://github.com/vignol-yw/loadbalancer/blob/main/internal/algorithms/least-connections.go): `internal/algorithms/least-connections.go`
- [Backend server state](https://github.com/vignol-yw/loadbalancer/blob/main/internal/loadbalancer/server.go): `internal/loadbalancer/server.go`

### TCP proxy

- [Client connection](https://github.com/vignol-yw/loadbalancer/blob/main/internal/loadbalancer/client.go): `internal/loadbalancer/client.go`
- [Connection handler](https://github.com/vignol-yw/loadbalancer/blob/main/internal/loadbalancer/server.go): `internal/loadbalancer/server.go`

### Other components

- **Operator**
- **TCP clients**
- **Backend instances**

## Connections

- Operator → Load balancer process: starts
- Load balancer process → Config loader: loads settings
- Config loader → Load balancer config: reads
- Load balancer process → Strategy injector: selects strategy
- Strategy injector → Round robin: creates
- Strategy injector → Least connections: creates
- Round robin → Strategy interface: implements
- Least connections → Strategy interface: implements
- Load balancer process → Backend server state: creates servers
- Load balancer process → Strategy interface: registers servers
- Load balancer process → TCP clients: accepts connections
- Load balancer process → Strategy interface: selects backend
- Round robin → Backend server state: returns selection
- Least connections → Backend server state: reads counts
- Least connections → Backend server state: returns selection
- Load balancer process → Client connection: wraps connection
- Load balancer process → Connection handler: dispatches connection
- Connection handler → Backend server state: dials address
- Connection handler → Backend instances: proxies TCP traffic
- Connection handler → TCP clients: proxies TCP traffic