graph TB
 subgraph "QML UI"
 Main[Main.qml]
 Pages[Pages: PointScroll, Buttons, EasySwitch, Settings]
 Components[Components: DeviceRender, SideNav, ProfileBar]
 end
 subgraph "App Layer (logitune-app-lib)"
 AC[AppController]
 DM_model[DeviceModel]
 BM[ButtonModel]
 AM[ActionModel]
 PM[ProfileModel]
 TM[TrayManager]
 end
 subgraph "Core Layer (logitune-core)"
 DevMgr[DeviceManager]
 PE[ProfileEngine]
 AE[ActionExecutor]
 DR[DeviceRegistry]
 
 subgraph "HID++ Protocol"
 FD[FeatureDispatcher]
 CQ[CommandQueue]
 TR[Transport]
 HR[HidrawDevice]
 end
 subgraph "Desktop Integration"
 IDesktop[IDesktopIntegration]
 KDE[KDeDesktop]
 Generic[GenericDesktop]
 end
 subgraph "Input Injection"
 IInject[IInputInjector]
 Uinput[UinputInjector]
 end
 end
 subgraph "System"
 hidraw[/dev/hidrawN/]
 udev[libudev]
 dbus[D-Bus Session Bus]
 uinputdev[/dev/uinput/]
 end
 Main --> DM_model
 Main --> BM
 Main --> AM
 Main --> PM
 Pages --> DM_model
 Pages --> BM
 AC --> DM_model
 AC --> BM
 AC --> AM
 AC --> PM
 AC --> DevMgr
 AC --> PE
 AC --> AE
 AC --> IDesktop
 DevMgr --> DR
 DevMgr --> FD
 DevMgr --> CQ
 DevMgr --> TR
 DevMgr --> udev
 FD --> TR
 CQ --> FD
 TR --> HR
 HR --> hidraw
 KDE --> dbus
 IDesktop -.-> KDE
 IDesktop -.-> Generic
 AE --> IInject
 IInject -.-> Uinput
 Uinput --> uinputdev
 TM --> DM_model

sequenceDiagram
 participant KWin as KWin Script
 participant KDE as KDeDesktop
 participant AC as AppController
 participant PE as ProfileEngine
 participant PM as ProfileModel
 participant DM as DeviceModel
 participant DMgr as DeviceManager
 participant CQ as CommandQueue
 participant FD as FeatureDispatcher
 participant TR as Transport
 KWin->>KDE: callDBus focusChanged(resourceClass, title, desktopFileName)
 KDE->>KDE: resolveDesktopFile(resourceClass)
 KDE->>AC: activeWindowChanged(appId, title)
 
 Note over AC: Skip shell components (plasmashell, krunner)
 
 AC->>DM: setActiveWmClass(wmClass)
 AC->>PE: profileForApp(wmClass)
 PE-->>AC: profileName (or "default")
 
 Note over AC: Skip if same as current hardware profile
 
 AC->>PE: cachedProfile(profileName)
 AC->>PE: setHardwareProfile(profileName)
 AC->>AC: applyProfileToHardware(profile)
 
 par Apply all settings
 AC->>DMgr: divertButton(CID, divert, rawXY) [for each button]
 AC->>DMgr: setDPI(value)
 AC->>DMgr: setSmartShift(enabled, threshold)
 AC->>DMgr: setScrollConfig(hiRes, invert)
 AC->>DMgr: setThumbWheelMode(mode, invert)
 end
 
 Note over DMgr: Each setter enqueues via CommandQueue
 
 loop For each enqueued command
 CQ->>FD: callAsync(feature, functionId, params)
 FD->>TR: sendRequestAsync(report)
 TR->>TR: write to hidraw fd
 Note over CQ: Wait 10ms before next command
 end
 
 AC->>PM: setHwActiveByProfileName(profileName)

