edison/chanora
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f3320715ea84c86df1fbc5cd85ca05df1ecac8f2
chanora/docs/architecture/sdd.md
T
EdisonJwa dfa84ee7bb docs(spec): baseline 0.9.5 — v1 audio + PTT lifecycle redesign 
Add SysRS-303/304, SysDes-149/150/151, SRS-204/205/206/207,
SAD-081/082/083, SDD-094/095/096/097, DEC-029/030.

Captures the v1 lifecycle redesign:
- Drop manual Start-audio button; audio engine is bound to voice-channel
  join/leave (ensure_running on first join, shutdown_if_idle on last
  leave). Output stream opens regardless of mic-permission state so
  listen-only is a first-class flow.
- TransmitMode enum (Ptt / Continuous / VoiceActivity-reserved).
  Default Ptt on fresh install. Persisted per identity.
- PTT release tail: 200 ms default (0-500 ms configurable) before
  transmit gate closes, avoiding clipped trailing syllables.
- Hard-mute toggle overrides transmit gate regardless of mode/PTT.
- Bridge surface: drop start_audio/stop_audio; add
  voice_join(channel_id) / voice_leave() and BridgeEvent::VoiceState.

DEC-029 rejects Flutter global-hotkey packages (hotkey_manager,
super_hot_key) for PTT: they wrap RegisterHotKey/RegisterEventHotKey
which consume the key and don't fire key-up, wrong primitive for PTT.
Native Rust DesktopPttBackend (SDD-083/084/085) stays authoritative.

DEC-030 defers Voice Activity Detection to P1. RMS / WebRTC VAD /
Silero VAD trade-off review (binary-size, dependency-surface, CPU
profile) postponed; TransmitMode::VoiceActivity reserved on the enum
surface so a P1 increment is non-breaking.

Validator clean: 304/151/207/83/97 IDs, strict layered sourcing
preserved, no new warnings beyond the pre-existing 35 old-package-name
filenames.
2026-05-15 22:46:51 +08:00

