Architecture

KVitals is a KDE Plasma 6 widget (plasmoid) with a modular architecture connecting native KSysGuard sensors to a QML UI through dedicated sensor components.

Data Flow

Sensor Modules (contents/ui/sensors/)

Each system metric has its own QML component under sensors/. These components encapsulate all sensor subscriptions, data parsing, and value formatting for their metric.

Module	Sensors	Exposed Properties
CpuSensors.qml	cpu/all/usage	cpuValue
MemorySensors.qml	memory/physical/used, total	ramValue
TempSensors.qml	cpu/all/averageTemperature	tempValue
GpuSensors.qml	gpu/all/usage, totalVram, usedVram, temperature	gpuValue, gpuRamValue, gpuTempValue, gpuDisplayValue, hasGpuData
BatterySensors.qml	power/<device>/chargePercentage, chargeRate	batValue, powerValue
NetworkSensors.qml	network/<iface>/download, upload	netDownValue, netUpValue

A shared Utils.qml singleton provides formatting helpers (formatBytes, formatRate) and sensor-reading utilities (sensorValueOrNaN, firstReadyNumber, maxReadyNumber, firstReadyVramPair).

Performance Benefits

1. Zero Subprocesses: No bash, awk, or cat commands are spawned.
2. Stable File Descriptors: No CLI pipes need to be kept open, eliminating Plasma 6 Wayland FD-exhaustion crashes.
3. Low Latency: The widget reads the exact same backend API as the official KDE System Monitor.

Orchestrator (main.qml)

main.qml acts as a lightweight orchestrator:

1. Reads configuration from Plasmoid.configuration
2. Instantiates sensor modules with the configured updateInterval
3. Builds metrics models using the orderedKeys array (derived from the metricOrder config)
4. Applies view-specific visibility rules such as compactShow* settings and compact grouping
5. Passes models to CompactView and FullView for rendering

main.qml
  ├── CpuSensors { id: cpu }
  ├── MemorySensors { id: memory }
  ├── TempSensors { id: temp }
  ├── GpuSensors { id: gpu }
  ├── BatterySensors { id: battery }
  ├── NetworkSensors { id: network }
  ├── compactRepresentation: CompactView { metricsModel: ... }
  └── fullRepresentation: FullView { metricsModel: ... }

Views

CompactView (Panel)

A RowLayout with a Repeater that renders each compact-visible metric as: - Icon (optional, via Kirigami.Icon with isMask: true) - Label (optional, e.g., "CPU:") - Value (always shown, e.g., "26%") - Separator (| between metrics)

Visibility of icons/labels is controlled by the displayMode property. Metric inclusion is controlled by both the metric-level show* settings and the compact-panel compactShow* settings, allowing a metric to remain visible in the popup/tooltip while being hidden from the panel.

The compact panel also supports horizontal and vertical delegates through the layoutType setting.

Tip

Icons use isMask: true to render as monochrome, matching the panel's text color regardless of the icon theme.

FullView (Popup)

A ColumnLayout with a Repeater showing a detailed row per enabled metric with label and bold value, displayed when clicking the widget.

Tooltip

Multi-line text showing all enabled metrics, displayed on hover. Compact-panel visibility settings do not filter the tooltip.

Configuration System

config/main.xml          ← Config schema (entry names, types, defaults)
config/config.qml        ← Tab registration (General, Metrics, Icons, Colors)
ui/configGeneral.qml     ← General tab (display mode, layout, font, interval)
ui/configMetrics.qml     ← Metrics tab (show/hide toggles, compact panel visibility, metric order, grouping, network interface, battery device)
ui/configIcons.qml       ← Icons tab (per-metric icon picker)
ui/configColors.qml      ← Colors tab (font color, warning/critical colors, thresholds)

All config values are accessed in main.qml via Plasmoid.configuration.<key>.

Adding a New Sensor

1. Create contents/ui/sensors/NewSensor.qml exposing formatted value properties
2. Register it in sensors/qmldir
3. Instantiate it in main.qml
4. Add it to the orderedKeys loop in compact/full/tooltip builders
5. Add show* and compactShow* config entries in main.xml
6. Add the metric and compact panel checkboxes in configMetrics.qml

Project Structure

kvitals/
├── metadata.json                   # Plasmoid metadata (name, version, id)
├── install.sh                      # Local install script
├── install-remote.sh               # Remote install (curl/wget)
├── CHANGELOG.md                    # Version history
├── docs/                           # Documentation
│   ├── installation.md
│   ├── configuration.md
│   ├── architecture.md
│   ├── contributing.md
│   └── troubleshooting.md
└── contents/
    ├── config/
    │   ├── config.qml              # Tab registration
    │   └── main.xml                # Config schema
    └── ui/
        ├── main.qml                # Widget orchestrator
        ├── CompactView.qml         # Panel representation
        ├── FullView.qml            # Popup representation
        ├── configGeneral.qml       # General settings tab
        ├── configMetrics.qml       # Metrics settings tab
        ├── configIcons.qml         # Icons settings tab
        ├── configColors.qml        # Colors settings tab
        └── sensors/                # Sensor modules
            ├── qmldir              # QML module definition
            ├── CpuSensors.qml      # CPU usage
            ├── MemorySensors.qml   # RAM usage
            ├── TempSensors.qml     # CPU temperature
            ├── GpuSensors.qml      # GPU usage, VRAM, temp
            ├── BatterySensors.qml  # Battery & power
            ├── NetworkSensors.qml  # Network speed
            └── Utils.qml           # Shared formatting helpers