DuckyDeck Studio — Architecture & Developer Reference (v0.1.4)

🏛️ 1. System Overview & Core Design Philosophy

🗺️ 2. High-Level System Architecture

DuckyDeck Studio is structured into four cleanly separated layers communicating across a thread-safe CXX-Qt bridge:

📂 3. Repository & Module Structure

🔗 4. CXX-Qt Concurrency Model & _GV31 Trigger Encoding

Because Qt GUI objects (QObject) have strict single-thread affinity on the Qt main event loop thread, src/bridge/device_controller.rs separates state into Qt-thread-owned fields and thread-safe shared registries:

• Qt-Thread Owned State (DeviceControllerRust): Holds profiles: Vec<DuckyProfile> (up to 64 profiles), sd_root_path: Option<PathBuf>, and copied_slot: Option<DuckyKeySlot>.
• Thread-Safe Shared State (Arc<Mutex<...>> / Atomics): Holds switcher_state, WEB_API_REGISTRY, WEB_API_PGV_REGISTRY, APP_LAUNCH_FKEY_REGISTRY, APP_LAUNCH_PGV_REGISTRY, and SYSTEM_EVENT_LOG.
• Cross-Thread UI Updates (CxxQtThread): Background worker threads never mutate QProperty values directly; they capture let qt_thread = self.qt_thread(); and queue closures onto the Qt event loop via qt_thread.queue(move |mut qobject| { ... }).

Unified _GV31 Hardware-to-Host Trigger Word

