# machad3x/way-vibrance architecture

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

- Interactive diagram: https://gitdiagram.com/machad3x/way-vibrance
- Repository: https://github.com/machad3x/way-vibrance

## Overview

Way Vibrance is a KDE Plasma 6 KWin desktop effect for global saturation and RGB gains, with per-window app profiles controlled through a tray UI or CLI. The main flow is user control → D-Bus settings → compositor-side window matching and color grading; settings persist across sessions. The README documents CLI, hotkeys, presets, monitor selection, and update checking. Source excerpts show D-Bus registration, asynchronous tray calls, profile matching, shader handling, and configuration persistence; unsampled CLI wiring is left unverified.

Main entry points: [`effect/vibranceeffect.cpp`](https://github.com/machad3x/way-vibrance/blob/main/effect/vibranceeffect.cpp) (Window color grading), [`tray/main.cpp`](https://github.com/machad3x/way-vibrance/blob/main/tray/main.cpp) (Tray UI), [`effect/vibranceeffect.h`](https://github.com/machad3x/way-vibrance/blob/main/effect/vibranceeffect.h) (D-Bus API), [`cli/wayvibrance`](https://github.com/machad3x/way-vibrance/blob/main/cli/wayvibrance) (CLI controls)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_controls["User controls"]
  node_tray["Tray UI<br/>[main.cpp]"]
  node_profile_editor["Profile editor<br/>[main.cpp]"]
  node_cli["CLI controls"]
  node_tray_widgets["UI widgets<br/>[resetbutton_p.h]"]
  node_theme["Theme styling<br/>[style_p.h]"]
  node_dbus_security["D-Bus trust check<br/>[dbus_security_p.h]"]
end

subgraph group_effect["Compositor effect"]
  node_effect_plugin["Effect plugin<br/>[main.cpp]"]
  node_vibrance["Window color grading<br/>[vibranceeffect.cpp]"]
  node_shader["RGB shader<br/>[wayvibrance.frag]"]
end

subgraph group_matching["Profiles and matching"]
  node_app_rules["App profiles<br/>[vibranceeffect.cpp]"]
  node_glob_match["Glob matching<br/>[globmatch_p.h]"]
end

subgraph group_state["Settings and integrations"]
  node_dbus_api["D-Bus API<br/>[vibranceeffect.h]"]
  node_config[("Persistent settings<br/>[vibranceeffect.cpp]")]
  node_limits["Shared limits<br/>[common_limits.h]"]
  node_update_check["Update check<br/>[main.cpp]"]
end

node_user(("Desktop user"))
node_kwin(("KWin compositor"))
node_window["Composited windows"]
node_network(("GitHub release service"))

node_user -->|"adjusts settings"| node_tray
node_user -->|"edits profiles"| node_profile_editor
node_user -->|"runs commands"| node_cli
node_tray -->|"sends settings"| node_dbus_api
node_profile_editor -->|"sends profiles"| node_dbus_api
node_cli -.->|"controls effect"| node_dbus_api
node_tray -->|"verifies owner"| node_dbus_security
node_tray -->|"uses controls"| node_tray_widgets
node_profile_editor -->|"uses controls"| node_tray_widgets
node_tray -->|"builds stylesheet"| node_theme
node_effect_plugin -->|"creates effect"| node_vibrance
node_kwin -->|"loads plugin"| node_effect_plugin
node_dbus_api -->|"exposes controls"| node_vibrance
node_vibrance -->|"grades frames"| node_window
node_vibrance -->|"selects profile"| node_app_rules
node_app_rules -->|"matches identities"| node_glob_match
node_vibrance -->|"applies RGB gains"| node_shader
node_vibrance -->|"persists settings"| node_config
node_vibrance -->|"uses bounds"| node_limits
node_tray -->|"offers check"| node_update_check
node_update_check -->|"requests release"| node_network

click node_tray "https://github.com/machad3x/way-vibrance/blob/main/tray/main.cpp"
click node_profile_editor "https://github.com/machad3x/way-vibrance/blob/main/tray/main.cpp"
click node_cli "https://github.com/machad3x/way-vibrance/blob/main/cli/wayvibrance"
click node_tray_widgets "https://github.com/machad3x/way-vibrance/blob/main/tray/resetbutton_p.h"
click node_theme "https://github.com/machad3x/way-vibrance/blob/main/tray/style_p.h"
click node_dbus_security "https://github.com/machad3x/way-vibrance/blob/main/tray/dbus_security_p.h"
click node_effect_plugin "https://github.com/machad3x/way-vibrance/blob/main/effect/main.cpp"
click node_vibrance "https://github.com/machad3x/way-vibrance/blob/main/effect/vibranceeffect.cpp"
click node_shader "https://github.com/machad3x/way-vibrance/blob/main/effect/shaders/wayvibrance.frag"
click node_app_rules "https://github.com/machad3x/way-vibrance/blob/main/effect/vibranceeffect.cpp"
click node_glob_match "https://github.com/machad3x/way-vibrance/blob/main/effect/globmatch_p.h"
click node_dbus_api "https://github.com/machad3x/way-vibrance/blob/main/effect/vibranceeffect.h"
click node_config "https://github.com/machad3x/way-vibrance/blob/main/effect/vibranceeffect.cpp"
click node_limits "https://github.com/machad3x/way-vibrance/blob/main/common_limits.h"
click node_update_check "https://github.com/machad3x/way-vibrance/blob/main/tray/main.cpp"

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_tray,node_profile_editor,node_cli,node_tray_widgets,node_theme,node_dbus_security,node_user toneBlue
class node_effect_plugin,node_vibrance,node_shader toneAmber
class node_app_rules,node_glob_match toneMint
class node_dbus_api,node_config,node_limits,node_update_check toneRose
class node_kwin,node_window,node_network toneIndigo
```

## Components

### User controls

- [Tray UI](https://github.com/machad3x/way-vibrance/blob/main/tray/main.cpp): `tray/main.cpp`
- [Profile editor](https://github.com/machad3x/way-vibrance/blob/main/tray/main.cpp): `tray/main.cpp`
- [CLI controls](https://github.com/machad3x/way-vibrance/blob/main/cli/wayvibrance): `cli/wayvibrance`
- [UI widgets](https://github.com/machad3x/way-vibrance/blob/main/tray/resetbutton_p.h): `tray/resetbutton_p.h`
- [Theme styling](https://github.com/machad3x/way-vibrance/blob/main/tray/style_p.h): `tray/style_p.h`
- [D-Bus trust check](https://github.com/machad3x/way-vibrance/blob/main/tray/dbus_security_p.h): `tray/dbus_security_p.h`

### Compositor effect

- [Effect plugin](https://github.com/machad3x/way-vibrance/blob/main/effect/main.cpp): `effect/main.cpp`
- [Window color grading](https://github.com/machad3x/way-vibrance/blob/main/effect/vibranceeffect.cpp): `effect/vibranceeffect.cpp`
- [RGB shader](https://github.com/machad3x/way-vibrance/blob/main/effect/shaders/wayvibrance.frag): `effect/shaders/wayvibrance.frag`

### Profiles and matching

- [App profiles](https://github.com/machad3x/way-vibrance/blob/main/effect/vibranceeffect.cpp): `effect/vibranceeffect.cpp`
- [Glob matching](https://github.com/machad3x/way-vibrance/blob/main/effect/globmatch_p.h): `effect/globmatch_p.h`

### Settings and integrations

- [D-Bus API](https://github.com/machad3x/way-vibrance/blob/main/effect/vibranceeffect.h): `effect/vibranceeffect.h`
- [Persistent settings](https://github.com/machad3x/way-vibrance/blob/main/effect/vibranceeffect.cpp): `effect/vibranceeffect.cpp`
- [Shared limits](https://github.com/machad3x/way-vibrance/blob/main/common_limits.h): `common_limits.h`
- [Update check](https://github.com/machad3x/way-vibrance/blob/main/tray/main.cpp): `tray/main.cpp`

### Other components

- **Desktop user**
- **KWin compositor**
- **Composited windows**
- **GitHub release service**

## Connections

- Desktop user → Tray UI: adjusts settings (evidence: `README.md`)
- Desktop user → Profile editor: edits profiles (evidence: `README.md`)
- Desktop user → CLI controls: runs commands (evidence: `README.md`)
- Tray UI → D-Bus API: sends settings (evidence: `tray/main.cpp`)
- Profile editor → D-Bus API: sends profiles (evidence: `tray/main.cpp`)
- CLI controls → D-Bus API: controls effect
- Tray UI → D-Bus trust check: verifies owner (evidence: `tray/dbus_security_p.h`)
- Tray UI → UI widgets: uses controls (evidence: `tray/main.cpp`)
- Profile editor → UI widgets: uses controls (evidence: `tray/main.cpp`)
- Tray UI → Theme styling: builds stylesheet (evidence: `tray/main.cpp`)
- Effect plugin → Window color grading: creates effect (evidence: `effect/main.cpp`)
- KWin compositor → Effect plugin: loads plugin (evidence: `effect/main.cpp`)
- D-Bus API → Window color grading: exposes controls (evidence: `effect/vibranceeffect.h`)
- Window color grading → Composited windows: grades frames
- Window color grading → App profiles: selects profile (evidence: `effect/vibranceeffect.cpp`)
- App profiles → Glob matching: matches identities (evidence: `effect/vibranceeffect.cpp`)
- Window color grading → RGB shader: applies RGB gains (evidence: `README.md`)
- Window color grading → Persistent settings: persists settings (evidence: `effect/vibranceeffect.cpp`)
- Window color grading → Shared limits: uses bounds (evidence: `effect/vibranceeffect.cpp`)
- Tray UI → Update check: offers check (evidence: `README.md`)
- Update check → GitHub release service: requests release (evidence: `tray/main.cpp`)