graph TB
 subgraph "Application"
 DevMgr[DeviceManager]
 end
 subgraph "Protocol"
 CQ[CommandQueue<br/>10ms pacing, retry]
 FD[FeatureDispatcher<br/>Feature table, callAsync, softwareId]
 TR[Transport<br/>send/receive, timeout, error handling]
 HR[HidrawDevice<br/>open, read, write, poll]
 end
 subgraph "Kernel"
 hidraw[hidraw fd]
 end
 DevMgr --> CQ
 DevMgr --> FD
 CQ --> FD
 FD --> TR
 TR --> HR
 HR --> hidraw

sequenceDiagram
 participant FD as FeatureDispatcher
 participant TR as Transport
 participant Dev as Device
 loop For each known FeatureId
 FD->>TR: send Root.getFeatureID(featureId)
 TR->>Dev: HID++ report
 Dev-->>TR: response with featureIndex
 TR-->>FD: Report
 Note over FD: Store featureId -> featureIndex mapping
 end

sequenceDiagram
 participant App as DeviceManager
 participant CQ as CommandQueue
 participant Timer as QTimer (10ms)
 participant FD as FeatureDispatcher
 participant TR as Transport
 App->>CQ: enqueue(SetDPI, ...)
 App->>CQ: enqueue(SetSmartShift, ...)
 App->>CQ: enqueue(DivertButton, ...)
 App->>CQ: enqueue(DivertButton, ...)
 Note over CQ: Queue: [SetDPI, SetSmartShift, Divert, Divert]
 Timer->>CQ: processNext()
 CQ->>FD: callAsync(SetDPI, ...)
 FD->>TR: sendRequestAsync(report)
 Note over CQ: Wait 10ms
 Timer->>CQ: processNext()
 CQ->>FD: callAsync(SetSmartShift, ...)
 Note over CQ: Wait 10ms
 Timer->>CQ: processNext()
 CQ->>FD: callAsync(DivertButton, ...)
 Note over CQ: Continue until queue empty
 CQ-->>App: queueDrained()

sequenceDiagram
 participant CQ as CommandQueue
 participant FD as FeatureDispatcher
 participant TR as Transport
 participant Notif as QSocketNotifier
 CQ->>FD: callAsync(feature, fn, params, callback)
 Note over FD: Assign softwareId = 3 (rotating 1-15)
 FD->>TR: sendRequestAsync(report with swId=3)
 Note over TR: Later, device responds...
 Notif->>Notif: hidraw fd readable
 Notif->>Notif: readReport -> parse Report
 Note over Notif: report.softwareId = 3 (non-zero)
 Notif->>FD: handleResponse(report)
 Note over FD: Look up callback for swId=3
 FD->>FD: callback(report)
 Note over FD: Remove pending callback

graph TB
 subgraph "ProfileEngine"
 Cache["In-Memory Cache<br/>QMap&lt;QString, Profile&gt;"]
 Disk["Disk Storage<br/>~/.config/Logitune/devices/&lt;serial&gt;/profiles/"]
 Bindings["App Bindings<br/>app-bindings.conf"]
 Display["displayProfile<br/>(what UI shows)"]
 Hardware["hardwareProfile<br/>(what device runs)"]
 end
 subgraph "Files"
 Default["default.conf"]
 Firefox["firefox.conf"]
 VSCode["code.conf"]
 AppBindConf["app-bindings.conf"]
 end
 Cache --> Default
 Cache --> Firefox
 Cache --> VSCode
 Bindings --> AppBindConf
 
 Display --> Cache
 Hardware --> Cache