1205 lines
52 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Chanora SDD — Software Detailed Design
**Document type:** SDD / Software Detailed Design
**Process alignment:** ASPICE SWE.3 Software Detailed Design and Unit Construction
**Version:** 0.9.2
**Status:** Baseline Candidate
**Language:** English
**Product:** Chanora
**Lifecycle position:** `SysRS -> SysDes -> SRS -> SAD -> SDD`
**Repo path:** `docs/architecture/sdd.md` ---
## 1. Purpose
This document defines detailed software design units, APIs, data structures, and implementation-level design rules for Chanora.
The SDD derives from the SAD only.
## 2. Strict Traceability Rules
```text
SDD shall link directly to SAD only.
SDD shall not use direct software-requirement source IDs.
SDD shall not use direct system-design source IDs.
SDD shall not use direct system-requirement source IDs.
```
## 3. Software Unit Decomposition
| Software Unit | Responsibility |
|---|---|
| `ChanoraApp` | Root application widget, initialization, theme mode, localization initialization |
| `ChanoraThemeFactory` | Builds ThemeData, ColorScheme, TextTheme, component themes |
| `ChanoraSemanticColors` | ThemeExtension for connection, voice, latency, diagnostic, and error states |
| `ChanoraSpacing` | ThemeExtension for spacing tokens |
| `ChanoraShape` | ThemeExtension for shape tokens |
| `ChanoraMotion` | ThemeExtension for motion tokens and reduced-motion behavior |
| `ChanoraAdaptiveShell` | Window class detection and shell layout selection |
| `CompactShell` | Single-column shell |
| `MediumShell` | Navigation rail / medium-width shell |
| `ExpandedShell` | Persistent pane shell |
| `ChanoraVoiceBar` | Persistent voice control component |
| `ChanoraChannelTree` | Hierarchical channel and client browser |
| `ChanoraClientTile` | Client row component |
| `ChanoraStatusBadge` | Accessible status indicator |
| `ChanoraAudioMeter` | Input level display |
| `LocalizationService` | Product-owned string localization and fallback |
| `ContentTextAdapter` | Server-provided text pass-through and display preparation |
| `UnicodeTextBoundary` | Boundary string validation and conversion helper |
| `PlatformInsetsService` | Safe area, keyboard, cutout, and desktop inset data |
| `BackIntentService` | Android/system back intent abstraction |
| `HapticsService` | Platform-aware haptic feedback wrapper |
| `BridgeFacade` | Flutter-to-Rust command and event facade |
| `CoreEventMapper` | Core-event-to-view-model mapping |
| `DiagnosticsTextPresenter` | Localized diagnostic descriptions and language-neutral event keys |
| `ArchitectureViewDocs` | Maintains context, container, component, runtime, deployment, and ADR architecture documentation |
| `DeploymentConfig` | Platform packaging and release configuration |
| `ArchitectureTraceChecker` | Checks direct-layer traceability rules for documentation |
## 4. SWE.3 Detailed Design Completeness Criteria
The detailed design shall be sufficient to support implementation and unit verification. For each software unit, the SDD shall identify where applicable:
| Detail | Required information |
|---|---|
| Unit responsibility | Purpose and boundaries of the unit |
| Inputs | Name, type, allowed range, default value, optionality |
| Outputs | Name, type, allowed range, default value, error behavior |
| Interfaces | Internal and external software interfaces |
| Dynamic behavior | State changes, sequence behavior, asynchronous behavior |
| Error behavior | Recoverable errors, fatal errors, fallback behavior |
| Resource behavior | Buffering, time-sensitive operations, memory expectations |
| Unit verification hooks | Test seams and expected verification approach |
## 5. Software Unit Interface Detail Catalog
| Unit | Interface | Direction | Name | Type | Unit | Resolution | Range | Default | Error / fallback |
|---|---|---:|---|---|---|---|---|---|---|
| `ChanoraThemeFactory` | Theme creation | Input | seedColor | Color value | n/a | n/a | valid color | Chanora default seed | fallback to default theme |
| `ChanoraThemeFactory` | Theme creation | Input | brightness | enum | n/a | n/a | light/dark | system setting | fallback to light |
| `ChanoraThemeFactory` | Theme creation | Output | themeData | ThemeData | n/a | n/a | valid ThemeData | n/a | construction error treated as app initialization failure |
| `ChanoraAdaptiveShell` | Window classification | Input | widthDp | double | dp | 1dp | >=0 | current window width | compact fallback |
| `ChanoraAdaptiveShell` | Window classification | Output | windowClass | enum | n/a | n/a | compact/medium/expanded | compact | compact fallback |
| `LocalizationService` | String lookup | Input | key | string | n/a | n/a | non-empty | n/a | fallback key display or English fallback |
| `LocalizationService` | String lookup | Input | locale | locale ID | n/a | n/a | supported locale | English | English fallback |
| `LocalizationService` | String lookup | Output | localizedText | UTF-8 string | n/a | n/a | valid Unicode | English fallback | missing-key diagnostic |
| `UnicodeTextBoundary` | Text validation | Input | rawText | external string/bytes | n/a | n/a | platform/protocol dependent | n/a | boundary conversion error |
| `UnicodeTextBoundary` | Text validation | Output | contentText | UTF-8 string | n/a | n/a | valid Unicode | replacement/failure policy | conversion diagnostic |
| `BridgeFacade` | Command bridge | Input | commandDto | DTO | n/a | n/a | valid command schema | n/a | bridge error DTO |
| `BridgeFacade` | Command bridge | Output | commandResult | DTO/result | n/a | n/a | success/error | n/a | typed error |
| `CoreEventMapper` | Event mapping | Input | coreEvent | event DTO | n/a | n/a | known event type | n/a | unknown event diagnostic |
| `CoreEventMapper` | Event mapping | Output | viewModelDelta | UI model delta | n/a | n/a | valid UI state change | n/a | safe no-op + diagnostic |
| `DiagnosticsTextPresenter` | Diagnostic presentation | Input | diagnosticKey | stable key | n/a | n/a | known/unknown key | n/a | generic localized fallback |
| `DiagnosticsTextPresenter` | Diagnostic presentation | Output | diagnosticText | localized string | n/a | n/a | valid Unicode | English fallback | fallback diagnostic text |
| `ChanoraAudioMeter` | Level display | Input | level | double | normalized | 0.01 | 0.0-1.0 | 0.0 | clamp to valid range |
| `ChanoraAudioMeter` | Level display | Output | semanticValue | localized string | n/a | n/a | valid string | "No input" | localized fallback |
| `BackIntentService` | Back handling | Input | platformBackEvent | platform event | n/a | n/a | platform-defined | n/a | ignored if unsupported |
| `BackIntentService` | Back handling | Output | backIntent | enum | n/a | n/a | pop/close/ignore/exitCandidate | ignore | safe no-op |
## 6. Detailed Design Evaluation Checklist
| Evaluation area | Question |
|---|---|
| Interoperability | Are interfaces compatible across units and layers? |
| Interaction | Are runtime interactions and asynchronous flows defined? |
| Criticality | Are critical voice, connection, security, and diagnostics behaviors detailed? |
| Technical complexity | Are complex units decomposed and testable? |
| Risks | Are platform, audio, protocol, encoding, and localization risks addressed? |
| Testability | Can unit tests, widget tests, integration tests, and platform tests be derived from the design? |
| Traceability | Does every detailed item link directly to SAD only? |
| Consistency | Are SAD, SDD, unit interfaces, and verification expectations consistent? |
## 7. Detailed Design Items
**SDD-001**: `ChanoraApp` shall initialize theme, localization, platform services, and routing before rendering feature content.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `ChanoraApp`
- Source SAD: SAD-001, SAD-031
- Verification method: Unit Test, Integration Test
Initialization order: platform bindings -> localization resources -> theme model -> app router -> adaptive shell.
**SDD-002**: `ChanoraThemeFactory` shall create Material 3 ThemeData for light and dark modes.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `ChanoraThemeFactory`
- Source SAD: SAD-001, SAD-002, SAD-043
- Verification method: Unit Test
The factory returns ThemeData instances with Material 3 enabled and populated ColorScheme and TextTheme values.
**SDD-003**: `ChanoraThemeFactory` shall support seed-color replacement without feature-screen changes.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `ChanoraThemeFactory`
- Source SAD: SAD-001, SAD-002, SAD-044
- Verification method: Unit Test
Seed color is injected into theme construction and not referenced in feature modules.
**SDD-004**: `ChanoraSemanticColors` shall define connection state colors independently from base ColorScheme.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `ChanoraSemanticColors`
- Source SAD: SAD-004, SAD-007
- Verification method: Unit Test
Connection tokens include connected, connecting, reconnecting, disconnected, and error roles.
**SDD-005**: `ChanoraSemanticColors` shall define voice state colors independently from base ColorScheme.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `ChanoraSemanticColors`
- Source SAD: SAD-005, SAD-007
- Verification method: Unit Test
Voice tokens include speaking, muted, deafened, push-to-talk-active, and unavailable roles.
**SDD-006**: `ChanoraSemanticColors` shall define latency, packet-loss, diagnostics, and error semantic roles.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `ChanoraSemanticColors`
- Source SAD: SAD-006, SAD-007
- Verification method: Unit Test
Token names remain semantic and shall not embed raw color names in API names.
**SDD-007**: `ChanoraSpacing` shall define reusable spacing values for compact, medium, and expanded layouts.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `ChanoraSpacing`
- Source SAD: SAD-002, SAD-003
- Verification method: Unit Test
Spacing APIs expose xs, sm, md, lg, xl, and xxl values.
**SDD-008**: `ChanoraShape` shall define reusable corner and shape values for cards, buttons, panels, badges, and sheets.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `ChanoraShape`
- Source SAD: SAD-002, SAD-003
- Verification method: Unit Test
Shape APIs expose none, small, medium, large, extraLarge, and full values.
**SDD-009**: `ChanoraMotion` shall define standard durations and reduced-motion behavior.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `ChanoraMotion`
- Source SAD: SAD-009
- Verification method: Unit Test
The unit maps reduced-motion settings to no-motion or simplified-motion behavior.
**SDD-010**: Feature widgets shall read tokens through Flutter theme accessors only.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `Feature Widgets`
- Source SAD: SAD-003, SAD-007
- Verification method: Static Inspection
Feature code may call Theme.of(context) and extension accessors, but shall not instantiate semantic tokens.
**SDD-011**: `ChanoraAdaptiveShell` shall classify window width into compact, medium, or expanded.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `ChanoraAdaptiveShell`
- Source SAD: SAD-008
- Verification method: Unit Test
Classification thresholds are centralized in the shell configuration.
**SDD-012**: `ChanoraAdaptiveShell` shall dispatch to `CompactShell`, `MediumShell`, or `ExpandedShell`.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `ChanoraAdaptiveShell`
- Source SAD: SAD-008, SAD-009, SAD-010, SAD-011
- Verification method: Widget Test
Layout selection shall be deterministic for a given window class.
**SDD-013**: `CompactShell` shall render single-column content and mobile navigation.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `CompactShell`
- Source SAD: SAD-009
- Verification method: Widget Test
Compact layout shall avoid side-by-side pane requirements.
**SDD-014**: `MediumShell` shall render side navigation or navigation rail behavior.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `MediumShell`
- Source SAD: SAD-010
- Verification method: Widget Test
Medium layout shall preserve main content and primary navigation.
**SDD-015**: `ExpandedShell` shall render persistent pane regions and persistent voice controls.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `ExpandedShell`
- Source SAD: SAD-011
- Verification method: Widget Test
Expanded layout shall support a side pane, main pane, and persistent VoiceBar slot.
**SDD-016**: `ConnectionStatusPresenter` shall provide non-color-only connection state presentation data.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `ConnectionStatusPresenter`
- Source SAD: SAD-012, SAD-014
- Verification method: Unit Test
The presenter returns label, icon, severity token, and accessibility description.
**SDD-017**: `ChanoraVoiceBar` shall expose mute, deaf, push-to-talk, input meter, current channel, and latency properties.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `ChanoraVoiceBar`
- Source SAD: SAD-013
- Verification method: Widget Test
VoiceBar properties are supplied from view models and shall not call Rust Core directly.
**SDD-018**: `ChanoraVoiceBar` shall remain renderable as a persistent shell slot.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `ChanoraVoiceBar`
- Source SAD: SAD-007, SAD-013
- Verification method: Widget Test
The component shall not depend on a specific route.
**SDD-019**: `ChanoraChannelTree` shall support hierarchical channel nodes and client rows.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `ChanoraChannelTree`
- Source SAD: SAD-003, SAD-006
- Verification method: Widget Test
The component consumes ChannelTreeVm data and supports expansion state.
**SDD-020**: `ChanoraChannelTree` shall support selected state, expansion state, join intent, and context-menu intent.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `ChanoraChannelTree`
- Source SAD: SAD-006, SAD-015
- Verification method: Widget Test
UI events are emitted through callbacks and view-model intents.
**SDD-021**: `ChanoraClientTile` shall display client status with text, icon, and semantic state cues.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `ChanoraClientTile`
- Source SAD: SAD-003, SAD-014
- Verification method: Widget Test, Accessibility Test
Client state shall not rely on color alone.
**SDD-022**: `ChanoraStatusBadge` shall expose visible text or icon and accessibility semantics.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `ChanoraStatusBadge`
- Source SAD: SAD-012, SAD-014
- Verification method: Widget Test, Accessibility Test
Badge states include normal, warning, error, speaking, muted, and disconnected.
**SDD-023**: `ChanoraAudioMeter` shall display audio input level and support reduced-motion fallback.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `ChanoraAudioMeter`
- Source SAD: SAD-009, SAD-013
- Verification method: Widget Test
Reduced-motion mode shall use simplified or static visual behavior.
**SDD-024**: All icon-only buttons shall provide localized semantic labels.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `Design System Components`
- Source SAD: SAD-014, SAD-020
- Verification method: Accessibility Test
Icon-only control constructors require label keys or semantic labels.
**SDD-025**: Focusable components shall define focus order and visible focus style.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `FocusPolicy`
- Source SAD: SAD-015
- Verification method: Widget Test
Focus traversal shall be testable with keyboard navigation.
**SDD-026**: Adaptive shell panes shall support increased text scale without losing critical actions.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `Adaptive Shell Components`
- Source SAD: SAD-016
- Verification method: Accessibility Test
Critical controls shall wrap, scroll, or remain reachable.
**SDD-027**: `PlatformInsetsService` shall provide safe area, keyboard inset, display cutout, and desktop inset data.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `PlatformInsetsService`
- Source SAD: SAD-017
- Verification method: Platform Test
Insets are consumed by shell layout rather than individual feature screens.
**SDD-028**: `BackIntentService` shall normalize Android/system back behavior into route-level intents.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `BackIntentService`
- Source SAD: SAD-018
- Verification method: Platform Test
Back handling shall be testable without direct platform branching in feature screens.
**SDD-029**: `HapticsService` shall expose platform-aware haptic feedback operations.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `HapticsService`
- Source SAD: SAD-019
- Verification method: Platform Test
Haptics calls are optional and shall no-op where unsupported.
**SDD-030**: `KeyboardAvoidancePolicy` shall prevent critical controls from being covered by virtual keyboards.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `KeyboardAvoidancePolicy`
- Source SAD: SAD-017, SAD-019
- Verification method: Platform Test
Inputs and primary actions remain reachable when the virtual keyboard appears.
**SDD-031**: `LocalizationService` shall load product string resources for the active locale.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `LocalizationService`
- Source SAD: SAD-020
- Verification method: Unit Test
The unit returns localized strings by key.
**SDD-032**: `LocalizationService` shall fall back to the baseline English locale when a key is missing.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `LocalizationService`
- Source SAD: SAD-020
- Verification method: Unit Test
Fallback behavior is deterministic and logged for diagnostics.
**SDD-033**: `LocalizationService` shall allow new locale resources without changes to protocol, audio, state, or storage modules.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `LocalizationService`
- Source SAD: SAD-020
- Verification method: Inspection
Locale resource registration is separated from non-UI software modules.
**SDD-034**: `ContentTextAdapter` shall pass through server-provided names and messages without translation.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `ContentTextAdapter`
- Source SAD: SAD-021
- Verification method: Integration Test
Server content is treated as user/server content rather than product copy.
**SDD-035**: `UnicodeTextBoundary` shall validate cross-layer text DTOs as UTF-8 compatible strings.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `UnicodeTextBoundary`
- Source SAD: SAD-022, SAD-023
- Verification method: Unit Test, Integration Test
Invalid external encodings are handled at boundaries.
**SDD-036**: Protocol-boundary conversion shall be implemented only in protocol adapter code.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `Protocol Adapter Text Boundary`
- Source SAD: SAD-023
- Verification method: Inspection
No general Flutter feature code may perform protocol encoding conversion.
**SDD-037**: Platform-boundary conversion shall be implemented only in platform adapter code.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `Platform Adapter Text Boundary`
- Source SAD: SAD-023
- Verification method: Inspection
Platform-specific string conversion remains explicit and localized.
**SDD-038**: Diagnostics export shall preserve Unicode after redaction.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `DiagnosticsTextPresenter`
- Source SAD: SAD-024
- Verification method: Test, Audit
Redaction removes secrets, not arbitrary multilingual content.
**SDD-039**: Bidi text rendering shall use Flutter text widgets and directionality behavior compatible with platform support.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `Flutter Text Presentation`
- Source SAD: SAD-025
- Verification method: Localization Test
Text rendering allows LTR and RTL content where supported.
**SDD-040**: Locale-aware formatting shall be centralized in localization utilities.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `LocalizationFormatting`
- Source SAD: SAD-026
- Verification method: Unit Test
Dates, times, numbers, and timestamps are formatted by locale-aware helpers.
**SDD-041**: Diagnostics event keys shall remain stable and language-neutral.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `DiagnosticsTextPresenter`
- Source SAD: SAD-027
- Verification method: Unit Test
User-facing descriptions are separate from machine-readable event keys.
**SDD-042**: UI/UX supporting documents shall be versioned with the software architecture baseline.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `Documentation Set`
- Source SAD: SAD-028
- Verification method: Review
Guidelines, token docs, component docs, adaptive docs, and platform docs are maintained as supporting baselines.
**SDD-043**: SAD source validation shall reject direct lower-layer source fields.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `Traceability Checker`
- Source SAD: SAD-029
- Verification method: Inspection
Automated or manual review checks SAD source fields.
**SDD-044**: SDD source validation shall reject direct non-SAD source fields.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `Traceability Checker`
- Source SAD: SAD-030, SAD-045
- Verification method: Inspection
Automated or manual review checks SDD source fields.
**SDD-045**: Theme/localization/platform initialization shall be tested before first feature render.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `App Initialization Tests`
- Source SAD: SAD-031
- Verification method: Integration Test
The app shell is tested for initialization order.
**SDD-046**: Bridge facade DTOs shall expose only stable UI-safe data structures.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `BridgeFacade`
- Source SAD: SAD-040, SAD-041
- Verification method: Integration Test
Flutter must not depend on Rust internal types.
**SDD-047**: Core event mapping shall convert Rust Core events into feature view models.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `CoreEventMapper`
- Source SAD: SAD-041
- Verification method: Unit Test
Event mapping is deterministic and testable.
**SDD-048**: Audio state view models shall separate UI state from real-time audio processing.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `VoiceViewModel`
- Source SAD: SAD-034, SAD-039
- Verification method: Unit Test
Voice UI receives status values without performing DSP.
**SDD-049**: Storage access shall be isolated from feature widgets behind repository or service APIs.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `StorageFacade`
- Source SAD: SAD-035
- Verification method: Inspection
Feature widgets shall not call database APIs directly.
**SDD-050**: Diagnostics UI shall obtain localized display text from diagnostics presentation services.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `DiagnosticsTextPresenter`
- Source SAD: SAD-027, SAD-036, SAD-050
- Verification method: Widget Test
Diagnostics UI consumes display models.
**SDD-051**: `ArchitectureViewDocs` shall maintain context, container, component, runtime, deployment, data, security, diagnostics, UI, audio, protocol, and i18n views.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P1 / Beta
- Software unit: `ArchitectureViewDocs`
- Source SAD: SAD-046, SAD-048, SAD-049, SAD-050
- Verification method: Review
Architecture views are updated when architecture-affecting changes occur.
**SDD-052**: `ArchitectureViewDocs` shall maintain an ADR index for accepted, deprecated, and superseded architectural decisions.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P1 / Beta
- Software unit: `ArchitectureViewDocs`
- Source SAD: SAD-047
- Verification method: Review
ADR entries include decision, rationale, status, and impact.
**SDD-053**: `DeploymentConfig` shall define platform-specific packaging and release configuration units.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P1 / Beta
- Software unit: `DeploymentConfig`
- Source SAD: SAD-049
- Verification method: Inspection
Deployment configuration separates platform package metadata from feature code.
**SDD-054**: `DiagnosticsArchitecture` shall centralize logging, event keys, localized descriptions, redaction, and export presentation.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P1 / Beta
- Software unit: `DiagnosticsArchitecture`
- Source SAD: SAD-050
- Verification method: Unit Test, Audit
Diagnostics behavior is implemented through centralized services.
**SDD-055**: `ArchitectureTraceChecker` shall check that SDD items reference only SAD IDs.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P1 / Beta
- Software unit: `ArchitectureTraceChecker`
- Source SAD: SAD-030, SAD-045
- Verification method: Inspection
A documentation check fails when non-SAD source IDs appear in SDD item source fields.
**SDD-056**: `ArchitectureTraceChecker` shall check that SAD items reference only SRS IDs.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P1 / Beta
- Software unit: `ArchitectureTraceChecker`
- Source SAD: SAD-029
- Verification method: Inspection
A documentation check fails when non-SRS source IDs appear in SAD item source fields.
**SDD-057**: `ArchitectureViewDocs` shall define reviewable architecture views for context, containers, components, runtime behavior, deployment, data, security, diagnostics, UI, audio, protocol, and i18n.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P1 / Beta
- Software unit: `ArchitectureViewDocs`
- Source SAD: SAD-046, SAD-051
- Verification method: Review
Each architecture view is maintained as part of the SAD baseline and referenced by the affected detailed design units.
**SDD-058**: `ArchitectureViewDocs` shall define an ADR record structure with ID, title, status, decision, rationale, consequences, affected units, and change history.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P1 / Beta
- Software unit: `ArchitectureViewDocs`
- Source SAD: SAD-047
- Verification method: Review
ADR records support architecture communication and change impact analysis.
**SDD-059**: `InterfaceDetailCatalog` shall refine SAD architectural interfaces into unit-level interface entries.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P1 / Beta
- Software unit: `InterfaceDetailCatalog`
- Source SAD: SAD-052, SAD-057
- Verification method: Inspection
Each entry includes name, type, unit, resolution, range, default value, and error/fallback behavior where applicable.
**SDD-060**: `InterfaceDetailCatalog` shall define command, event, localization, Unicode, diagnostics, adaptive layout, audio meter, and platform-intent interfaces.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P1 / Beta
- Software unit: `InterfaceDetailCatalog`
- Source SAD: SAD-052, SAD-056, SAD-057
- Verification method: Inspection
The catalog supports integration and unit verification planning.
**SDD-061**: `PerformanceDesignNotes` shall record UI responsiveness, audio latency, memory growth, reconnect, localization, and diagnostics resource considerations.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P1 / Beta
- Software unit: `PerformanceDesignNotes`
- Source SAD: SAD-053
- Verification method: Review, Analysis
Performance notes identify design mechanisms and verification hooks.
**SDD-062**: `AssumptionRegister` shall record software design assumptions and dependencies that affect feasibility.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P1 / Beta
- Software unit: `AssumptionRegister`
- Source SAD: SAD-054
- Verification method: Review
Assumptions are reviewed during change impact analysis.
**SDD-063**: `ArchitectureGlossary` shall provide definitions for architecture and detailed design terms.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P2 / Production
- Software unit: `ArchitectureGlossary`
- Source SAD: SAD-055
- Verification method: Review
The glossary reduces ambiguity across software architecture, detailed design, and verification.
**SDD-064**: Each software unit detailed design shall include responsibility, inputs, outputs, interfaces, dynamic behavior, error behavior, resource behavior, and verification hooks where applicable.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P1 / Beta
- Software unit: `SoftwareUnitDesignTemplate`
- Source SAD: SAD-058, SAD-059
- Verification method: Review, Inspection
The template defines the minimum expected detail for unit construction and unit verification.
**SDD-065**: `UnitConstructionGuideline` shall state that software units are constructed according to the SDD rather than reverse-documented from code.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P1 / Beta
- Software unit: `UnitConstructionGuideline`
- Source SAD: SAD-059
- Verification method: Review
The unit construction guideline preserves design-to-code traceability.
**SDD-066**: `SoftwareUnitTraceChecker` shall verify that SDD items link directly to SAD IDs only.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `SoftwareUnitTraceChecker`
- Source SAD: SAD-030, SAD-045, SAD-060
- Verification method: Inspection
The checker supports traceability rule enforcement.
**SDD-067**: `SoftwareUnitTraceChecker` shall support impact analysis from changed SAD items to affected SDD items.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P1 / Beta
- Software unit: `SoftwareUnitTraceChecker`
- Source SAD: SAD-060
- Verification method: Inspection
Impact analysis output identifies affected detailed design units.
**SDD-068**: `DetailedDesignReviewRecord` shall capture review evidence for SDD completeness, testability, and consistency with SAD.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P1 / Beta
- Software unit: `DetailedDesignReviewRecord`
- Source SAD: SAD-059, SAD-060
- Verification method: Review
Review records support baseline approval and communication.
**SDD-069**: `UnitVerificationHandoff` shall identify verification method candidates for each software unit.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P1 / Beta
- Software unit: `UnitVerificationHandoff`
- Source SAD: SAD-059
- Verification method: Review
The handoff supports unit verification planning.
**SDD-070**: `SoftwareUnitRegistry` shall maintain the list of software units, their owning component, source SAD items, and implementation status.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P1 / Beta
- Software unit: `SoftwareUnitRegistry`
- Source SAD: SAD-058, SAD-060
- Verification method: Inspection
The registry supports consistency between architecture, detailed design, implementation, and verification.
## 8. SAD-to-SDD Coverage Matrix
| SAD Range | SDD Coverage |
|---|---|
| SAD-001 through SAD-007 | SDD-001 through SDD-010 |
| SAD-008 through SAD-011 | SDD-011 through SDD-015 |
| SAD-012 through SAD-016 | SDD-016 through SDD-026 |
| SAD-017 through SAD-019 | SDD-027 through SDD-030 |
| SAD-020 through SAD-027 | SDD-031 through SDD-041 |
| SAD-028 through SAD-031 | SDD-042 through SDD-045 |
| SAD-032 through SAD-038 | SDD-046 through SDD-050 |
| SAD-039 through SAD-045 | SDD-046 through SDD-050, SDD-055, SDD-056 |
| SAD-046 through SAD-050 | SDD-051 through SDD-058, SDD-061 |
| SAD-051 through SAD-060 | SDD-057 through SDD-070 |
## 9. Change History
| Version | Date | Description |
|---|---|---|
| 0.1.0 | 2026-05-14 | Initial SDD baseline covering SAD-001 through SAD-045 and enforcing SAD-only direct traceability. |
| 0.2.0 | 2026-05-14 | Updated SDD coverage for expanded SAD v0.2 architecture views, ADRs, deployment architecture, diagnostics architecture, and traceability checker units. |
| 0.3.0 | 2026-05-14 | Added SWE.3 detailed-design completeness criteria, unit interface detail catalog, evaluation checklist, unit construction guideline, and additional SAD coverage. |
---
## 10. Platform Baseline and Product Decision Detailed Design Addendum
**SDD-071**: `IOSBuildConfig` shall define the iOS minimum runtime deployment target as iOS 13 unless an approved platform change raises it.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `IOSBuildConfig`
- Source SAD: SAD-061
- Verification method: Inspection, Platform Test
**SDD-072**: `IOSReleaseGate` shall verify that App Store Connect upload builds use Xcode 26 or later and the iOS 26 / iPadOS 26 SDK or later on or after 2026-04-28 unless Apple publishes a newer applicable upload requirement.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `IOSReleaseGate`
- Source SAD: SAD-062
- Verification method: Release Inspection
**SDD-073**: `AndroidBuildConfig` shall define Android API 24 as the minimum Android runtime baseline and shall expose target SDK configuration for release inspection.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `AndroidBuildConfig`
- Source SAD: SAD-063
- Verification method: Platform Test, Release Inspection
**SDD-074**: `ConnectionSessionManager` shall enforce a single active server connection in MVP.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `ConnectionSessionManager`
- Source SAD: SAD-064
- Verification method: Unit Test, System Test
**SDD-075**: `AudioProcessingSettings` shall default AEC, AGC, Noise Suppression, and High-Pass Filter to enabled where supported and stable.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `AudioProcessingSettings`
- Source SAD: SAD-065
- Verification method: Unit Test, Audio Test
**SDD-076**: `AudioProcessingBackendSelector` shall select platform-native audio processing first where available and stable and isolate any fallback backend behind the audio subsystem interface.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P1 / Beta
- Software unit: `AudioProcessingBackendSelector`
- Source SAD: SAD-066
- Verification method: Unit Test, Audio Test
**SDD-077**: `LocalDatabaseRepository` shall persist non-secret local state through SQLite or an equivalent embedded database abstraction.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `LocalDatabaseRepository`
- Source SAD: SAD-067
- Verification method: Unit Test, Storage Test
**SDD-078**: `SecretStorageRepository` shall persist secrets only through platform secure storage service interfaces.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `SecretStorageRepository`
- Source SAD: SAD-067
- Verification method: Unit Test, Security Audit
**SDD-079**: `TypedBridgeFacade` shall define generated or schema-controlled DTOs for Flutter/Rust commands, results, and events.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `TypedBridgeFacade`
- Source SAD: SAD-068
- Verification method: Integration Test, Inspection
**SDD-080**: `DiagnosticsPrivacyGate` shall disable automatic diagnostic upload, telemetry upload, and crash reporting in MVP release configuration unless an approved decision enables them.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `DiagnosticsPrivacyGate`
- Source SAD: SAD-069, SAD-070
- Verification method: Privacy Review, Security Audit
**SDD-081**: `DesktopPttBackend` shall be a Rust trait in `chanora_audio::ptt` exposing `fn capability(&self) -> PttCapabilityLevel`, `fn backend_id(&self) -> &'static str`, `fn start(&mut self, gate: Arc<AudioTransmitGate>, binding: PttBinding) -> Result<(), PttError>`, `fn stop(&mut self)`, and `fn rebind(&mut self, binding: PttBinding) -> Result<(), PttError>`. Implementations shall be Send and stop on Drop.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `DesktopPttBackend`
- Source SAD: SAD-071
- Verification method: Unit Test, Inspection
**SDD-082**: `PttCapabilityLevel` shall be a plain Rust enum (`L0Focused`, `L1GlobalShortcut`, `L2GlobalHoldToTalk`, `L3GlobalWithMouseButtons`, `L4DeviceAware`) with a public `as_str(&self) -> &'static str` mapping for diagnostics. `L4DeviceAware` is reserved and shall not be produced by any MVP implementation.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `PttCapabilityLevel`
- Source SAD: SAD-071
- Verification method: Unit Test
**SDD-083**: `WindowsRawInputBackend` shall use the `RegisterRawInputDevices` Win32 API targeting `HID_USAGE_PAGE_GENERIC` keyboard and mouse usages, run a dedicated message-only window on its own OS thread, and forward only sanitised binding-match results to the `AudioTransmitGate`. Raw `RAWINPUT` payloads shall never cross the backend boundary.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `WindowsRawInputBackend`
- Source SAD: SAD-072
- Verification method: Platform Test (Windows), Unit Test
**SDD-084**: `WindowsHookBackend` shall be used only when Raw Input registration fails. It installs `WH_KEYBOARD_LL` and `WH_MOUSE_LL` hooks on its dedicated thread; the hook callbacks compare against the active binding and call `AudioTransmitGate::set` only, never logging key data. The hook is uninstalled on Drop.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `WindowsHookBackend`
- Source SAD: SAD-072
- Verification method: Platform Test (Windows), Unit Test
**SDD-085**: `MacOSEventTapBackend` shall create a `CGEventTap` filtered to keyboard and mouse-button events, attached to the main run loop with an explicit retain. The tap callback shall consult the active binding and call `AudioTransmitGate::set` only. The backend shall expose `permission_state() -> Granted | Denied | Undetermined` via `IOHIDCheckAccess` (or the macOS-version-appropriate equivalent) and shall return `PttCapabilityLevel::L0Focused` when permission is not Granted.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `MacOSEventTapBackend`
- Source SAD: SAD-073
- Verification method: Platform Test (macOS), User Acceptance Test
**SDD-086**: `LinuxGnomeWaylandBackend` shall call `CreateSession`, `BindShortcuts`, and listen for `Activated` / `Deactivated` signals on the freedesktop `org.freedesktop.portal.GlobalShortcuts` D-Bus interface. Binding capture shall use the portal's own configuration dialog; Chanora itself does not read raw key events. Missing D-Bus or missing portal interface resolves to `PttCapabilityLevel::L0Focused`.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `LinuxGnomeWaylandBackend`
- Source SAD: SAD-074
- Verification method: Platform Test (Linux, GNOME Wayland), Unit Test
**SDD-087**: `FocusedPttBackend` shall integrate with Flutter's keyboard / pointer event stream via the existing `Listener` widget path and the bridge `set_ptt` command. Reports `PttCapabilityLevel::L0Focused` and `backend_id = "focused"`.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `FocusedPttBackend`
- Source SAD: SAD-071, SAD-072, SAD-073, SAD-074
- Verification method: Unit Test, UI Review
**SDD-088**: `PttController` shall sit in `chanora_core::ptt` and own a `Box<dyn DesktopPttBackend>`, a clone of `AudioTransmitGate`, a `watch::Sender<PttCapabilityLevel>` for live publication to the bridge, and a `tokio::sync::Mutex` over the active `PttBinding`. Public surface: `set_binding`, `current_capability`, `subscribe_capability`.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `PttController`
- Source SAD: SAD-071, SAD-076
- Verification method: Unit Test, Integration Test
**SDD-089**: `AudioTransmitGate` shall be `Arc<AudioTransmitGate>` wrapping a `tokio::sync::watch::Sender<bool>` and an internal `AtomicBool`. `set(v)` updates both atomically; `load()` reads the atomic; `subscribe()` hands out a `watch::Receiver` for the missed-key-up watchdog task.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `AudioTransmitGate`
- Source SAD: SAD-075
- Verification method: Unit Test
**SDD-090**: `PttSanitizer` shall implement `tracing_subscriber::Layer` and decorate the existing `RedactingLogLayer`. Records whose field names match the SDD-077 banned list shall be dropped before `on_event` reaches the wrapped sink. The implementation shall be allocation-free on the success path (the typical "no banned field" case).
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `PttSanitizer`
- Source SAD: SAD-077
- Verification method: Unit Test, Privacy Review
**SDD-091**: `PttCapabilityBadge` shall be a Flutter widget rendered inside the Voice Bar, subscribed to the FRB stream of `BridgeEvent::PttCapability`. The widget shall map each enum value to a short user-facing label and shall render an info icon that opens a per-platform explanation sheet when the resolved capability is `L0Focused`.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `PttCapabilityBadge`
- Source SAD: SAD-078
- Verification method: UI Review, User Acceptance Test
**SDD-092**: `MissedKeyUpWatchdog` shall be a tokio task spawned by the audio engine that holds the `watch::Receiver<bool>` from `AudioTransmitGate::subscribe()`. On each transition from `false` to `true` the task records the timestamp; on each `true -> false` transition the task clears the timestamp. If the transition timeline shows `true` for longer than the configured timeout the task calls `AudioTransmitGate::set(false)` and emits a sanitised diagnostic record.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `MissedKeyUpWatchdog`
- Source SAD: SAD-079
- Verification method: Unit Test, Integration Test
**SDD-093**: `PttInputClass` shall be a Rust enum in `chanora_audio::ptt_backends` with variants `None`, `Keyboard`, and `MouseSideButton`. The enum is the only carrier of the user's bound input class across the audio + bridge + Flutter boundary; its `as_str(&self) -> &'static str` mapping returns the diagnostic-safe label (`""` / `"keyboard"` / `"mouse-side-button"`) consumed by `PttBackendDescriptor::bound_input_class`. The Windows backend ladder and the macOS event-tap backend shall observe the `MouseSideButton` variant on their binding-rebind path and translate it into the platform's native side-button identifier internally; the Linux GNOME-Wayland portal backend shall accept whatever input class the portal returns from `BindShortcuts` and apply the same classifier already documented in `desktop-ptt-architecture.md` §5.3. The Flutter binding-capture dialog shall capture mouse side-button presses through the `PointerEvent.buttons` bitmask (back = `0x08`, forward = `0x10`) and never forward the raw bitmask beyond the dialog — the bridge `set_ptt_binding` call carries only the enum variant.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `PttInputClass`, `WindowsRawInputBackend`, `WindowsHookBackend`, `MacOSEventTapBackend`, `LinuxGnomeWaylandBackend`, `_PttBindingCaptureDialog`
- Source SAD: SAD-080
- Verification method: Unit Test, Platform Test (Windows / macOS / Linux), UI Review
**SDD-094**: `chanora_bridge::voice::voice_join(channel_id: ChannelId) -> Result<(), VoiceError>` and `chanora_bridge::voice::voice_leave() -> Result<(), VoiceError>` shall be the only public-bridge voice lifecycle calls. Internally `chanora_audio::engine::AudioEngine::ensure_running()` shall be idempotent and shall open the cpal input and output streams on the first call of the session; `chanora_audio::engine::AudioEngine::shutdown_if_idle()` shall be called from `voice_leave` and shall close both streams when no voice channels remain. The Flutter widget tree shall subscribe to `BridgeEvent::VoiceState { in_channel, transmit_mode, mute, release_tail_ms }` through the existing FRB stream and shall render the Voice Bar from that stream. The pre-existing `start_audio` and `stop_audio` FRB symbols shall be deleted from `crates/chanora_bridge/src/api.rs` together with their generated bindings; the corresponding caller in `apps/chanora_flutter/lib/main.dart` shall be removed.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `chanora_bridge::voice`, `chanora_audio::engine::AudioEngine`, `BridgeEvent::VoiceState`, `apps/chanora_flutter/lib/main.dart`
- Source SAD: SAD-081
- Verification method: Integration Test, UI Review
**SDD-095**: `chanora_audio::TransmitMode` shall be a `#[repr(u8)]` Rust enum with variants `Ptt = 0`, `Continuous = 1`, `VoiceActivity = 2`. Persistence shall be provided by `chanora_storage::IdentityStore::set_transmit_mode(&self, mode: TransmitMode)` and `chanora_storage::IdentityStore::get_transmit_mode(&self) -> TransmitMode`, the latter returning `TransmitMode::Ptt` on first read for a fresh install. The bridge surface shall carry the enum across the FFI boundary via `mirror` codegen as `BridgeTransmitMode`. The Flutter settings page in `apps/chanora_flutter/lib/widgets/voice_settings.dart` shall render three radio rows; the `VoiceActivity` row shall be rendered with `enabled: false` and a "Coming soon" trailing label until DEC-030 is resolved and an implementation is allocated.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `chanora_audio::TransmitMode`, `chanora_storage::IdentityStore::{set_transmit_mode, get_transmit_mode}`, `BridgeTransmitMode`, `apps/chanora_flutter/lib/widgets/voice_settings.dart`
- Source SAD: SAD-083
- Verification method: Unit Test, UI Review
**SDD-096**: `chanora_audio::release_tail::ReleaseTailTimer` shall be a tokio-task-owning struct exposing `arm(&self, gate: AudioTransmitGate, tail_ms: u32)`, `key_down(&self)`, `key_up(&self)`, and `cancel(&self)`. Internally the struct shall hold a `tokio::sync::watch::Sender<bool>` plus a `JoinHandle<()>` for the pending close. `key_down` shall abort any pending close handle and shall set `transmit_active = true` via the gate; `key_up` shall abort the prior close handle and shall spawn a new task that sleeps for `tail_ms` milliseconds and then sets `transmit_active = false`. The struct shall use no `unsafe`, no mutex, and shall rely only on atomic refcounts on the watch handle. The configuration value `release_tail_ms` shall live in the identity store next to `transmit_mode`, with a default of 200 and validated range 0–500 inclusive on every write.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `chanora_audio::release_tail::ReleaseTailTimer`, `chanora_storage::IdentityStore` (`release_tail_ms`)
- Source SAD: SAD-082
- Verification method: Unit Test, Integration Test
**SDD-097**: `apps/chanora_flutter/lib/widgets/voice_bar.dart` shall replace the existing `_AudioControls` widget in `apps/chanora_flutter/lib/main.dart` as the rendering surface for voice state. Its input shall be the `BridgeEvent::VoiceState` stream; its children, in render order, shall be: the channel-name pill (visible only when `in_channel` is true); the mode badge (`PTT: <key_label>` / `Continuous` / `Voice activity (coming soon)`); the hard-mute toggle button; the release-tail and threshold disclosure; the level meter; and the PTT capability badge already specified in SDD-091. The "Start audio" button shall be removed from the widget tree. The settings dialog in `apps/chanora_flutter/lib/widgets/voice_settings.dart` shall render the `TransmitMode` radio group, the bind-key button, and a release-tail slider over the range 0–500 ms with step 25 ms; the dialog shall never expose a "Start audio" affordance.
- Status: Draft
- Type: Software Detailed Design Item
- Stage: P0 / MVP
- Software unit: `apps/chanora_flutter/lib/widgets/voice_bar.dart`, `apps/chanora_flutter/lib/widgets/voice_settings.dart`, `apps/chanora_flutter/lib/main.dart`
- Source SAD: SAD-081, SAD-083
- Verification method: UI Review, Widget Test
## 11. Updated SAD-to-SDD Coverage Matrix
| SAD Range | SDD Coverage |
|---|---|
| SAD-001 through SAD-060 | Covered by inherited SDD baseline `SDD-001` through `SDD-070` |
| SAD-061 through SAD-070 | Covered by `SDD-071` through `SDD-080` |
| SAD-071 through SAD-079 | Covered by `SDD-081` through `SDD-092` |
| SAD-080 | Covered by `SDD-093` |
| SAD-081 through SAD-083 | Covered by `SDD-094` through `SDD-097` |
## Baseline Candidate 0.9.1 Update
| Version | Date | Description |
|---|---|---|
| 0.9.1 | 2026-05-14 | Updated baseline after product decision closure: Apple App Store SDK gate uses Xcode 26+ and iOS 26 / iPadOS 26 SDK+ since 2026-04-28, platform baselines and decision traceability propagated across the document set. |
## Baseline Candidate 0.9.2 Update
| Version | Date | Description |
|---|---|---|
| 0.9.2 | 2026-05-14 | Corrected Apple App Store Connect upload gate effective date and preserved layer-specific traceability. |
## Baseline Candidate 0.9.3 Update
| Version | Date | Description |
|---|---|---|
| 0.9.3 | 2026-05-15 | Added desktop PTT detailed design SDD-081 through SDD-092: `DesktopPttBackend` trait, `PttCapabilityLevel` enum, Windows Raw-Input + low-level-hook + Focused implementations, macOS event-tap + Focused implementations, Linux GNOME-Wayland portal + Focused implementations, `PttController`, `AudioTransmitGate`, `PttSanitizer` layer, `PttCapabilityBadge` widget, `MissedKeyUpWatchdog` task. Strict sourcing (`SDD -> SAD` only) preserved. |
## Baseline Candidate 0.9.4 Update
| Version | Date | Description |
|---|---|---|
| 0.9.4 | 2026-05-15 | Added `SDD-093` covering `SAD-080`. `SDD-093` fixes the `PttInputClass` enum surface, the cross-backend rebind contract for `MouseSideButton`, and the Flutter side-button capture path against the `PointerEvent.buttons` bitmask. Strict layered sourcing preserved (`SDD -> SAD` only). |
## Baseline Candidate 0.9.5 Update
| Version | Date | Description |
|---|---|---|
| 0.9.5 | 2026-05-15 | Added v1 audio + PTT lifecycle detailed design SDD-094 through SDD-097 sourced from SAD-081..083: bridge surface drops `start_audio` / `stop_audio` and exposes `chanora_bridge::voice::voice_join` / `voice_leave` with idempotent `AudioEngine::ensure_running` and `shutdown_if_idle`, `chanora_audio::TransmitMode` as `#[repr(u8)]` enum persisted via `chanora_storage::IdentityStore::{set,get}_transmit_mode` and mirrored across FRB as `BridgeTransmitMode`, `chanora_audio::release_tail::ReleaseTailTimer` as a tokio-task-owning adapter on the watch handle (no `unsafe`, no mutex; configurable 0–500 ms via `release_tail_ms`), and the new `apps/chanora_flutter/lib/widgets/voice_bar.dart` + `voice_settings.dart` surfaces replacing the legacy `_AudioControls` widget. Strict layered sourcing preserved (`SDD -> SAD` only). |
Reference in New Issue View Git Blame Copy Permalink