# abhikdps/zero-overhead-lb architecture

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

- Interactive diagram: https://gitdiagram.com/abhikdps/zero-overhead-lb
- Repository: https://github.com/abhikdps/zero-overhead-lb

## Overview

Zero-Overhead Load Balancer routes TCP/UDP traffic at the NIC through an XDP/eBPF data plane, while a userspace CLI configures and manages it. The main flow is packet parsing and VIP lookup, affinity-aware backend selection, packet rewriting and forwarding; unmatched traffic passes to the kernel. Userspace also supports health checks and live backend failover, map-based statistics, event streaming, and hitless reload. Sampled source shows the key calls and map interactions; other documented CLI capabilities are included where source excerpts are incomplete.

Main entry points: [`src/user/main.c`](https://github.com/abhikdps/zero-overhead-lb/blob/main/src/user/main.c) (CLI commands), [`src/bpf/xdp_lb_kern.c`](https://github.com/abhikdps/zero-overhead-lb/blob/main/src/bpf/xdp_lb_kern.c) (Packet routing), [`src/user/health.c`](https://github.com/abhikdps/zero-overhead-lb/blob/main/src/user/health.c) (Backend health), [`src/user/stats.c`](https://github.com/abhikdps/zero-overhead-lb/blob/main/src/user/stats.c) (Stats reporting)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control plane"]
  node_cli["CLI commands<br/>[main.c]"]
  node_config["Config parsing<br/>[config.c]"]
end

subgraph group_data["XDP data plane"]
  node_xdp["Packet routing<br/>[xdp_lb_kern.c]"]
end

subgraph group_state["BPF map state"]
  node_map_contract["Map data contract<br/>[xdp_lb_common.h]"]
  node_maps[("BPF maps<br/>[xdp_lb_kern.c]")]
end

subgraph group_ops["Health and observability"]
  node_health["Backend health<br/>[health.c]"]
  node_stats["Stats reporting<br/>[stats.c]"]
  node_events["Event streaming<br/>[events.c]"]
end

node_operator(("Operator"))
node_traffic(("Incoming traffic"))
node_backend_hosts["Backend hosts"]
node_kernel["Kernel network stack"]

node_operator -->|"runs commands"| node_cli
node_traffic -->|"enters XDP"| node_xdp
node_cli -->|"loads and validates"| node_config
node_cli -->|"loads and attaches"| node_xdp
node_cli -->|"populates and reloads"| node_maps
node_xdp -->|"uses shared structs"| node_map_contract
node_xdp -->|"looks up and updates"| node_maps
node_xdp -->|"forwards packets"| node_backend_hosts
node_xdp -->|"passes unmatched traffic"| node_kernel
node_xdp -->|"writes events and counters"| node_maps
node_cli -->|"starts health checks"| node_health
node_health -->|"checks TCP health"| node_backend_hosts
node_health -->|"updates backend slots"| node_maps
node_cli -->|"dispatches stats"| node_stats
node_stats -->|"reads counters and backends"| node_maps
node_cli -->|"dispatches events"| node_events
node_events -->|"consumes ring buffer"| node_maps

click node_cli "https://github.com/abhikdps/zero-overhead-lb/blob/main/src/user/main.c"
click node_config "https://github.com/abhikdps/zero-overhead-lb/blob/main/src/user/config.c"
click node_xdp "https://github.com/abhikdps/zero-overhead-lb/blob/main/src/bpf/xdp_lb_kern.c"
click node_map_contract "https://github.com/abhikdps/zero-overhead-lb/blob/main/src/bpf/xdp_lb_common.h"
click node_maps "https://github.com/abhikdps/zero-overhead-lb/blob/main/src/bpf/xdp_lb_kern.c"
click node_health "https://github.com/abhikdps/zero-overhead-lb/blob/main/src/user/health.c"
click node_stats "https://github.com/abhikdps/zero-overhead-lb/blob/main/src/user/stats.c"
click node_events "https://github.com/abhikdps/zero-overhead-lb/blob/main/src/user/events.c"

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_config toneBlue
class node_xdp toneAmber
class node_map_contract,node_maps toneMint
class node_health,node_stats,node_events toneRose
class node_operator,node_traffic,node_backend_hosts,node_kernel toneIndigo
```

## Components

### Control plane

- [CLI commands](https://github.com/abhikdps/zero-overhead-lb/blob/main/src/user/main.c): `src/user/main.c`
- [Config parsing](https://github.com/abhikdps/zero-overhead-lb/blob/main/src/user/config.c): `src/user/config.c`

### XDP data plane

- [Packet routing](https://github.com/abhikdps/zero-overhead-lb/blob/main/src/bpf/xdp_lb_kern.c): `src/bpf/xdp_lb_kern.c`

### BPF map state

- [Map data contract](https://github.com/abhikdps/zero-overhead-lb/blob/main/src/bpf/xdp_lb_common.h): `src/bpf/xdp_lb_common.h`
- [BPF maps](https://github.com/abhikdps/zero-overhead-lb/blob/main/src/bpf/xdp_lb_kern.c): `src/bpf/xdp_lb_kern.c`

### Health and observability

- [Backend health](https://github.com/abhikdps/zero-overhead-lb/blob/main/src/user/health.c): `src/user/health.c`
- [Stats reporting](https://github.com/abhikdps/zero-overhead-lb/blob/main/src/user/stats.c): `src/user/stats.c`
- [Event streaming](https://github.com/abhikdps/zero-overhead-lb/blob/main/src/user/events.c): `src/user/events.c`

### Other components

- **Operator**
- **Incoming traffic**
- **Backend hosts**
- **Kernel network stack**

## Connections

- Operator → CLI commands: runs commands (evidence: `README.md`)
- Incoming traffic → Packet routing: enters XDP (evidence: `README.md`)
- CLI commands → Config parsing: loads and validates (evidence: `src/user/main.c`)
- CLI commands → Packet routing: loads and attaches (evidence: `src/user/main.c`)
- CLI commands → BPF maps: populates and reloads (evidence: `src/user/main.c`)
- Packet routing → Map data contract: uses shared structs (evidence: `src/bpf/xdp_lb_kern.c`)
- Packet routing → BPF maps: looks up and updates (evidence: `src/bpf/xdp_lb_kern.c`)
- Packet routing → Backend hosts: forwards packets (evidence: `README.md`)
- Packet routing → Kernel network stack: passes unmatched traffic (evidence: `src/bpf/xdp_lb_kern.c`)
- Packet routing → BPF maps: writes events and counters (evidence: `src/bpf/xdp_lb_kern.c`)
- CLI commands → Backend health: starts health checks (evidence: `src/user/main.c`)
- Backend health → Backend hosts: checks TCP health (evidence: `src/user/health.c`)
- Backend health → BPF maps: updates backend slots (evidence: `src/user/health.c`)
- CLI commands → Stats reporting: dispatches stats (evidence: `README.md`)
- Stats reporting → BPF maps: reads counters and backends (evidence: `src/user/stats.c`)
- CLI commands → Event streaming: dispatches events (evidence: `README.md`)
- Event streaming → BPF maps: consumes ring buffer (evidence: `src/user/events.c`)