graph LR
 subgraph "View (QML)"
 PointScroll[PointScrollPage.qml]
 Buttons[ButtonsPage.qml]
 EasySwitch[EasySwitchPage.qml]
 Settings[SettingsPage.qml]
 ProfileBar[AppProfileBar.qml]
 end
 subgraph "ViewModel (C++ Models)"
 DM[DeviceModel<br/>QObject singleton]
 BM[ButtonModel<br/>QAbstractListModel]
 AM[ActionModel<br/>QAbstractListModel]
 PM[ProfileModel<br/>QAbstractListModel]
 end
 subgraph "Model (Core)"
 DMgr[DeviceManager]
 PE[ProfileEngine]
 AE[ActionExecutor]
 end
 PointScroll --> DM
 Buttons --> BM
 Buttons --> AM
 Buttons --> DM
 EasySwitch --> DM
 Settings --> DM
 ProfileBar --> PM
 DM --> DMgr
 BM --> AC[AppController]
 AM --> AC
 PM --> AC
 AC --> DMgr
 AC --> PE
 AC --> AE

classDiagram
 class IDesktopIntegration {
 <<abstract>>
 +start()
 +available() bool
 +desktopName() QString
 +detectedCompositors() QStringList
 +blockGlobalShortcuts(bool block)
 +runningApplications() QVariantList
 +activeWindowChanged(wmClass, title) signal
 }
 class KDeDesktop {
 +focusChanged(resourceClass, title, desktopFileName)
 -resolveDesktopFile(resourceClass) QString
 -m_kwin : QDBusInterface
 -m_pollTimer : QTimer
 -m_resolveCache : QHash
 }
 class GenericDesktop {
 +start()
 +available() bool
 }
 IDesktopIntegration <|-- KDeDesktop
 IDesktopIntegration <|-- GenericDesktop

sequenceDiagram
 participant KWin as KWin Compositor
 participant Script as Focus Watcher Script
 participant DBus as D-Bus Session Bus
 participant KDE as KDeDesktop
 participant AC as AppController
 Note over KDE: On start, register D-Bus service com.logitune.app
 KDE->>KWin: loadScript(logitune_focus_watcher.js)
 KDE->>KWin: start()
 Note over Script: workspace.windowActivated.connect(update)
 KWin->>Script: windowActivated
 Script->>DBus: callDBus('com.logitune.app', '/FocusWatcher', focusChanged, resourceClass, caption, desktopFileName)
 DBus->>KDE: focusChanged(resourceClass, title, desktopFileName)
 KDE->>KDE: resolveDesktopFile(resourceClass)
 Note over KDE: 1. Use desktopFileName if present<br/>2. Search .desktop files by name/StartupWMClass<br/>3. Fall back to resourceClass
 KDE->>AC: activeWindowChanged(appId, title)

flowchart TD
 Start[DeviceManager::start] --> InitUdev[Initialize libudev monitor]
 InitUdev --> Scan[scanExistingDevices]
 Scan --> ForEach{For each /dev/hidrawN}
 ForEach --> CheckVendor{Vendor == 0x046d?}
 CheckVendor -->|No| ForEach
 CheckVendor -->|Yes| Probe[probeDevice]
 Probe --> CheckDesc{sysfs report_descriptor<br/>has HID++ report ID 0x11?}
 CheckDesc -->|No| Skip[Skip - wrong interface]
 CheckDesc -->|Yes| Open[Open hidraw fd]
 Open --> CheckPID{PID matches<br/>Bolt/Unifying receiver?}
 CheckPID -->|Receiver| PingSlots[Ping slots 1-6]
 PingSlots --> Found{Response from slot?}
 Found -->|Yes| Connect[Store device + index]
 Found -->|No| KeepOpen[Keep receiver open<br/>for DJ notifications]
 CheckPID -->|Direct device| SetDirect[deviceIndex = 0xFF]
 SetDirect --> Connect
 Connect --> Enumerate[enumerateAndSetup]
 Enumerate --> Features[FeatureDispatcher::enumerate]
 Features --> ReadState[Read battery, DPI, SmartShift, scroll, thumb wheel, Easy-Switch]
 ReadState --> LookupDesc[DeviceRegistry::findByPid/findByName]
 LookupDesc --> Undivert[Undivert all buttons + thumb wheel]
 Undivert --> CreateQueue[Create CommandQueue]
 CreateQueue --> Signal[emit deviceSetupComplete]

