edison/chanora
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
76c6d1d40c5da3f7db5e1b0218ec337e87801678
chanora/docs/architecture/sdd.md
T

59 KiB
Raw Blame History

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.7 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

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 any of the following banned field names shall be dropped before on_event reaches the wrapped sink: key_code, scan_code, virtual_key, vk, keysym, keysym_string, key_sequence (7 fields required by SAD-077) and key_press_history, key_timing (2 defensive additions for future PTT diagnostic fields that might carry raw key data). 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 cancel any pending close by aborting the JoinHandle (cancel_pending()) and shall set transmit_active = true via the gate; key_up shall abort the prior close handle via JoinHandle::abort() and shall spawn a new task that sleeps for tail_ms milliseconds and then sets transmit_active = false. Cancellation is performed by aborting the pending JoinHandle; the watch channel enables cooperative early exit — the spawned task races cancel_rx.changed() against the tail sleep so that it can exit without writing to the gate when the sender is replaced or dropped. The struct shall use no unsafe. No std::sync::Mutex — interior mutability shall use std::sync::RwLock for brief edge-transition writes (arm, key_down, key_up, cancel); concurrent reads are uncontended. The watch handle shall be shared via atomic refcounts. 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

SDD-098: IOSAudioSessionConfig shall be a Swift unit that configures AVAudioSession with category .playAndRecord, mode .default, and options .defaultToSpeaker | .allowBluetoothHFP | .allowBluetoothA2DP. setCategory shall be called from didFinishLaunching in the app delegate; setActive shall be called from the UIApplication.didBecomeActiveNotification observer. The actual session state shall be read back after both calls and logged for verification.

  • Status: Draft
  • Type: Software Detailed Design Item
  • Stage: P0 / MVP
  • Software unit: IOSAudioSessionConfig
  • Source SAD: SAD-061, SAD-064
  • Verification method: Platform Test, Release Inspection

SDD-099: IOSPermissionRequester shall call AVAudioSession.sharedInstance().requestRecordPermission approximately 1 second after app launch. The permission result shall be logged. A denied permission shall surface as an audio engine failure at voice_join time with a user-safe message; the UI shall not crash or hang.

  • Status: Draft
  • Type: Software Detailed Design Item
  • Stage: P0 / MVP
  • Software unit: IOSPermissionRequester
  • Source SAD: SAD-061
  • Verification method: Platform Test, Demo

SDD-100: Swift shall observe AVAudioSession.routeChangeNotification. On route change where reason == .oldDeviceUnavailable or reason == .newDeviceAvailable, Swift shall call the Rust bridge method handleRouteChange(). The Rust side shall invoke the ios_voice_unit restart path, uninitialising then reinitialising per ios_voice_unit.rs comments §5. Audio shall continue after rebind.

  • Status: Draft
  • Type: Software Detailed Design Item
  • Stage: P0 / MVP
  • Software unit: IOSRouteChangeHandler, ios_voice_unit
  • Source SAD: SAD-061, SAD-064
  • Verification method: Platform Test TC-9.3

SDD-101: Swift shall observe AVAudioSession.interruptionNotification. On .began the audio shall pause via VPIO.stop(). On .ended with shouldResume == true the audio shall resume via VPIO.start(). A phone call shall yield the audio session; the end of the call shall resume audio without user action. The interruption state shall be communicated to Flutter via BridgeEvent.

  • Status: Draft
  • Type: Software Detailed Design Item
  • Stage: P0 / MVP
  • Software unit: IOSInterruptionRecovery, BridgeEvent
  • Source SAD: SAD-061
  • Verification method: Platform Test TC-9.1, TC-9.2

Design note (shouldResume == false): When iOS signals interruption end with shouldResume == false, the VPIO unit remains paused and the BridgeEvent_InterruptionState carries shouldResume: false to Flutter. The Flutter UI surfaces a snackbar indicating the interruption. The user must manually rejoin the voice channel or the app must implement a "resume audio" action in a future release. This is a known limitation for P0.

Design note (lifecycle interleaving): The current iOS audio lifecycle handlers (route change, interruption began/ended) are individually serialized by the session mutex and _ios_voice_unit mutex, but do not track an explicit lifecycle state (e.g., Running, Interrupted, Restarting). This means that a route change arriving during an active interruption will restart the VPIO unit even though the app should remain paused. A future release should introduce an explicit iOS audio lifecycle state model that gates restart/resume decisions accordingly. For P0, the risk is mitigated by iOS serializing these notifications on the main thread and the low probability of interleaving in practice.

SDD-102: Info.plist shall contain UIBackgroundModes = [audio]. The VPIO unit shall continue running when the app backgrounds. iOS shall show the red microphone indicator in the status bar while background audio is active. AVAudioSession shall remain active. On iOS lock screen, audio shall continue if the network remains available.

  • Status: Draft
  • Type: Software Detailed Design Item
  • Stage: P0 / MVP
  • Software unit: Info.plist, VPIOUnit
  • Source SAD: SAD-061
  • Verification method: Platform Test TC-8

SDD-103: iOS P0 shall use FocusedPttBackend only. There shall be no DesktopPttBackend ladder on iOS. PttCapabilityLevel shall always be L0Focused. The UI shall render an on-screen PTT button. A capability badge shall explain the iOS limitation. Users shall bind a key through the in-app dialog only when the app is in the foreground.

  • Status: Draft
  • Type: Software Detailed Design Item
  • Stage: P0 / MVP
  • Software unit: FocusedPttBackend, PttCapabilityLevel, FocusedPttBindingDialog
  • Source SAD: SAD-061, SAD-071
  • Verification method: Platform Test TC-3, TC-12

SDD-104: VoiceProcessingIO AudioUnit shall provide hardware AEC, AGC, and noise suppression. These shall always be engaged and shall not be user-disableable. The Flutter audio processing settings UI shall display these as hardware-enabled with switches disabled and a "Hardware-enabled" label.

  • Status: Draft
  • Type: Software Detailed Design Item
  • Stage: P0 / MVP
  • Software unit: VoiceProcessingIO, AudioProcessingSettings (Flutter)
  • Source SAD: SAD-061, SAD-065
  • Verification method: Platform Test, Audio 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-061 through SAD-070 Covered by SDD-098 through SDD-104 (iOS platform additions)

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).

Baseline Candidate 0.9.6 Update

Version Date Description
0.9.6 2026-05-17 Added iOS P0 platform SDD-098 through SDD-104 to close traceability gaps identified in the P0 audit: IOSAudioSessionConfig (AVAudioSession .playAndRecord configuration), IOSPermissionRequester (microphone permission flow), IOSRouteChangeHandler (route change observation and Rust bridge call), IOSInterruptionRecovery (audio interruption handling), Info.plist / VPIOUnit (background audio), FocusedPttBackend only (iOS no global PTT), and VoiceProcessingIO (hardware AEC/AGC/NS always engaged). Sourced from SAD-061, SAD-064, SAD-065, SAD-071. Strict layered sourcing preserved (SDD -> SAD only).

Baseline Candidate 0.9.7 Update

Version Date Description
0.9.7 2026-05-17 Added design notes to SDD-101: (1) shouldResume == false behavior for iOS audio interruption recovery — VPIO remains paused, BridgeEvent_InterruptionState carries shouldResume: false to Flutter, snackbar surfaces the interruption, manual rejoin required; (2) iOS audio lifecycle interleaving concern — handlers are individually serialized but lack explicit lifecycle state, route-change-during-interruption risk is mitigated by iOS main-thread serialization for P0.
Reference in New Issue View Git Blame Copy Permalink