Developer Guide

Developer guide

The user guide is the wiki's primary purpose. These notes provide an entry point for contributors without replacing the repository's source-controlled technical documentation.

Prerequisites

• Rust 1.88.0 with rustfmt and clippy.
• Node.js 22.
• pnpm 11.
• Platform build tools required by Tauri.

Install frontend dependencies and start the desktop app with:

pnpm --dir ui install
cargo tauri dev

Run the complete local verification suite with:

pnpm run ci:all

Local environment

Copy .env.example to .env.development when local validation needs environment-specific values. The repository's local scripts load that file before running pnpm and Rust commands while preserving variables already exported by the shell.

Never commit .env.development, credentials, certificates, or private keys.

Ubuntu development

For Ubuntu development, install Tauri's desktop build dependencies and pulseaudio-utils for the PulseAudio-compatible pactl interface:

sudo apt install libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev pulseaudio-utils

The audio adapter works with PulseAudio or PipeWire's pipewire-pulse service. Installed applications also require pulseaudio-utils at runtime.

Repository layout

Path	Responsibility
crates/domain	Validated values, mappings, confirmed state, and pending intent
crates/synchronization	Platform-neutral state machine and side effects
crates/integration	Coordinator, serialization, and command coalescing
crates/sonos	SSDP, device descriptions, SOAP control, and GENA events
crates/platform-audio	Windows Core Audio, macOS Core Audio, and Ubuntu PulseAudio-compatible adapters
crates/test-support	Local Sonos mock server and fixtures
src-tauri	Application composition, configuration, runtime, tray, and commands
ui	Settings interface and frontend tests
docs	Architecture decisions, protocol notes, verification, and release details

Contribution workflow

The application repository uses Gitflow. Create focused feat/, fix/, or chore/ branches from current develop, and target pull requests to develop. Keep main stable for completed releases.

For behavior changes:

• Add or update tests.
• Keep domain and synchronization crates independent of Tauri, OS APIs, and networking.
• Keep platform and protocol details in their adapters.
• Run the complete validation suite.
• Record hardware-specific behavior as unverified until it is tested on the actual platform and device.

Public issues and pull requests must not contain credentials, local paths, network addresses, device identifiers, raw logs, diagnostic payloads, or other sensitive environment details.

Useful source documentation at v1.3.3

• Documentation index
• Architecture
• How it works
• Development
• State machine
• Sonos local protocol
• Architecture decisions
• Verification matrix
• Release process