Both Web API (// @DUCKYDECK_WEBAPI) and Desktop Application Launch (// @DUCKYDECK_APPLAUNCH) scripts in pgv trigger mode write a 32-bit magic word into Persistent Global Variable _GV31 (PGV_TRIGGER_INDEX = 31):

// 32-bit _GV31 Trigger Word Layout:
// Bits 16..31 : 0x5741 ("WA" magic header)
// Bit  15     : is_release (0 = On Press, 1 = On Release)
// Bits 8..14  : profile_num (1..64)
// Bits 0..7   : slot_num (1..58)
pub fn encode_pgv31_trigger(profile_num: u8, slot_num: u8, is_release: bool) -> u32 {
    let rel_bit = if is_release { 0x8000 } else { 0 };
    0x5741_0000 | rel_bit | ((profile_num as u32 & 0x7F) << 8) | (slot_num as u32)
}

When the background USB HID poller reads _GV0.._GV31 via command 0x18 (HID_CMD_DUMP_PGV) and detects a non-zero _GV31 matching decode_pgv31_trigger, it immediately writes _GV31 = 0 via command 0x19 (HID_CMD_WRITE_PGV) to re-arm the trigger and dispatches the matching WEB_API_PGV_REGISTRY or APP_LAUNCH_PGV_REGISTRY action on the Linux host.

🔌 5. USB HID Protocol, USB Mass Storage & Flatpak Host Bridge

5.1 64-Byte USB HID Report Protocol (src/hardware/storage.rs)

The duckyPad Pro (0x0483:0xd11d) and duckyPad 2020 (0x0483:0xd11c) communicate over a 64-byte vendor-defined USB HID interface (HID_REPORT_ID_OUT = 0x05):

5.2 USB Mass Storage (MSC) Mounting & Flatpak Host Command Bridging (src/hardware/msc.rs)

When reading or writing profiles or staging firmware on a duckyPad Pro, DuckyDeck Studio sends HID command 0x14 (tx[3] = 1) to enumerate the microSD card as a TinyUSB Mass Storage block device (/dev/disk/by-label/DP24_* or /dev/disk/by-id/*TinyUSB_Flash_Storage*), mounts the FAT32 partition via udisksctl mount --no-user-interaction -b /dev/sdX1, performs SHA-256 read-back verification, flushes buffers via sync, unmounts cleanly via udisksctl unmount, and reboots back into HID mode (0x14, tx[3] = 0).

⚙️ 6. DSVM v2 Bytecode Compiler (src/vm/compiler.rs)

The duckyPad Pro executes compiled DSVM v2 (.dsb) stack-machine bytecode binaries rather than interpreting raw text on-device. src/vm/compiler.rs implements a complete two-pass compiler in pure Rust:

🪟 7. Wayland Auto-Switcher, Session D-Bus IPC & Rule Invariants

On KDE Plasma 6 Wayland, DuckyDeck Studio registers the session D-Bus service io.github.duckydeck.Studio at object path /KWinBridge (interface io.github.duckydeck.KWinBridge) via zbus:

• ReportActiveWindow(window_class: &str, window_title: &str): Invoked by the dynamically injected KWin 6 JavaScript hook (duckydeck-kwin6-hook.js) whenever the active Wayland window changes; evaluates AutoSwitchRule entries and switches the duckyPad profile over USB HID unless paused while the script editor is open.
• ReportPickedWindow(window_class: &str, window_title: &str): Invoked when the user clicks a window using the interactive KWin crosshair picker.
• DispatchIpcCommand(command: &str) -> u32: Handles single-instance activation, system tray actions, and CLI remote control (show, show-about, minimize, toggle, quit, toggle-oled-widget, switch-profile:<n>, trigger-fkey:<F13..F24>).

Profile Fallback & Auto-Switcher Synchronization Invariants

• Default Fallback Profile Guarantee: Whenever a new profile group is created or loaded, if no profiles exist, Profile #1 ("Default") is automatically created and marked as the fallback_profile.
• Non-Deletable Fallback Profile: delete_profile rejects deletion of the currently configured fallback_profile so unmatched windows and reassigned rules always have a valid target.
• Automatic Rule Remapping on Reorder & Delete: Reordering profiles (remap_rules_on_profile_reorder) atomically updates fallback_profile and every rule's target profile number/name. Deleting a profile (remap_rules_on_profile_delete) shifts higher indices down by 1 and reassigns any rule referencing the deleted profile to the fallback_profile.

First-Run Deck Setup, Legacy Migration & Conflict Resolution

• Conflicting Process Detection: Detects legacy background processes (duckypad_autoprofile.py, duckypad_autoswitcher, duckypad_configurator) via /proc and host process inspection, offering one-click graceful shutdown to prevent USB HID bus contention.
• Profile & Rule Discovery: Discovers profiles from the deck microSD, local cache, and legacy dekuNukem backups in ~/.local/share/duckypad_config/profile_backups/ (src/hardware/profile.rs). Discovers rules from microSD duckydeck_rules.json, local rules, and legacy auto-switcher files in ~/.local/share/duckypad_autoswitcher/ (src/kwin/auto_switcher.rs).
• Portable SD Rules Bundle: duckydeck_rules.json on the microSD card syncs auto-switcher rules alongside hardware profiles, enabling instant cross-machine rule portability.
• Onboarding State Tracking: Persists completion in first_run_onboarding_state.json across local and host configs.

🎨 8. Keycap Layout, OLED Desktop Widget & Automated UI Verification

Automated Scene-Graph UI Test Suite (Native & Flatpak)

src/qml/EventLogDialog.qml and src/main.rs include a comprehensive automated UI verification harness (--ui-test-suite) that walks every window, drawer, and modal across both Dark Mode and Light Mode at 100% and 115% zoom levels, auditing:

• Zero Overflow & Overlap Violations: Audits 160+ keycap instances and all text labels for truncation or sibling bounding-box collisions.
• WCAG Contrast & High-Contrast Controls: Verifies text/background contrast ratios, HighContrastCheckBox border luminance, and 40+ HighContrastScrollBar instances.
• 12 Behavioral Invariants: Verifies profile group creation, non-deletable fallback protection, profile reorder/delete rule remapping, Escape-key modal dismissal, zoom persistence, and bundled DuckyDeck Studio custom firmware catalog presence (duckydeck_studio_firmware_available_in_catalog).

💾 9. Persistence, Credentials & Hardware Portability

🌐 9.7 Embedded HTTP REST API Server (src/api_server.rs)

DuckyDeck Studio embeds a bounded, stoppable/restartable HTTP/1.1 REST API server (src/api_server.rs and src/bridge/rest_routes.rs):

• Default Security Posture: Disabled by default (rest_api_enabled = false), bound to loopback 127.0.0.1:28491, with constant-time Bearer Token authentication (ddk_<40 hex chars> stored in OS keyring).
• Resource Bounds: Capped at MAX_CONCURRENT_CONNECTIONS = 8 (returning 503 Service Unavailable when full) and MAX_BODY_BYTES = 2 MB (returning 413 Payload Too Large).
• Async Worker Jobs (202 Accepted): Long-running hardware operations (/api/v1/sd/sync, /api/v1/sd/mount, /api/v1/sd/unmount, /api/v1/device/reboot) return 202 Accepted with a job ID pollable via GET /api/v1/jobs/{id}.
• Interactive Documentation: Full OpenAPI 3.0.3 & Swagger 2.0 specs are served at /api/v1/openapi.yaml, /api/v1/openapi.json, and /api/v1/swagger.json (and documented in REST_API.md).

📦 10. Flatpak Sandbox Architecture & Packaging

DuckyDeck Studio is packaged as a self-contained Flatpak bundle (io.github.duckydeck.Studio) built against org.kde.Platform//6.11 and org.kde.Sdk//6.11 (configured in io.github.duckydeck.Studio.yml and scripts/build-flatpak.sh).

Download, Install & Run the Flatpak

# Download & install the latest Flatpak bundle directly:
curl -LO https://duckydeckstudio.com/releases/duckydeck-studio-v0.1.4-x86_64.flatpak
flatpak install --user -y duckydeck-studio-v0.1.4-x86_64.flatpak

# Launch GUI:
flatpak run io.github.duckydeck.Studio

# Run CLI commands inside Flatpak:
flatpak run io.github.duckydeck.Studio --status

🛠️ 11. Building, Testing & Extending

# 1. Run formatting, clippy (-D warnings), unit tests, and architecture path checks:
bash scripts/check.sh

# 2. Run the Native QML UI Overflow, Contrast & Behavioral Test Suite:
cargo test ui_test_suite::test_full_qml_ui_overflow_and_contrast_suite -- --ignored --nocapture

# 3. Build & install the Flatpak bundle from source:
bash scripts/build-flatpak.sh
flatpak install --user -y --reinstall target/release/duckydeck-studio-v0.1.4-x86_64.flatpak

# 4. Run the Flatpak QML UI Test Suite inside the Flatpak sandbox:
bash scripts/test-flatpak-ui.sh