chanora/docs/architecture/desktop-ptt-architecture.md

Desktop Push-to-Talk Architecture

Field	Value
Document type	Architecture
Version	0.9.3
Status	Baseline Candidate
Language	English
Product	Chanora
Date	2026-05-15

Owner-resolved review questions from gen2/chanora-desktop-ptt-review-summary-v0.9.2.md are recorded as DEC-023 through DEC-028 in docs/governance/product-decision-register.md.

---

1. Purpose

Desktop Push-to-Talk (PTT) is the operation by which a user holds a bound keyboard key or mouse button to enable voice transmission and releases it to disable transmission. This document fixes the architecture so the product can describe, implement, verify, and release desktop PTT honestly — every capability claim made to the user is auditable against a live runtime measurement.

The previous architecture treated PTT as a single global behaviour. That over-promised on platforms where the operating system, the user-granted permission set, the display server, or the compositor does not permit unconditional global key capture. This document replaces that with a capability-based model.

2. Architectural Decisions

ID	Decision	Source
DEC-023	Windows Global PTT is P0 / MVP.	Owner ruling 2026-05-15
DEC-024	macOS Global PTT is P0 / MVP with explicit permission UX flow.	Owner ruling 2026-05-15
DEC-025	The officially-tested Linux environment for the first public release is GNOME on Wayland (only).	Owner ruling 2026-05-15
DEC-026	Mouse side buttons are supported in the first desktop PTT release on Windows and macOS; Linux support follows whatever the GlobalShortcuts portal exposes.	Owner ruling 2026-05-15
DEC-027	The diagnostic export carries capability and availability state only — no raw key codes, scan codes, or virtual-key values ever leave the device.	Owner ruling 2026-05-15
DEC-028	The missed-key-up watchdog is P0: the audio engine shall self-release transmit_active if the OS suppresses a key-up event.	Owner ruling 2026-05-15

3. Capability Ladder

Level	Name	Meaning
L0Focused	Focused PTT	PTT works only while the Chanora window has input focus. Mandatory on every desktop platform per SysRS-296.
L1GlobalShortcut	Global shortcut activation	The OS recognises a global accelerator and notifies the application, but hold-to-talk semantics may be approximated rather than guaranteed.
L2GlobalHoldToTalk	Global hold-to-talk	Press and release events are delivered while the application is not focused. The common Windows / macOS / GNOME-Wayland-portal MVP target.
L3GlobalWithMouseButtons	Global hold-to-talk plus mouse buttons	Includes mouse side buttons (Mouse4 / Mouse5).
L4DeviceAware	Device-aware PTT	Backend can distinguish specific input devices. Reserved. No MVP implementation produces L4DeviceAware.

The reported capability shall match runtime behaviour. A backend that could deliver L2GlobalHoldToTalk but lacks the user-granted permission shall report L0Focused until permission is granted.

4. Component Allocation

+------------------------------------+
| Flutter Voice UI                   |
|   PTT binding-capture sheet        |
|   VoiceBar PttCapabilityBadge      |
+---------------+--------------------+
                |
                |  set_binding(...)
                |  events_stream() -> BridgeEvent::PttCapability
                v
+---------------+--------------------+
| chanora_bridge                     |
|   typed DTOs, no key data crosses  |
+---------------+--------------------+
                |
                v
+------------------------------------+
| chanora_core                       |
|   PttController                    |
|     owns Box<dyn DesktopPttBackend>|
|     owns Arc<AudioTransmitGate>    |
|     publishes PttCapabilityLevel   |
|   MissedKeyUpWatchdog (tokio task) |
+---------------+--------------------+
                |
                v
+------------------------------------+
| chanora_audio                      |
|   DesktopPttBackend trait          |
|     WindowsRawInputBackend         |
|     WindowsHookBackend             |
|     MacOSEventTapBackend           |
|     LinuxGnomeWaylandBackend       |
|     FocusedPttBackend              |
|   AudioTransmitGate                |
|   capture_active / transmit_active |
+------------------------------------+
                |
                v
+------------------------------------+
| chanora_diagnostics                |
|   RedactingLogLayer                |
|   PttSanitizer (drops banned keys) |
+------------------------------------+

The audio engine reads transmit_active once per outbound Opus frame. No code path other than AudioTransmitGate::set flips the value.

5. Per-Platform Strategy

5.1 Windows

Three-level ladder evaluated once at audio-engine start:

1. WindowsRawInputBackend — preferred. Uses RegisterRawInputDevices with RIDEV_INPUTSINK to receive keyboard and mouse events even when Chanora is not focused. Runs a message-only window on its own OS thread so the WndProc is non-blocking. Reports L2GlobalHoldToTalk (keyboard) or L3GlobalWithMouseButtons (when a mouse side button is bound).
2. WindowsHookBackend — fallback. Installs WH_KEYBOARD_LL and WH_MOUSE_LL hooks on its own thread. Used when Raw Input registration fails (some constrained environments). Reports L2GlobalHoldToTalk / L3GlobalWithMouseButtons.
3. FocusedPttBackend — final fallback. Reports L0Focused.

The chosen rung is fixed for the lifetime of the audio engine; restart of the engine re-evaluates the ladder.

5.2 macOS

Two-level ladder with explicit permission gating:

1. MacOSEventTapBackend — preferred when Input Monitoring (or Accessibility, depending on macOS version) permission is Granted. Creates a CGEventTap on the main run loop, filtered to keyboard and mouse-button events. Reports L2GlobalHoldToTalk / L3GlobalWithMouseButtons.
2. FocusedPttBackend — fallback when permission is Denied, Undetermined, or revoked at runtime. Reports L0Focused.

The audio engine starts immediately on user request; the permission state is queried in parallel and the capability level is upgraded asynchronously through BridgeEvent::PttCapability if the user grants the permission. This avoids blocking voice functionality on a permission prompt.

5.3 Linux

Two-level ladder restricted to the officially-tested environment per DEC-025:

1. LinuxGnomeWaylandBackend — used when XDG_SESSION_TYPE=wayland and the desktop environment is GNOME, and the org.freedesktop.portal.GlobalShortcuts D-Bus interface is reachable. Calls CreateSession, BindShortcuts (delegates binding capture to the portal's own dialog), and listens for Activated / Deactivated signals. Reports L2GlobalHoldToTalk; mouse-button support follows whatever the portal exposes for the current session.
2. FocusedPttBackend — fallback on any other Linux environment (X11, sway, KDE, untested compositor, missing portal). Reports L0Focused.

Per DEC-025 the application does not claim Global PTT support on an untested Linux environment. The UI capability badge explicitly notes "Focused PTT — untested compositor for Global PTT" when the user runs Chanora outside GNOME-on-Wayland.

6. Privacy Rule

Per SysRS-302 and SRS-202:

• Raw key codes, scan codes, virtual-key values, keysyms, and key-press timing sequences shall not be logged, persisted, or included in any user-initiated diagnostic export.
• The PttSanitizer log-sink decorator enforces this at write time by inspecting field names and dropping records whose field names match a banned list (key_code, scan_code, virtual_key, vk, keysym, keysym_string, key_sequence). The check is structural — it does not rely on a content scan.
• The diagnostic export shall name only the capability level (PttCapabilityLevel::as_str()), the backend identifier (a fixed &'static str per implementation), and the bound input class ("keyboard", "mouse-side-button").

7. Audio Gate Rule

Per SRS-201:

• capture_active: AtomicBool is set by the audio engine on input-stream lifecycle transitions (stream opened or closed) and by the platform input-permission state. The PTT subsystem does not write capture_active.
• transmit_active: AtomicBool lives inside AudioTransmitGate. The Opus encoder feed reads it once per outbound frame; the gate is the only mutator path.
• A muted self-input (per set_input_muted) forces transmit_active to false regardless of the PTT subsystem's wish; this preserves the existing self-mute semantics.

8. Missed-Key-Up Watchdog

Per SRS-203 / DEC-028:

• The audio engine spawns one MissedKeyUpWatchdog task per audio session.
• It subscribes to AudioTransmitGate's watch::Receiver<bool> and notes the timestamp of each false -> true transition.
• On each true -> false transition it clears the timestamp.
• If a true lifetime exceeds the configured ceiling (default 30 s, owner-tunable through a future setting), the watchdog calls AudioTransmitGate::set(false) and emits a sanitised diagnostic line naming only the capability level and backend identifier.

9. Release Readiness

Per SysDes-148 and the release-readiness record:

• Every release artefact carries a per-platform capability-evidence row listing the detected PttCapabilityLevel, the active backend identifier, and whether the Focused fallback was exercised during verification.
• Release notes shall mirror that evidence and shall not over-claim Global PTT support.

10. Traceability

SysRS-296..302
  -> SysDes-142..148
  -> SRS-195..203
  -> SAD-071..079
  -> SDD-081..092

Verification coverage:

SDD-081..092 -> SWE4-UV-035..039
SAD-071..079 + SDD-081..092 -> SWE5-IV-015
SRS-195..203 -> SWE6-SV-017
SysDes-142..148 -> SYS4-SIV-016

11. Change History

Version	Date	Description
0.9.3	2026-05-15	Initial baseline-candidate architecture for capability-based desktop Push-to-Talk. Codifies the owner rulings for PTT-OPEN-001 through PTT-OPEN-006 as DEC-023 through DEC-028.