# lekhanj/load-balancer architecture

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

- Interactive diagram: https://gitdiagram.com/lekhanj/load-balancer
- Repository: https://github.com/lekhanj/load-balancer

## Overview

This is a learning-oriented HTTP load balancer: it accepts client requests, selects a healthy backend using a configured strategy, and reverse-proxies the request. Startup loads configuration, initializes backend state, and starts periodic health checks; request handling resolves a client key, chooses a server, tracks active connections, and reuses a proxy. The README also documents four interchangeable routing strategies and a Python HTTP backend. The graph follows the sampled Go entry point and runtime modules; the backend’s role is documented and its implementation is present in the tree.

Main entry points: [`cmd/load-balancer/main.go`](https://github.com/lekhanj/load-balancer/blob/main/cmd/load-balancer/main.go) (Load Balancer Entry), [`internal/balancer/server.go`](https://github.com/lekhanj/load-balancer/blob/main/internal/balancer/server.go) (Backend Server State), [`internal/balancer/balancer.go`](https://github.com/lekhanj/load-balancer/blob/main/internal/balancer/balancer.go) (Strategy Dispatcher), [`internal/balancer/proxy_pool.go`](https://github.com/lekhanj/load-balancer/blob/main/internal/balancer/proxy_pool.go) (Proxy Pool)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Startup and Config"]
  node_main["Load Balancer Entry<br/>[main.go]"]
  node_configfile["Runtime Config<br/>[config.json]"]
  node_config["Config Model<br/>[config.go]"]
end

subgraph group_routing["Routing and State"]
  node_lb["Strategy Dispatcher<br/>[balancer.go]"]
  node_roundrobin["Round Robin<br/>[round_robin.go]"]
  node_weighted["Weighted Round Robin"]
  node_least["Least Connections"]
  node_iphash["IP Hash<br/>[ip_hash.go]"]
  node_serverstate["Backend Server State<br/>[server.go]"]
  node_health["Health Checker<br/>[health_check.go]"]
  node_pool["Proxy Pool<br/>[proxy_pool.go]"]
  node_proxy["Reverse Proxy<br/>[proxy_pool.go]"]
end

subgraph group_backends["Backend Services"]
  node_pybackend["Python HTTP Backend<br/>[server.py]"]
end

node_client(("HTTP Client"))

node_client -->|"sends request"| node_main
node_main -->|"reads"| node_configfile
node_main -->|"decodes config"| node_config
node_main -.->|"selects strategy"| node_roundrobin
node_main -.->|"selects strategy"| node_weighted
node_main -.->|"selects strategy"| node_least
node_main -.->|"selects strategy"| node_iphash
node_main -->|"initializes"| node_lb
node_main -->|"creates servers"| node_serverstate
node_main -->|"starts checks"| node_health
node_main -->|"creates pool"| node_pool
node_main -->|"requests selection"| node_lb
node_lb -.->|"dispatches Next"| node_roundrobin
node_lb -.->|"dispatches Next"| node_weighted
node_lb -.->|"dispatches Next"| node_least
node_lb -.->|"dispatches Next"| node_iphash
node_roundrobin -->|"checks health"| node_serverstate
node_weighted -->|"checks health and weights"| node_serverstate
node_least -->|"reads health and counts"| node_serverstate
node_iphash -->|"checks health"| node_serverstate
node_health -->|"updates health"| node_serverstate
node_health -->|"sends HEAD"| node_pybackend
node_main -->|"tracks connections"| node_serverstate
node_main -->|"gets proxy"| node_pool
node_pool -->|"reads backend URL"| node_serverstate
node_pool -->|"creates and reuses"| node_proxy
node_main -->|"serves request"| node_proxy
node_proxy -->|"forwards HTTP"| node_pybackend

click node_main "https://github.com/lekhanj/load-balancer/blob/main/cmd/load-balancer/main.go"
click node_configfile "https://github.com/lekhanj/load-balancer/blob/main/cmd/load-balancer/config.json"
click node_config "https://github.com/lekhanj/load-balancer/blob/main/internal/balancer/config.go"
click node_lb "https://github.com/lekhanj/load-balancer/blob/main/internal/balancer/balancer.go"
click node_roundrobin "https://github.com/lekhanj/load-balancer/blob/main/internal/algorithms/round_robin.go"
click node_weighted "https://github.com/lekhanj/load-balancer/blob/main/internal/algorithms/weighted_round_robin.go"
click node_least "https://github.com/lekhanj/load-balancer/blob/main/internal/algorithms/least_connections.go"
click node_iphash "https://github.com/lekhanj/load-balancer/blob/main/internal/algorithms/ip_hash.go"
click node_serverstate "https://github.com/lekhanj/load-balancer/blob/main/internal/balancer/server.go"
click node_health "https://github.com/lekhanj/load-balancer/blob/main/internal/balancer/health_check.go"
click node_pool "https://github.com/lekhanj/load-balancer/blob/main/internal/balancer/proxy_pool.go"
click node_proxy "https://github.com/lekhanj/load-balancer/blob/main/internal/balancer/proxy_pool.go"
click node_pybackend "https://github.com/lekhanj/load-balancer/blob/main/server/server.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_main,node_configfile,node_config,node_client toneBlue
class node_lb,node_roundrobin,node_weighted,node_least,node_iphash,node_serverstate,node_health,node_pool,node_proxy toneAmber
class node_pybackend toneMint
```

## Components

### Startup and Config

- [Load Balancer Entry](https://github.com/lekhanj/load-balancer/blob/main/cmd/load-balancer/main.go): `cmd/load-balancer/main.go`
- [Runtime Config](https://github.com/lekhanj/load-balancer/blob/main/cmd/load-balancer/config.json): `cmd/load-balancer/config.json`
- [Config Model](https://github.com/lekhanj/load-balancer/blob/main/internal/balancer/config.go): `internal/balancer/config.go`

### Routing and State

- [Strategy Dispatcher](https://github.com/lekhanj/load-balancer/blob/main/internal/balancer/balancer.go): `internal/balancer/balancer.go`
- [Round Robin](https://github.com/lekhanj/load-balancer/blob/main/internal/algorithms/round_robin.go): `internal/algorithms/round_robin.go`
- [Weighted Round Robin](https://github.com/lekhanj/load-balancer/blob/main/internal/algorithms/weighted_round_robin.go): `internal/algorithms/weighted_round_robin.go`
- [Least Connections](https://github.com/lekhanj/load-balancer/blob/main/internal/algorithms/least_connections.go): `internal/algorithms/least_connections.go`
- [IP Hash](https://github.com/lekhanj/load-balancer/blob/main/internal/algorithms/ip_hash.go): `internal/algorithms/ip_hash.go`
- [Backend Server State](https://github.com/lekhanj/load-balancer/blob/main/internal/balancer/server.go): `internal/balancer/server.go`
- [Health Checker](https://github.com/lekhanj/load-balancer/blob/main/internal/balancer/health_check.go): `internal/balancer/health_check.go`
- [Proxy Pool](https://github.com/lekhanj/load-balancer/blob/main/internal/balancer/proxy_pool.go): `internal/balancer/proxy_pool.go`
- [Reverse Proxy](https://github.com/lekhanj/load-balancer/blob/main/internal/balancer/proxy_pool.go): `internal/balancer/proxy_pool.go`

### Backend Services

- [Python HTTP Backend](https://github.com/lekhanj/load-balancer/blob/main/server/server.py): `server/server.py`

### Other components

- **HTTP Client**

## Connections

- HTTP Client → Load Balancer Entry: sends request
- Load Balancer Entry → Runtime Config: reads
- Load Balancer Entry → Config Model: decodes config
- Load Balancer Entry → Round Robin: selects strategy
- Load Balancer Entry → Weighted Round Robin: selects strategy
- Load Balancer Entry → Least Connections: selects strategy
- Load Balancer Entry → IP Hash: selects strategy
- Load Balancer Entry → Strategy Dispatcher: initializes
- Load Balancer Entry → Backend Server State: creates servers
- Load Balancer Entry → Health Checker: starts checks
- Load Balancer Entry → Proxy Pool: creates pool
- Load Balancer Entry → Strategy Dispatcher: requests selection
- Strategy Dispatcher → Round Robin: dispatches Next
- Strategy Dispatcher → Weighted Round Robin: dispatches Next
- Strategy Dispatcher → Least Connections: dispatches Next
- Strategy Dispatcher → IP Hash: dispatches Next
- Round Robin → Backend Server State: checks health
- Weighted Round Robin → Backend Server State: checks health and weights
- Least Connections → Backend Server State: reads health and counts
- IP Hash → Backend Server State: checks health
- Health Checker → Backend Server State: updates health
- Health Checker → Python HTTP Backend: sends HEAD
- Load Balancer Entry → Backend Server State: tracks connections
- Load Balancer Entry → Proxy Pool: gets proxy
- Proxy Pool → Backend Server State: reads backend URL
- Proxy Pool → Reverse Proxy: creates and reuses
- Load Balancer Entry → Reverse Proxy: serves request
- Reverse Proxy → Python HTTP Backend: forwards HTTP