Files

T

EdisonJwa 63f2901a6a docs(traceability): close SRS-200 SAD/SDD coverage gap (P0 audit follow-up)

A P0 traceability audit per the project's compliance workflow
found exactly one gap across the 162 P0 SRS items:

  * SRS-200 (mouse side buttons as bindable inputs for desktop
    Global PTT) had no dedicated SAD item. The earlier baseline
    matrix folded SRS-200 under the narrative
    `SRS-195..203 -> SAD-071..079` umbrella, which technically
    covered the requirement at the table level but did not give
    SRS-200 a one-to-one SAD source the validator's strict
    discipline expects.

Per the project's gate-check workflow (Case C —
BLOCKED_MISSING_SAD) this commit closes the documentation chain
*before* claiming compliance for the already-merged mouse-side-
button code path:

  * `docs/architecture/sad.md` v0.9.4 — new `SAD-080` sources
    SRS-200, allocates `Audio (Windows / macOS / Linux), Bridge,
    Flutter UI`, and records the cross-platform mouse-side-button
    surface as a software-architecture item. The §27 coverage
    matrix gains a dedicated SRS-200 -> SAD-080 row.
  * `docs/architecture/sdd.md` v0.9.4 — new `SDD-093` sources
    SAD-080. Specifies the `PttInputClass` enum surface
    (`None` / `Keyboard` / `MouseSideButton`), the rebind
    contract on the Windows + macOS backends, the Linux portal's
    pass-through behaviour, and the Flutter
    `PointerEvent.buttons` bitmask capture (back = `0x08`,
    forward = `0x10`). The §11 coverage matrix gains the
    SAD-080 -> SDD-093 row.
  * `docs/governance/traceability-matrix.md` v0.9.4 — the
    `(DEC-026 mouse buttons)` row moves from
    `SAD-072..074 / SDD-082..086` to the dedicated
    `SAD-080 / SDD-093`.
  * `docs/governance/baseline-candidate-validation-report.md`
    v0.9.4 — ID totals advance to 302 / 148 / 203 / 80 / 93;
    direct-layer-rule and undefined-reference counts remain
    zero.
  * `docs/governance/repo-format-validation-report.md` v0.9.4 —
    same ID totals update.

Audit summary
-------------

* 162 P0 SRS items audited.
* 1 SAD-coverage gap (SRS-200) — closed by this commit.
* 0 SDD-coverage gaps (every PTT SAD has explicit SDD coverage;
  the inherited baseline `SAD-032/033` are covered through the
  documented range row, not individually).
* All Priority: P0 software requirements now have a strict
  SRS -> SAD -> SDD chain on file.

Validator output:

```
[OK] SysRS: 302 defined, 0 undefined references
[OK] SysDes: 148 defined, 0 undefined references
[OK] SRS: 203 defined, 0 undefined references
[OK] SAD: 80 defined, 0 undefined references
[OK] SDD: 93 defined, 0 undefined references
[OK] SRS direct SysRS references: 0
[OK] SAD direct SysRS references: 0
[OK] SAD direct SysDes references: 0
[OK] SDD direct SysRS references: 0
[OK] SDD direct SysDes references: 0
[OK] SDD direct SRS references: 0
```

Implementation status
---------------------

The mouse-side-button code was implemented in v1.0.0-rc.4 and
v1.0.0-rc.5 under the (then-implicit) PTT umbrella; the code
already matches the new SDD-093's contract verbatim. This
commit ships **documentation only** — it adds the SAD/SDD/matrix
rows that retroactively justify the existing implementation
under the strict traceability discipline. No code edits, no test
edits.

  * `cargo test --workspace`: 67/67 green (unchanged).
  * `cargo deny check`: advisories ok, bans ok, licenses ok,
    sources ok.
  * `cargo about generate`: zero new warnings (no Cargo.lock
    delta).
  * `flutter analyze`: clean.
  * `tools/validate_docs.py`: all SRS/SAD/SDD coverage and
    direct-layer-rule checks pass.

Outstanding open items remain live verification per
`docs/release/release-readiness-go-nogo-record.md`
(RR-PTT-001..006/008) and the DEC-012 legal review; both are
non-engineering work.

2026-05-15 17:02:26 +08:00

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

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

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`

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

46 KiB Raw Blame History