edison/chanora
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
181b3d329de3e9148147cd6109ea660db2c8be27
chanora/docs/architecture/sdd.md
T
EdisonJwa f1bc9a6c85 chore(repo): initial baseline import (docs v0.9.2 + bootstrap) 
Imports the v0.9.2 documentation baseline and the bootstrap files
required by docs/governance/repository-bootstrap-plan.md v0.1.0 §3,
minus the justfile (added in the next commit).

This commit establishes the git history for the project. All previous
work lived only as filesystem state with no version control.
2026-05-14 12:25:33 +08:00

37 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

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

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.
Reference in New Issue View Git Blame Copy Permalink