sequenceDiagram
 participant Dev as Device
 participant Recv as Bolt Receiver
 participant DMgr as DeviceManager
 Dev->>Recv: (device powers off)
 Recv->>DMgr: HID++ 1.0 notification<br/>featureIndex=0x41<br/>params[0] bit 6 = 1 (link not established)
 
 Note over DMgr: Soft disconnect:<br/>- Clear CommandQueue<br/>- Reset features<br/>- Keep hidraw fd open<br/>- Emit deviceDisconnected
 Dev->>Recv: (device powers on)
 Recv->>DMgr: HID++ 1.0 notification<br/>featureIndex=0x41<br/>params[0] bit 6 = 0 (link established)
 
 Note over DMgr: Start 1500ms reconnect timer<br/>(debounce — device sends multiple<br/>notifications during boot)
 
 DMgr->>DMgr: Timer fires: enumerateAndSetup()
 Note over DMgr: Re-enumerate features,<br/>re-read state,<br/>re-create CommandQueue,<br/>emit deviceSetupComplete

stateDiagram-v2
 [*] --> Idle
 Idle --> GestureActive : Gesture button pressed<br/>(CID 0x00C3, diverted)
 
 GestureActive --> GestureActive : Raw XY deltas<br/>accumulate dx, dy
 
 GestureActive --> ResolveGesture : Button released<br/>(controlId = 0, all released)
 
 ResolveGesture --> ExecuteAction : |dx| or |dy| > 50
 ResolveGesture --> ExecuteClick : |dx| and |dy| <= 50
 ExecuteAction --> Idle : Inject keystroke<br/>(Up/Down/Left/Right)
 ExecuteClick --> Idle : Inject keystroke<br/>(Click gesture)

graph TB
 subgraph "Owned Subsystems"
 Registry[DeviceRegistry]
 DevMgr[DeviceManager]
 PE[ProfileEngine]
 AE[ActionExecutor]
 DM[DeviceModel]
 BM[ButtonModel]
 AM[ActionModel]
 PM[ProfileModel]
 end
 subgraph "Injected (or created)"
 Desktop[IDesktopIntegration]
 Injector[IInputInjector]
 end
 subgraph "Signal Connections (wireSignals)"
 S1["ButtonModel::userActionChanged -> onUserButtonChanged"]
 S2["IDesktopIntegration::activeWindowChanged -> onWindowFocusChanged"]
 S3["ProfileModel::profileSwitched -> onTabSwitched"]
 S4["ProfileEngine::displayProfileChanged -> onDisplayProfileChanged"]
 S5["DeviceManager::deviceSetupComplete -> onDeviceSetupComplete"]
 S6["DeviceModel::userGestureChanged -> saveCurrentProfile"]
 S7["ProfileModel::profileAdded -> ProfileEngine::createProfileForApp"]
 S8["ProfileModel::profileRemoved -> ProfileEngine::removeAppProfile"]
 S9["DeviceManager::gestureRawXY -> onGestureRawXY"]
 S10["DeviceManager::divertedButtonPressed -> onDivertedButtonPressed"]
 S11["DeviceManager::thumbWheelRotation -> onThumbWheelRotation"]
 S12["DeviceModel::dpiChangeRequested -> onDpiChangeRequested"]
 S13["DeviceModel::smartShiftChangeRequested -> onSmartShiftChangeRequested"]
 S14["DeviceModel::scrollConfigChangeRequested -> onScrollConfigChangeRequested"]
 S15["DeviceModel::thumbWheelModeChangeRequested -> onThumbWheelModeChangeRequested"]
 S16["DeviceModel::thumbWheelInvertChangeRequested -> onThumbWheelInvertChangeRequested"]
 end