# libratbag/piper architecture

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

- Interactive diagram: https://gitdiagram.com/libratbag/piper
- Repository: https://github.com/libratbag/piper

## Overview

Piper is a GTK frontend for configuring gaming mice through the external ratbagd D-Bus daemon. The user selects a detected device, configures profile resolutions, buttons, LEDs, and advanced settings, then commits changes through the device UI. The graph follows documented and indexed calls; several device and dialog internals are only partially sampled, so no extra low-level D-Bus call edges are inferred.

Main entry points: [`piper/ratbagd.py`](https://github.com/libratbag/piper/blob/master/piper/ratbagd.py) (ratbagd client), [`piper/mouseperspective.py`](https://github.com/libratbag/piper/blob/master/piper/mouseperspective.py) (Device settings), [`piper/window.py`](https://github.com/libratbag/piper/blob/master/piper/window.py) (Main window), [`piper/buttonspage.py`](https://github.com/libratbag/piper/blob/master/piper/buttonspage.py) (Button settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application shell"]
  node_application["Application<br/>[application.py]"]
  node_window["Main window<br/>[window.py]"]
  node_welcome["Device selection"]
  node_errors["Error display"]
end

subgraph group_device["Device access"]
  node_ratbag["ratbagd client<br/>[ratbagd.py]"]
  node_gobject["Signal helper<br/>[gobject.py]"]
end

subgraph group_configure["Configuration UI"]
  node_mouse["Device settings"]
  node_profiles["Profile rows<br/>[profilerow.py]"]
  node_resolutions["Resolution settings<br/>[resolutionspage.py]"]
  node_resolutionrow["Resolution controls<br/>[resolutionrow.py]"]
  node_buttons["Button settings<br/>[buttonspage.py]"]
  node_buttondialog["Button mapping dialog<br/>[buttondialog.py]"]
  node_leds["LED settings<br/>[ledspage.py]"]
  node_leddialog["LED dialog<br/>[leddialog.py]"]
  node_advanced["Advanced settings<br/>[advancedpage.py]"]
  node_option["Option button<br/>[optionbutton.py]"]
end

subgraph group_visual["Mouse visualization"]
  node_mousemap["Mouse map<br/>[mousemap.py]"]
  node_svg["Device SVG<br/>[svg.py]"]
  node_devicerow["Device row<br/>[devicerow.py]"]
end

node_user(("User"))
node_daemon["ratbagd daemon"]

node_user -->|"launches"| node_application
node_application -->|"opens"| node_window
node_application -->|"initializes"| node_ratbag
node_window -->|"requests client"| node_ratbag
node_ratbag -->|"uses D-Bus"| node_daemon
node_window -->|"shows devices"| node_welcome
node_window -->|"shows failures"| node_errors
node_welcome -->|"renders devices"| node_devicerow
node_window -->|"opens selected device"| node_mouse
node_mouse -->|"renders profiles"| node_profiles
node_mouse -->|"creates page"| node_resolutions
node_mouse -->|"creates page"| node_buttons
node_mouse -->|"creates page"| node_leds
node_mouse -->|"creates page"| node_advanced
node_resolutions -->|"creates rows"| node_resolutionrow
node_resolutionrow -->|"updates resolution"| node_ratbag
node_buttons -->|"opens dialog"| node_buttondialog
node_buttondialog -->|"configures mapping"| node_ratbag
node_leds -->|"opens dialog"| node_leddialog
node_leddialog -->|"configures LED"| node_ratbag
node_advanced -->|"updates profile"| node_ratbag
node_buttons -->|"embeds controls"| node_mousemap
node_resolutions -->|"embeds map"| node_mousemap
node_leds -->|"embeds controls"| node_mousemap
node_mousemap -->|"renders device"| node_svg
node_buttons -->|"uses controls"| node_option
node_leds -->|"uses controls"| node_option
node_resolutionrow -->|"connects signals"| node_gobject

click node_application "https://github.com/libratbag/piper/blob/master/piper/application.py"
click node_window "https://github.com/libratbag/piper/blob/master/piper/window.py"
click node_welcome "https://github.com/libratbag/piper/blob/master/piper/welcomeperspective.py"
click node_errors "https://github.com/libratbag/piper/blob/master/piper/errorperspective.py"
click node_ratbag "https://github.com/libratbag/piper/blob/master/piper/ratbagd.py"
click node_mouse "https://github.com/libratbag/piper/blob/master/piper/mouseperspective.py"
click node_profiles "https://github.com/libratbag/piper/blob/master/piper/profilerow.py"
click node_resolutions "https://github.com/libratbag/piper/blob/master/piper/resolutionspage.py"
click node_resolutionrow "https://github.com/libratbag/piper/blob/master/piper/resolutionrow.py"
click node_buttons "https://github.com/libratbag/piper/blob/master/piper/buttonspage.py"
click node_buttondialog "https://github.com/libratbag/piper/blob/master/piper/buttondialog.py"
click node_leds "https://github.com/libratbag/piper/blob/master/piper/ledspage.py"
click node_leddialog "https://github.com/libratbag/piper/blob/master/piper/leddialog.py"
click node_advanced "https://github.com/libratbag/piper/blob/master/piper/advancedpage.py"
click node_option "https://github.com/libratbag/piper/blob/master/piper/optionbutton.py"
click node_mousemap "https://github.com/libratbag/piper/blob/master/piper/mousemap.py"
click node_svg "https://github.com/libratbag/piper/blob/master/piper/svg.py"
click node_devicerow "https://github.com/libratbag/piper/blob/master/piper/devicerow.py"
click node_gobject "https://github.com/libratbag/piper/blob/master/piper/util/gobject.py"

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_application,node_window,node_welcome,node_errors,node_user toneBlue
class node_ratbag,node_gobject toneAmber
class node_mouse,node_profiles,node_resolutions,node_resolutionrow,node_buttons,node_buttondialog,node_leds,node_leddialog,node_advanced,node_option toneMint
class node_mousemap,node_svg,node_devicerow toneRose
class node_daemon toneIndigo
```

## Components

### Application shell

- [Application](https://github.com/libratbag/piper/blob/master/piper/application.py): `piper/application.py`
- [Main window](https://github.com/libratbag/piper/blob/master/piper/window.py): `piper/window.py`
- [Device selection](https://github.com/libratbag/piper/blob/master/piper/welcomeperspective.py): `piper/welcomeperspective.py`
- [Error display](https://github.com/libratbag/piper/blob/master/piper/errorperspective.py): `piper/errorperspective.py`

### Device access

- [ratbagd client](https://github.com/libratbag/piper/blob/master/piper/ratbagd.py): `piper/ratbagd.py`
- [Signal helper](https://github.com/libratbag/piper/blob/master/piper/util/gobject.py): `piper/util/gobject.py`

### Configuration UI

- [Device settings](https://github.com/libratbag/piper/blob/master/piper/mouseperspective.py): `piper/mouseperspective.py`
- [Profile rows](https://github.com/libratbag/piper/blob/master/piper/profilerow.py): `piper/profilerow.py`
- [Resolution settings](https://github.com/libratbag/piper/blob/master/piper/resolutionspage.py): `piper/resolutionspage.py`
- [Resolution controls](https://github.com/libratbag/piper/blob/master/piper/resolutionrow.py): `piper/resolutionrow.py`
- [Button settings](https://github.com/libratbag/piper/blob/master/piper/buttonspage.py): `piper/buttonspage.py`
- [Button mapping dialog](https://github.com/libratbag/piper/blob/master/piper/buttondialog.py): `piper/buttondialog.py`
- [LED settings](https://github.com/libratbag/piper/blob/master/piper/ledspage.py): `piper/ledspage.py`
- [LED dialog](https://github.com/libratbag/piper/blob/master/piper/leddialog.py): `piper/leddialog.py`
- [Advanced settings](https://github.com/libratbag/piper/blob/master/piper/advancedpage.py): `piper/advancedpage.py`
- [Option button](https://github.com/libratbag/piper/blob/master/piper/optionbutton.py): `piper/optionbutton.py`

### Mouse visualization

- [Mouse map](https://github.com/libratbag/piper/blob/master/piper/mousemap.py): `piper/mousemap.py`
- [Device SVG](https://github.com/libratbag/piper/blob/master/piper/svg.py): `piper/svg.py`
- [Device row](https://github.com/libratbag/piper/blob/master/piper/devicerow.py): `piper/devicerow.py`

### Other components

- **User**
- **ratbagd daemon**

## Connections

- User → Application: launches (evidence: `README.md`)
- Application → Main window: opens (evidence: `piper/application.py`)
- Application → ratbagd client: initializes (evidence: `piper/application.py`)
- Main window → ratbagd client: requests client (evidence: `piper/window.py`)
- ratbagd client → ratbagd daemon: uses D-Bus (evidence: `README.md`)
- Main window → Device selection: shows devices (evidence: `piper/window.py`)
- Main window → Error display: shows failures (evidence: `piper/window.py`)
- Device selection → Device row: renders devices (evidence: `piper/welcomeperspective.py`)
- Main window → Device settings: opens selected device (evidence: `piper/window.py`)
- Device settings → Profile rows: renders profiles (evidence: `piper/mouseperspective.py`)
- Device settings → Resolution settings: creates page (evidence: `piper/mouseperspective.py`)
- Device settings → Button settings: creates page (evidence: `piper/mouseperspective.py`)
- Device settings → LED settings: creates page (evidence: `piper/mouseperspective.py`)
- Device settings → Advanced settings: creates page (evidence: `piper/mouseperspective.py`)
- Resolution settings → Resolution controls: creates rows (evidence: `piper/resolutionspage.py`)
- Resolution controls → ratbagd client: updates resolution (evidence: `piper/resolutionrow.py`)
- Button settings → Button mapping dialog: opens dialog (evidence: `piper/buttonspage.py`)
- Button mapping dialog → ratbagd client: configures mapping (evidence: `piper/buttondialog.py`)
- LED settings → LED dialog: opens dialog (evidence: `piper/ledspage.py`)
- LED dialog → ratbagd client: configures LED (evidence: `piper/leddialog.py`)
- Advanced settings → ratbagd client: updates profile (evidence: `piper/advancedpage.py`)
- Button settings → Mouse map: embeds controls (evidence: `piper/buttonspage.py`)
- Resolution settings → Mouse map: embeds map (evidence: `piper/resolutionspage.py`)
- LED settings → Mouse map: embeds controls (evidence: `piper/ledspage.py`)
- Mouse map → Device SVG: renders device (evidence: `piper/mousemap.py`)
- Button settings → Option button: uses controls (evidence: `piper/buttonspage.py`)
- LED settings → Option button: uses controls (evidence: `piper/ledspage.py`)
- Resolution controls → Signal helper: connects signals (evidence: `piper/resolutionrow.py`)
