# onimekh/oci-cpu-balancer architecture

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

- Interactive diagram: https://gitdiagram.com/onimekh/oci-cpu-balancer
- Repository: https://github.com/onimekh/oci-cpu-balancer

## Overview

This repository provides an OCI CPU balancer and a separate watchdog. The main runtime loop aims to keep system CPU utilization within a configured range while yielding to real workloads; an hourly watchdog can restart a manually stopped service after 24 idle hours. The README describes the service, timer, configuration, scheduling policy, and memory cap, but no source excerpts were supplied, so the graph shows only documented relationships.

Main entry points: [`oci-cpu-balancer`](https://github.com/onimekh/oci-cpu-balancer/blob/main/oci-cpu-balancer) (CPU balancer), [`oci-cpu-balancer.service`](https://github.com/onimekh/oci-cpu-balancer/blob/main/oci-cpu-balancer.service) (Balancer service), [`oci-cpu-watchdog`](https://github.com/onimekh/oci-cpu-balancer/blob/main/oci-cpu-watchdog) (Watchdog), [`oci-cpu-watchdog.service`](https://github.com/onimekh/oci-cpu-balancer/blob/main/oci-cpu-watchdog.service) (Watchdog service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["CPU control"]
  node_config["Balancer config"]
  node_balancer["CPU balancer"]
end

subgraph group_watchdog["Watchdog"]
  node_watchdog["Watchdog"]
  node_watchdog_unit["Watchdog service"]
  node_timer["Hourly timer"]
end

subgraph group_runtime["Host runtime"]
  node_balancer_unit["Balancer service"]
  node_kernel["Linux scheduler"]
  node_cpu[("Host CPU usage")]
end

node_admin(("Operator"))
node_workload["Host workloads"]
node_systemd["systemd"]

node_config -->|"configures"| node_balancer
node_balancer_unit -->|"runs"| node_balancer
node_balancer -->|"maintains target"| node_cpu
node_balancer -->|"runs idle priority"| node_kernel
node_workload -->|"preempts burners"| node_kernel
node_timer -->|"triggers hourly"| node_watchdog_unit
node_watchdog_unit -->|"runs"| node_watchdog
node_watchdog -->|"restarts when idle"| node_balancer_unit
node_systemd -->|"caps memory"| node_balancer_unit
node_admin -->|"manages services"| node_systemd

click node_config "https://github.com/onimekh/oci-cpu-balancer/blob/main/oci-cpu-balancer.conf"
click node_balancer "https://github.com/onimekh/oci-cpu-balancer/blob/main/oci-cpu-balancer"
click node_balancer_unit "https://github.com/onimekh/oci-cpu-balancer/blob/main/oci-cpu-balancer.service"
click node_watchdog "https://github.com/onimekh/oci-cpu-balancer/blob/main/oci-cpu-watchdog"
click node_watchdog_unit "https://github.com/onimekh/oci-cpu-balancer/blob/main/oci-cpu-watchdog.service"
click node_timer "https://github.com/onimekh/oci-cpu-balancer/blob/main/oci-cpu-watchdog.timer"

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_config,node_balancer toneBlue
class node_watchdog,node_watchdog_unit,node_timer toneAmber
class node_balancer_unit,node_kernel,node_cpu toneMint
class node_admin,node_workload,node_systemd toneIndigo
```

## Components

### CPU control

- [Balancer config](https://github.com/onimekh/oci-cpu-balancer/blob/main/oci-cpu-balancer.conf): `oci-cpu-balancer.conf`
- [CPU balancer](https://github.com/onimekh/oci-cpu-balancer/blob/main/oci-cpu-balancer): `oci-cpu-balancer`

### Watchdog

- [Watchdog](https://github.com/onimekh/oci-cpu-balancer/blob/main/oci-cpu-watchdog): `oci-cpu-watchdog`
- [Watchdog service](https://github.com/onimekh/oci-cpu-balancer/blob/main/oci-cpu-watchdog.service): `oci-cpu-watchdog.service`
- [Hourly timer](https://github.com/onimekh/oci-cpu-balancer/blob/main/oci-cpu-watchdog.timer): `oci-cpu-watchdog.timer`

### Host runtime

- [Balancer service](https://github.com/onimekh/oci-cpu-balancer/blob/main/oci-cpu-balancer.service): `oci-cpu-balancer.service`
- **Linux scheduler**
- **Host CPU usage**

### Other components

- **Operator**
- **Host workloads**
- **systemd**

## Connections

- Balancer config → CPU balancer: configures (evidence: `README.md`)
- Balancer service → CPU balancer: runs (evidence: `README.md`)
- CPU balancer → Host CPU usage: maintains target (evidence: `README.md`)
- CPU balancer → Linux scheduler: runs idle priority (evidence: `README.md`)
- Host workloads → Linux scheduler: preempts burners (evidence: `README.md`)
- Hourly timer → Watchdog service: triggers hourly (evidence: `README.md`)
- Watchdog service → Watchdog: runs (evidence: `README.md`)
- Watchdog → Balancer service: restarts when idle (evidence: `README.md`)
- systemd → Balancer service: caps memory (evidence: `README.md`)
- Operator → systemd: manages services (evidence: `README.md`)
