# kasvith/simplelb architecture

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

- Interactive diagram: https://gitdiagram.com/kasvith/simplelb
- Repository: https://github.com/kasvith/simplelb

## Overview

SimpleLB is a small Go reverse-proxy load balancer. The operator supplies backend URLs and a listening port; incoming HTTP requests are routed to an active backend using round robin, with proxy retries and backend removal after repeated failures. A periodic health check updates backend availability. These responsibilities are implemented together in main.go, so component paths are shared. The sampled source shows TCP-based health checks; the README describes the availability behavior at a high level.

Main entry points: [`main.go`](https://github.com/kasvith/simplelb/blob/master/main.go) (Startup and configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Startup"]
  node_main["Startup and configuration<br/>[main.go]"]
  node_listener["HTTP listener<br/>[main.go]"]
end

subgraph group_routing["Request routing"]
  node_handler["Request handler<br/>[main.go]"]
  node_pool["Backend pool<br/>[main.go]"]
  node_proxy["Reverse proxy and retries<br/>[main.go]"]
end

subgraph group_health["Backend health"]
  node_scheduler["Health scheduler<br/>[main.go]"]
  node_healthcheck["Health checker<br/>[main.go]"]
end

node_operator(("Operator"))
node_client(("HTTP client"))
node_backends["Backend servers"]

node_operator -->|"configures"| node_main
node_main -->|"registers backends"| node_pool
node_main -->|"starts"| node_listener
node_client -->|"sends requests"| node_listener
node_listener -->|"dispatches"| node_handler
node_handler -->|"selects peer"| node_pool
node_handler -->|"serves request"| node_proxy
node_proxy -->|"proxies requests"| node_backends
node_proxy -->|"marks failed peer"| node_pool
node_proxy -->|"retries routing"| node_handler
node_main -->|"starts"| node_scheduler
node_scheduler -->|"runs periodically"| node_healthcheck
node_healthcheck -->|"checks TCP reachability"| node_backends
node_healthcheck -->|"updates status"| node_pool

click node_main "https://github.com/kasvith/simplelb/blob/master/main.go"
click node_listener "https://github.com/kasvith/simplelb/blob/master/main.go"
click node_handler "https://github.com/kasvith/simplelb/blob/master/main.go"
click node_pool "https://github.com/kasvith/simplelb/blob/master/main.go"
click node_proxy "https://github.com/kasvith/simplelb/blob/master/main.go"
click node_scheduler "https://github.com/kasvith/simplelb/blob/master/main.go"
click node_healthcheck "https://github.com/kasvith/simplelb/blob/master/main.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_main,node_listener,node_client toneBlue
class node_handler,node_pool,node_proxy toneAmber
class node_scheduler,node_healthcheck,node_backends toneMint
class node_operator toneIndigo
```

## Components

### Startup

- [Startup and configuration](https://github.com/kasvith/simplelb/blob/master/main.go): `main.go`
- [HTTP listener](https://github.com/kasvith/simplelb/blob/master/main.go): `main.go`

### Request routing

- [Request handler](https://github.com/kasvith/simplelb/blob/master/main.go): `main.go`
- [Backend pool](https://github.com/kasvith/simplelb/blob/master/main.go): `main.go`
- [Reverse proxy and retries](https://github.com/kasvith/simplelb/blob/master/main.go): `main.go`

### Backend health

- [Health scheduler](https://github.com/kasvith/simplelb/blob/master/main.go): `main.go`
- [Health checker](https://github.com/kasvith/simplelb/blob/master/main.go): `main.go`

### Other components

- **Operator**
- **HTTP client**
- **Backend servers**

## Connections

- Operator → Startup and configuration: configures (evidence: `README.md`)
- Startup and configuration → Backend pool: registers backends (evidence: `main.go`)
- Startup and configuration → HTTP listener: starts (evidence: `main.go`)
- HTTP client → HTTP listener: sends requests (evidence: `main.go`)
- HTTP listener → Request handler: dispatches (evidence: `main.go`)
- Request handler → Backend pool: selects peer (evidence: `main.go`)
- Request handler → Reverse proxy and retries: serves request (evidence: `main.go`)
- Reverse proxy and retries → Backend servers: proxies requests (evidence: `main.go`)
- Reverse proxy and retries → Backend pool: marks failed peer (evidence: `main.go`)
- Reverse proxy and retries → Request handler: retries routing (evidence: `main.go`)
- Startup and configuration → Health scheduler: starts (evidence: `main.go`)
- Health scheduler → Health checker: runs periodically (evidence: `main.go`)
- Health checker → Backend servers: checks TCP reachability (evidence: `main.go`)
- Health checker → Backend pool: updates status (evidence: `main.go`)
