chanora/docs/architecture/sad.md

# Chanora SAD — Software Architecture Description

**Document type:** SAD / Software Architecture Description  
**Process alignment:** ASPICE SWE.2 Software Architectural Design  
**Version:** 0.9.2
**Status:** Baseline Candidate  
**Language:** English  
**Product:** Chanora  
**Architecture baseline:** Flutter + Rust Core  
**Lifecycle position:** `SysRS -> SysDes -> SRS -> SAD -> SDD`  

**Repo path:** `docs/architecture/sad.md`  ---

## 1. Purpose

This Software Architecture Description defines the software architecture for Chanora.

The SAD is intentionally structured as an architecture document, not only a list of modules. It includes:

- Stakeholders and concerns
- Architecture drivers and constraints
- System context view
- Container view
- Component view
- Runtime / sequence views
- Deployment view
- Data and storage view
- Security and privacy view
- Diagnostics and observability view
- UI architecture view
- Audio architecture view
- Protocol architecture view
- Internationalization architecture view
- Architecture decision records
- SRS-to-SAD traceability

## 2. Strict Traceability Rules

The documentation hierarchy is:

```text
SysRS -> SysDes -> SRS -> SAD -> SDD
```

The SAD shall use only the SRS layer as its direct source.

Rules:

```text
SAD items shall use Source SRS only.
SAD items shall not use direct system-requirement sources.
SAD items shall not use direct system-design sources.
SDD items shall use Source SAD only.
```

## 3. Stakeholders and Architecture Concerns

| Stakeholder | Concerns |
|---|---|
| End user | Fast voice access, stable connection, clear UI, safe controls |
| Power user | Audio configuration, diagnostics, reliable reconnect |
| Software team | Clear module boundaries, testability, maintainability |
| Platform team | OS permissions, audio routing, lifecycle behavior, packaging |
| QA team | Traceability, test seams, platform coverage, regression verification |
| Security reviewer | Secret storage, redaction, input validation, diagnostics safety |
| UX designer | Material 3 consistency, adaptive layout, accessibility, i18n |
| Release operator | Repeatable builds, signing, packaging, release metadata |

## 4. Architecture Drivers

| Driver | Architectural impact |
|---|---|
| Flutter + Rust Core | UI and core logic are separated by bridge DTOs and event streams. |
| `tsclientlib` | Protocol integration is isolated inside a protocol adapter. |
| Cross-platform operation | Platform behavior is isolated behind platform services and adapters. |
| Low-latency voice | Real-time audio processing is isolated from UI rendering. |
| Material 3 baseline | UI architecture uses a design-system layer above Material 3. |
| Strict traceability | SAD derives only from SRS and SDD derives only from SAD. |
| i18n readiness | Product localization, server content, Unicode, and diagnostics text are separated. |
| Diagnostics and support | Logging, redaction, exports, and machine-readable diagnostics are centralized. |

## 5. Context View

```text
User
  -> Chanora Flutter Client
       -> Rust Core
          -> tsclientlib Protocol Adapter
             -> External TeamSpeak-compatible Server

Chanora Flutter Client
  -> Operating System Services
       -> Audio devices
       -> Secure storage
       -> Permissions
       -> Notifications
       -> Lifecycle / insets / routing
```

### Context boundaries

Inside Chanora software:

- Flutter app shell
- Chanora design system
- Feature modules
- Flutter state and view models
- Bridge facade
- Rust Core
- Protocol adapter
- Audio subsystem
- Storage subsystem
- Diagnostics subsystem
- Localization subsystem
- Platform service abstractions

Outside Chanora software:

- External compatible voice servers
- Operating systems
- Physical audio devices
- App stores / package repositories
- Network infrastructure

## 6. Container View

```text
+---------------------------------------------------------------+
| Flutter Application Container                                 |
|  App Shell                                                    |
|  Design System                                                |
|  Adaptive Shell                                               |
|  Feature Modules                                              |
|  Flutter State / View Models                                  |
|  Localization Service                                         |
|  Platform Services                                            |
+------------------------- Bridge DTOs / Events ----------------+
| Rust Core Container                                           |
|  Connection Manager                                           |
|  State Synchronization                                        |
|  Protocol Adapter                                             |
|  Audio Engine                                                 |
|  Storage Services                                             |
|  Diagnostics                                                  |
+---------------------------------------------------------------+
```

| Container | Responsibility |
|---|---|
| Flutter Application Container | UI, navigation, Material 3 theming, accessibility, localization, platform presentation |
| Bridge Container | Stable DTOs, commands, event streams, error mapping |
| Rust Core Container | Authoritative connection, protocol coordination, state, audio, storage, diagnostics |
| Platform Services Container | OS-specific services exposed to Flutter/Rust boundaries |
| External Server | Compatible server providing channels, users, voice, and text |

## 7. Component View

### 7.1 Flutter application components

| Component | Responsibility |
|---|---|
| `app_shell` | App initialization, routing, global providers, theme mode, localization bootstrap |
| `design_system` | Material 3 configuration, Chanora tokens, typography, shapes, motion, density |
| `adaptive_shell` | Compact, medium, expanded layout branching |
| `features/connect` | Manual connection and bookmark entry |
| `features/server` | Channel tree, users, connection status |
| `features/voice` | Voice controls and audio settings |
| `features/chat` | Channel text UI |
| `features/settings` | User settings, audio processing settings, i18n options |
| `features/diagnostics` | Redacted diagnostics and export flow |
| `state` | View models derived from Rust Core events |
| `localization` | Product string resources and fallback |
| `platform_services` | Insets, back intent, haptics, permissions, platform behavior |

### 7.2 Rust components

| Component | Responsibility |
|---|---|
| `chanora_core` | Top-level Rust API, connection orchestration, command handling |
| `chanora_protocol` | `tsclientlib` isolation and protocol event mapping |
| `chanora_state` | Snapshot, delta, reducers, authoritative state model |
| `chanora_audio` | Capture, processing, encode/decode, jitter, mixing |
| `chanora_storage` | Bookmarks, settings, identity references, non-secret data |
| `chanora_diagnostics` | Logs, redaction, event recording, export |
| `chanora_bridge` | Flutter/Rust DTOs, API, event streams |

## 8. Runtime Views

### 8.1 Application startup

```text
Start process
  -> Initialize platform bindings
  -> Load localization baseline
  -> Build Material 3 theme
  -> Register Chanora design tokens
  -> Initialize bridge facade
  -> Initialize app router
  -> Render adaptive shell
```

### 8.2 Connect to server

```text
User submits connection
  -> Connect feature controller
  -> Bridge command
  -> Rust Core connection manager
  -> Protocol adapter
  -> tsclientlib
  -> External server
  -> Snapshot fetch
  -> State reducer
  -> Core event stream
  -> Flutter view model
  -> Server screen render
```

### 8.3 Incoming server event

```text
External server event
  -> tsclientlib
  -> Protocol adapter
  -> Internal protocol event
  -> State reducer
  -> Core event
  -> Bridge stream
  -> Flutter state
  -> UI update
```

### 8.4 Outgoing voice

```text
Microphone
  -> Platform capture
  -> Audio pipeline
  -> High-pass filter
  -> Noise suppression
  -> Echo canceller
  -> Automatic gain control
  -> Push-to-talk / mute gate
  -> Encoder
  -> Protocol adapter
  -> External server
```

### 8.5 Incoming voice

```text
External server
  -> Protocol adapter
  -> Jitter buffer
  -> Decoder
  -> Per-user mute / volume
  -> Mixer
  -> Platform playback
```

### 8.6 Product-localized text rendering

```text
String key
  -> Localization service
  -> Locale lookup
  -> Fallback if missing
  -> Flutter text widget
  -> Accessibility semantics
```

### 8.7 Server-content rendering

```text
Server-provided text
  -> Protocol boundary conversion if required
  -> UTF-8 internal representation
  -> DTO / state
  -> Flutter UI
  -> Display without translation
```

## 9. Deployment View

| Platform | Deployment form |
|---|---|
| Windows | Signed installer or packaged desktop artifact |
| macOS | Signed and notarized application bundle |
| Linux | Selected package format such as AppImage, Flatpak, deb, or rpm |
| Android | AAB/APK with platform permissions and foreground voice behavior |
| iOS | TestFlight/App Store build with platform permission and audio session behavior |

Deployment architecture separates:

- Build scripts
- Signing assets
- Store metadata
- Release notes
- Platform permission declarations
- Runtime configuration

## 10. Data and Storage View

| Data type | Storage architecture |
|---|---|
| Bookmarks | Local database / repository |
| Recent servers | Local database / repository |
| Audio settings | Local database / repository |
| UI preferences | Local database / repository |
| Identity secrets | Platform secure storage |
| Server passwords | Platform secure storage |
| Diagnostic bundles | User-initiated generated export |
| Protocol state | Runtime state, rebuilt from snapshot |
| Product localization | Static or packaged localization resources |
| Server content | Runtime content, optionally session-level persistence later |

## 11. Security and Privacy View

Security architecture rules:

- Secrets are not stored in plaintext.
- Passwords and identity secrets are stored through platform secure storage.
- Logs and diagnostic exports are redacted.
- User-visible errors do not expose internal stack traces.
- Diagnostics export requires user action.
- Protocol and platform text conversions occur only at explicit boundaries.
- Product localization does not translate server-provided content.

## 12. Diagnostics and Observability View

Diagnostics components provide:

- Structured logs
- Redaction
- Network diagnostics
- Audio diagnostics
- Protocol event recording where enabled
- Event replay support where enabled
- User-initiated diagnostic export
- Stable language-neutral diagnostic keys
- Localizable diagnostic display descriptions

## 13. UI Architecture View

```text
Material 3
  -> Chanora Design System
     -> Tokens
     -> Component themes
     -> Chanora components
        -> Feature screens
           -> View models
```

Rules:

- Feature screens do not hardcode semantic colors, spacing, shapes, or motion.
- Design system owns Material 3 mapping.
- Components own accessibility semantics for common controls.
- Voice and connection controls remain visible or directly reachable across layouts.
- Adaptive shell owns layout class selection.

## 14. Audio Architecture View

The audio subsystem is separate from UI rendering.

Key elements:

- Platform capture
- Audio preprocessing
- Echo cancellation
- Automatic gain control
- Noise suppression
- High-pass filtering
- Voice activity and metering
- Push-to-talk and mute gate
- Opus-compatible encode/decode
- Jitter buffer
- Mixer
- Playback routing

## 15. Protocol Architecture View

The protocol subsystem isolates all `tsclientlib` interaction.

Rules:

- Flutter does not call `tsclientlib`.
- Rust Core does not expose raw protocol library types to Flutter.
- Protocol events are converted to internal protocol events.
- Protocol errors are converted to user-safe error models.
- Reconnect orchestration remains above protocol adapter behavior when required.

## 16. Internationalization Architecture View

i18n architecture separates:

| Text type | Handling |
|---|---|
| Product strings | Localized |
| Accessibility labels | Localized |
| Settings labels | Localized |
| Error descriptions | Localized where user-facing |
| Diagnostic keys | Stable and language-neutral |
| Server names | Preserved, not translated |
| Channel names | Preserved, not translated |
| Client nicknames | Preserved, not translated |
| Chat messages | Preserved, not translated |

UTF-8 is the internal representation for cross-layer text. Conversion occurs only at protocol or platform boundaries.

## 17. Architecture Decisions

| ADR | Decision | Status |
|---|---|---|
| ADR-001 | Use Flutter for cross-platform UI | Accepted |
| ADR-002 | Use Rust Core for protocol, state, audio, storage, and diagnostics logic | Accepted |
| ADR-003 | Use `tsclientlib` and isolate it in the protocol adapter | Accepted |
| ADR-004 | Use Material 3 as UI design baseline | Accepted |
| ADR-005 | Define Chanora Design System above Material 3 | Accepted |
| ADR-006 | Use strict `SysRS -> SysDes -> SRS -> SAD -> SDD` traceability | Accepted |
| ADR-007 | Do not let SAD link directly to system requirement or system design IDs | Accepted |
| ADR-008 | Use UTF-8 internally and boundary-only string conversion | Accepted |
| ADR-009 | Treat server-provided text as content, not product localization | Accepted |


## 18. SWE.2 Architecture Completeness and Evaluation Criteria

The architecture shall be evaluated against the following SWE.2 criteria before baseline approval and after architecture-affecting changes.

| Criterion | Architecture evidence |
|---|---|
| Software elements are identified | Component View and Software Architecture Items |
| Software requirements are allocated | SRS-to-SAD coverage matrix |
| Interfaces are defined | Interface Catalog |
| Dynamic behavior is defined | Runtime Views |
| Resource consumption objectives are considered | Performance and Resource View |
| Architecture is technically feasible | Architecture evaluation checklist |
| Architecture is testable | Verification hooks and test seams |
| Traceability is maintained | Direct `Source SRS` references only |
| Consistency is maintained | View consistency checklist and change impact review |
| Architecture is communicated | Change History and baseline approval record |

## 19. Interface Catalog

The interface catalog records software architectural interfaces. Detailed design shall refine these interfaces in the SDD.

| Interface ID | Interface | Producer | Consumer | Data / message | Error handling | Source SAD |
|---|---|---|---|---|---|---|
| IF-SAD-001 | Flutter command bridge | Flutter Feature Controller | Rust Bridge Facade | Command DTO | Bridge error DTO | SAD-040 |
| IF-SAD-002 | Rust event stream | Rust Core | Flutter State | Core event DTO | Stream close / error event | SAD-041 |
| IF-SAD-003 | Protocol adapter boundary | Rust Core | Protocol Adapter | Protocol command / event | Protocol error mapping | SAD-032 |
| IF-SAD-004 | Audio capture boundary | Platform Audio | Audio Subsystem | Audio frame | Device unavailable / underrun | SAD-034 |
| IF-SAD-005 | Audio playback boundary | Audio Subsystem | Platform Audio | Mixed audio frame | Device unavailable / route changed | SAD-034 |
| IF-SAD-006 | Secure storage boundary | Storage Service | Platform Secure Storage | Secret key/value | Secure-store error | SAD-035 |
| IF-SAD-007 | Localization lookup | Flutter UI | Localization Service | String key + parameters | Missing-key fallback | SAD-020 |
| IF-SAD-008 | Server-content text path | Protocol Adapter | Flutter UI | UTF-8 content text | Boundary conversion error | SAD-021, SAD-022 |
| IF-SAD-009 | Diagnostics export | Diagnostics | File/share target | Redacted diagnostic bundle | Export failure | SAD-036, SAD-050 |
| IF-SAD-010 | Platform behavior service | Flutter Shell | Platform Services | Insets, back, haptics, permissions | Unsupported platform behavior | SAD-017, SAD-018, SAD-019 |

## 20. Performance and Resource View

| Area | Objective | Architecture mechanism |
|---|---|---|
| UI responsiveness | Avoid blocking UI during connection, sync, reconnect, and diagnostics export | Async bridge calls, view models, Rust Core background work |
| Audio latency | Minimize local audio pipeline latency | Dedicated audio subsystem and platform audio adapters |
| Memory growth | Avoid unbounded growth in logs, audio buffers, chat history, and event queues | Bounded buffers, retention policies, diagnostic export controls |
| Reconnect | Rebuild state after recoverable connection failure | Connection manager, fresh snapshot, state reducer |
| Localization | Avoid runtime string lookup failures | Baseline English fallback and localization service tests |
| Diagnostics | Export without leaking secrets | Central redaction and export service |

## 21. Assumptions and Dependencies

| ID | Assumption / Dependency | Impact |
|---|---|---|
| SAD-ASM-001 | Flutter Material 3 support is available on the target Flutter version. | Design System depends on Material 3 widgets and ThemeData behavior. |
| SAD-ASM-002 | Rust and Flutter bridge tooling supports stable DTO generation. | Bridge and event stream interfaces depend on stable generated bindings. |
| SAD-ASM-003 | `tsclientlib` supports or can be adapted for required MVP protocol behavior. | Protocol Adapter feasibility depends on library capability. |
| SAD-ASM-004 | Target operating systems expose required audio, permission, and secure storage services. | Platform Services depend on OS capabilities. |
| SAD-ASM-005 | Flutter text rendering can preserve Unicode and support bidirectional text where platform engines support it. | i18n architecture depends on platform text support. |

## 22. Architecture Glossary

| Term | Meaning |
|---|---|
| App Shell | Top-level Flutter composition root for routing, initialization, theme, localization, and adaptive layout |
| Design System | Chanora UI layer that maps Material 3 and product semantic tokens to components |
| Bridge Facade | Software boundary used by Flutter to call Rust Core and receive Rust events |
| Runtime View | Architecture view describing runtime interaction, sequence, or state behavior |
| Interface Catalog | Architectural list of software interfaces to be refined by detailed design |
| ADR | Architecture Decision Record |
| Product string | User-visible string owned by Chanora and eligible for localization |
| Server content | User/server-provided text received from a compatible voice server and displayed without translation |


## 23. Software Architecture Items

**SAD-001**: The architecture shall use a Flutter App Shell as the top-level software composition root.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Flutter App Shell
- Source SRS: SRS-144, SRS-149, SRS-151, SRS-184
- Verification method: Review, Inspection

The shell initializes routing, theme, localization, adaptive layout, platform services, and feature containers before rendering feature screens.

**SAD-002**: The architecture shall use a Chanora Design System package above Material 3.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Design System
- Source SRS: SRS-145, SRS-146, SRS-147, SRS-148, SRS-149
- Verification method: Review, Widget Test

The design system contains product tokens, Material 3 theme configuration, component themes, and product semantic mappings.

**SAD-003**: The architecture shall isolate feature screens from direct theme-token construction.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Feature Modules, Design System
- Source SRS: SRS-150
- Verification method: Static Inspection

Feature screens consume design-system APIs and components instead of creating colors, spacing, shape, or motion locally.

**SAD-004**: The architecture shall implement connection-state token mapping in the design system.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Design System
- Source SRS: SRS-146, SRS-148
- Verification method: Unit Test

Connection states such as connected, connecting, reconnecting, disconnected, and error map to product semantic tokens.

**SAD-005**: The architecture shall implement voice-state token mapping in the design system.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Design System
- Source SRS: SRS-147
- Verification method: Unit Test

Voice states such as speaking, muted, deafened, and push-to-talk active map to product semantic tokens.

**SAD-006**: The architecture shall implement latency, packet-loss, diagnostics, and error token mapping.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Design System
- Source SRS: SRS-148
- Verification method: Unit Test

Latency, packet loss, diagnostics severity, warning, and error semantics are separated from Material base colors.

**SAD-007**: The architecture shall expose tokens through Flutter theming mechanisms.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Design System
- Source SRS: SRS-149
- Verification method: Widget Test

ThemeData, ColorScheme, component themes, TextTheme, and ThemeExtension are the allowed token access mechanisms.

**SAD-008**: The architecture shall provide an Adaptive Shell that owns window-class resolution.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Flutter App Shell
- Source SRS: SRS-151, SRS-152, SRS-153, SRS-154
- Verification method: Widget Test, Integration Test

Window class is resolved once at shell level and passed into layout composition.

**SAD-009**: The architecture shall implement a compact layout branch.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Adaptive Shell
- Source SRS: SRS-152, SRS-155, SRS-156
- Verification method: Integration Test

Compact layout uses single-column content and keeps connection and voice controls visible or directly reachable.

**SAD-010**: The architecture shall implement a medium layout branch.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Adaptive Shell
- Source SRS: SRS-153, SRS-155, SRS-156
- Verification method: Integration Test

Medium layout supports side navigation or navigation rail and main content.

**SAD-011**: The architecture shall implement an expanded layout branch.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Adaptive Shell
- Source SRS: SRS-154, SRS-155, SRS-156
- Verification method: System Test

Expanded layout supports persistent panes and persistent voice controls.

**SAD-012**: The architecture shall implement a Connection Status UI component.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Components, Feature Modules
- Source SRS: SRS-155, SRS-159
- Verification method: Widget Test

Connection state is displayed with non-color-only cues.

**SAD-013**: The architecture shall implement a persistent VoiceBar component.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Components, Voice Feature
- Source SRS: SRS-156
- Verification method: Widget Test, Integration Test

VoiceBar exposes mute, deaf, push-to-talk, input level, current channel, and latency summary.

**SAD-014**: The architecture shall implement accessible semantics for critical controls.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Components, Localization
- Source SRS: SRS-157, SRS-158, SRS-159
- Verification method: Accessibility Test

Critical controls expose semantic labels and state descriptions.

**SAD-015**: The architecture shall implement keyboard focus traversal for desktop and tablet keyboard use.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Flutter UI
- Source SRS: SRS-160
- Verification method: Widget Test, System Test

Focusable components use a predictable traversal order and visible focus indication.

**SAD-016**: The architecture shall protect critical controls under increased text scaling.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Adaptive Shell, Components
- Source SRS: SRS-161
- Verification method: Accessibility Test

Shell and components are designed to avoid clipping or loss of critical actions when text scale increases.

**SAD-017**: The architecture shall centralize safe-area and inset handling.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Flutter App Shell, Platform Services
- Source SRS: SRS-162
- Verification method: Platform Test

Safe area, display cutout, system bars, keyboard, and desktop inset handling is performed through shared shell utilities.

**SAD-018**: The architecture shall model Android back behavior through platform services.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Platform Services
- Source SRS: SRS-163
- Verification method: Platform Test

Back behavior is represented as an intent handled by route and shell policy.

**SAD-019**: The architecture shall model iOS navigation, keyboard avoidance, safe area, and haptics through platform services.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Platform Services
- Source SRS: SRS-164
- Verification method: Platform Test

iOS behavior is not hardcoded in feature screens.

**SAD-020**: The architecture shall implement a Localization Service for product-owned strings.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Localization Service
- Source SRS: SRS-165, SRS-166, SRS-167, SRS-168, SRS-169
- Verification method: Unit Test, Integration Test

Product strings are loaded from localization resources with English fallback.

**SAD-021**: The architecture shall separate product localization from server-provided content.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Localization Service, Protocol DTOs, Flutter UI
- Source SRS: SRS-170
- Verification method: Integration Test

Server content is displayed as content and is not translated by the client.

**SAD-022**: The architecture shall preserve Unicode through protocol, bridge, state, and UI paths.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Protocol Adapter, Bridge, Rust Core, Flutter UI
- Source SRS: SRS-171, SRS-172
- Verification method: Integration Test

DTOs and internal state use UTF-8 compatible representations.

**SAD-023**: The architecture shall isolate non-UTF-8 conversion in boundary adapters.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Protocol Adapter, Platform Adapter, Bridge
- Source SRS: SRS-173
- Verification method: Inspection, Integration Test

Encoding conversion is not permitted in feature screens or general business logic.

**SAD-024**: The architecture shall preserve multilingual content in diagnostics except for intentional redaction.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Diagnostics, Storage
- Source SRS: SRS-174
- Verification method: Test, Audit

Diagnostic payload builders preserve Unicode values while applying redaction policy.

**SAD-025**: The architecture shall support bidirectional text where the platform text engine supports it.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Flutter UI
- Source SRS: SRS-175
- Verification method: Localization Test

Text widgets are selected and configured to allow natural bidirectional rendering.

**SAD-026**: The architecture shall centralize locale-aware formatting.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Localization Service, Diagnostics UI
- Source SRS: SRS-176
- Verification method: Localization Test

Date, time, number, and visible diagnostic timestamp formatting occurs through localization utilities.

**SAD-027**: The architecture shall keep diagnostic machine fields language-neutral.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Diagnostics, Localization Service
- Source SRS: SRS-177, SRS-178
- Verification method: Inspection, Test

Diagnostic keys and codes remain stable while display descriptions are localized.

**SAD-028**: The architecture shall maintain downstream UI/UX and design-system documentation.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: UX, Software Engineering
- Source SRS: SRS-179
- Verification method: Review

The UI/UX guideline, token guide, component catalog, adaptive layout guide, and platform guide are treated as supporting baselines.

**SAD-029**: The architecture shall enforce SRS-only source traceability for SAD.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Software Architecture
- Source SRS: SRS-180, SRS-181, SRS-182
- Verification method: Inspection

SAD items contain Source SRS and do not contain lower-layer source IDs.

**SAD-030**: The architecture shall enforce SAD-only source traceability for SDD.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Software Design
- Source SRS: SRS-183
- Verification method: Inspection

Detailed design items are derived from SAD items only.

**SAD-031**: The architecture shall initialize theme, localization, and platform services before first feature render.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Flutter App Shell
- Source SRS: SRS-184
- Verification method: Integration Test

The app shell performs initialization sequencing before rendering user-visible feature content.

**SAD-032**: The architecture shall isolate TeamSpeak-compatible protocol integration behind Rust protocol components.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Rust Core, Protocol Adapter
- Source SRS: SRS-001 through SRS-030
- Verification method: Integration Test

Protocol responsibilities remain outside Flutter feature screens.

**SAD-033**: The architecture shall isolate authoritative server state in Rust Core and state synchronization components.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Rust Core, State Sync
- Source SRS: SRS-031 through SRS-060
- Verification method: System Test

Flutter consumes state events and view models rather than mutating protocol state.

**SAD-034**: The architecture shall isolate real-time audio processing in the audio subsystem.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Audio Subsystem, Platform Audio
- Source SRS: SRS-061 through SRS-090
- Verification method: Audio Test

Capture, preprocessing, encoding, decoding, jitter buffer, and mixing are assigned to audio software components.

**SAD-035**: The architecture shall isolate local storage and secure storage behavior behind storage components.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P1 / Beta
- Allocated to: Storage, Platform Secure Storage
- Source SRS: SRS-091 through SRS-110
- Verification method: Security Test, Inspection

Storage APIs separate non-secret data from secrets.

**SAD-036**: The architecture shall isolate diagnostics and redaction behavior in diagnostics components.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P1 / Beta
- Allocated to: Diagnostics
- Source SRS: SRS-111 through SRS-124
- Verification method: Audit, Test

Logs, event capture, export, and redaction stay centralized.

**SAD-037**: The architecture shall isolate deployment, release, and packaging support in build and release assets.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P1 / Beta
- Allocated to: Build, Release, Operations
- Source SRS: SRS-125 through SRS-134
- Verification method: Inspection, Demo

Packaging and release decisions are outside feature-screen code.

**SAD-038**: The architecture shall provide verification hooks for requirements traceability and platform validation.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P1 / Beta
- Allocated to: Verification Support
- Source SRS: SRS-135 through SRS-143
- Verification method: Review, Inspection

Traceability checks and verification evidence are supported by documentation and test structure.

**SAD-039**: The architecture shall use view models as the boundary between feature screens and application state.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P1 / Beta
- Allocated to: Flutter State
- Source SRS: SRS-001 through SRS-184
- Verification method: Unit Test, Review

Feature screens receive render-ready state and issue user intents through controllers.

**SAD-040**: The architecture shall use a bridge facade as the only Flutter-to-Rust command boundary.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P1 / Beta
- Allocated to: Bridge Facade
- Source SRS: SRS-001 through SRS-184
- Verification method: Inspection, Integration Test

Flutter feature modules call bridge services rather than Rust implementation details.

**SAD-041**: The architecture shall map asynchronous Rust events into Flutter UI state updates.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P1 / Beta
- Allocated to: Bridge, Flutter State
- Source SRS: SRS-001 through SRS-184
- Verification method: Integration Test

Core event streams update UI view models deterministically.

**SAD-042**: The architecture shall define test seams for theme, localization, adaptive shell, platform services, and bridge facade.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P1 / Beta
- Allocated to: Verification Support
- Source SRS: SRS-165 through SRS-184
- Verification method: Review, Test

Test seams allow widget, integration, platform, and golden tests.

**SAD-043**: The architecture shall support light and dark theme mode behavior.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P1 / Beta
- Allocated to: Design System, Flutter App Shell
- Source SRS: SRS-157
- Verification method: Widget Test

Theme mode is controlled centrally and propagates through Material theme data.

**SAD-044**: The architecture shall allow dynamic color as an optional enhancement without overriding Chanora semantic state tokens.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P1 / Beta
- Allocated to: Design System
- Source SRS: SRS-158
- Verification method: Widget Test

Dynamic color affects base Material scheme but not product semantic safety states.

**SAD-045**: The architecture shall keep future SDD derivation independent from non-SAD requirement IDs.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P2 / Production
- Allocated to: Software Design
- Source SRS: SRS-183
- Verification method: Inspection

The SAD-to-SDD boundary is the only source path for SDD.

**SAD-046**: The architecture shall include C4-style architecture views in the SAD baseline.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P2 / Production
- Allocated to: Software Architecture
- Source SRS: SRS-182
- Verification method: Review

Context, container, component, runtime, deployment, and data views are part of the architecture baseline.

**SAD-047**: The architecture shall include ADRs for architecturally significant decisions.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P2 / Production
- Allocated to: Software Architecture
- Source SRS: SRS-182
- Verification method: Review

ADR entries document the rationale for major design decisions.

**SAD-048**: The architecture shall identify software stakeholders and architecture concerns.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P2 / Production
- Allocated to: Software Architecture
- Source SRS: SRS-182
- Verification method: Review

Stakeholder concerns guide architecture views and tradeoffs.

**SAD-049**: The architecture shall include deployment and operational architecture views.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P2 / Production
- Allocated to: Release Architecture
- Source SRS: SRS-125 through SRS-134, SRS-182
- Verification method: Review, Inspection

Deployment view covers platform-specific packaging and release architecture.

**SAD-050**: The architecture shall include diagnostics and observability architecture views.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P2 / Production
- Allocated to: Diagnostics Architecture
- Source SRS: SRS-111 through SRS-124, SRS-177, SRS-178
- Verification method: Review, Test

Diagnostics view covers logs, redaction, event keys, localization, and exports.



**SAD-051**: The architecture shall include a SWE.2 evaluation checklist covering software elements, allocation, interfaces, dynamic behavior, resource objectives, feasibility, testability, traceability, consistency, and communication.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P1 / Beta
- Allocated to: Software Architecture
- Source SRS: SRS-182
- Verification method: Review, Inspection

The checklist is used before SAD baseline approval and after architecture-affecting changes.

**SAD-052**: The architecture shall maintain an interface catalog for architecturally significant software interfaces.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Software Architecture
- Source SRS: SRS-182
- Verification method: Review, Inspection

The catalog records producers, consumers, data/message type, and error handling for each architectural interface.

**SAD-053**: The architecture shall include performance and resource views for UI responsiveness, audio latency, memory growth, reconnect, localization, and diagnostics.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P1 / Beta
- Allocated to: Software Architecture
- Source SRS: SRS-182
- Verification method: Review, Analysis

Performance and resource objectives are linked to architecture mechanisms.

**SAD-054**: The architecture shall document assumptions and dependencies that affect design feasibility.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P1 / Beta
- Allocated to: Software Architecture
- Source SRS: SRS-182
- Verification method: Review

Assumptions and dependencies are reviewed during change impact analysis.

**SAD-055**: The architecture shall include a glossary for architecture-specific terms.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P2 / Production
- Allocated to: Software Architecture
- Source SRS: SRS-182
- Verification method: Review

The glossary reduces ambiguity across architecture, detailed design, and verification activities.

**SAD-056**: The architecture shall define software interface error-handling responsibilities at the architectural level.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Software Architecture, Bridge, Rust Core, Platform Services
- Source SRS: SRS-182
- Verification method: Review, Integration Test

Each architecturally significant interface identifies error handling responsibilities.

**SAD-057**: The architecture shall explicitly support detailed design refinement of interface names, types, units, resolutions, ranges, and default values.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P1 / Beta
- Allocated to: Software Architecture, Software Design
- Source SRS: SRS-183
- Verification method: Review, Inspection

The SAD delegates detailed per-unit interface metadata to the SDD.

**SAD-058**: The architecture shall define software units as the target decomposition level for SWE.3 detailed design.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P1 / Beta
- Allocated to: Software Architecture, Software Design
- Source SRS: SRS-183
- Verification method: Review

Software components are decomposed into software units in the SDD.

**SAD-059**: The architecture shall define that SDD detail must be sufficient to support implementation and unit verification.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P1 / Beta
- Allocated to: Software Design, Verification
- Source SRS: SRS-183
- Verification method: Review, Inspection

The required SDD detail level is driven by implementation and unit verification needs.

**SAD-060**: The architecture shall require SAD and SDD changes to be communicated to relevant affected parties before downstream implementation or verification updates are treated as baseline.

- Status: Baseline
- Type: Software Architecture Item
- Stage: P1 / Beta
- Allocated to: Software Architecture, Software Design, Verification
- Source SRS: SRS-180, SRS-182, SRS-183
- Verification method: Review

Communication evidence is maintained through change history and baseline approval records.


## 24. SRS-to-SAD Coverage Matrix

| SRS Range | SAD Coverage |
|---|---|
| SRS-001 through SRS-030 | SAD-032, SAD-039, SAD-040, SAD-041 |
| SRS-031 through SRS-060 | SAD-033, SAD-039, SAD-041 |
| SRS-061 through SRS-090 | SAD-034, SAD-039, SAD-041 |
| SRS-091 through SRS-110 | SAD-035 |
| SRS-111 through SRS-124 | SAD-036, SAD-050 |
| SRS-125 through SRS-134 | SAD-037, SAD-049 |
| SRS-135 through SRS-143 | SAD-038 |
| SRS-144 through SRS-184 | SAD-001 through SAD-031, SAD-039 through SAD-060 |

## 25. Change History

| Version | Date | Description |
|---|---|---|
| 0.1.0 | 2026-05-14 | Initial SAD baseline covering SRS-001 through SRS-184 and enforcing SRS-only direct traceability. |
| 0.2.0 | 2026-05-14 | Expanded SAD into a full software architecture document with stakeholders, concerns, context/container/component/runtime/deployment/data/security/diagnostics/UI/audio/protocol/i18n views and ADRs. |
| 0.3.0 | 2026-05-14 | Added SWE.2 evaluation checklist, interface catalog, performance/resource view, assumptions/dependencies, glossary, and SDD refinement requirements. |

---

## 26. Platform Baseline and Product Decision Architecture Addendum

**SAD-061**: The software architecture shall isolate iOS runtime minimum version configuration from feature logic.

- Status: Baseline Candidate
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: iOS Build Configuration, Platform Services
- Source SRS: SRS-185
- Verification method: Platform Test, Inspection

**SAD-062**: The software architecture shall treat Apple App Store SDK compliance as a release pipeline and build configuration responsibility.

- Status: Baseline Candidate
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Release Pipeline, iOS Build Configuration
- Source SRS: SRS-186
- Verification method: Release Inspection

**SAD-063**: The software architecture shall isolate Android runtime minimum version and Play target API compliance in Android build configuration and platform services.

- Status: Baseline Candidate
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Android Build Configuration, Platform Services, Release Pipeline
- Source SRS: SRS-187, SRS-188
- Verification method: Platform Test, Release Inspection

**SAD-064**: The software architecture shall model one active connection as the MVP runtime invariant across UI, Rust Core, state synchronization, audio routing, and protocol adapter components.

- Status: Baseline Candidate
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Flutter UI, Rust Core, State Sync, Audio Subsystem, Protocol Adapter
- Source SRS: SRS-189
- Verification method: System Test, Review

**SAD-065**: The software architecture shall assign audio processing defaults and capability detection to the audio subsystem and settings presentation layer.

- Status: Baseline Candidate
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Audio Subsystem, Platform Audio, Settings UI
- Source SRS: SRS-190
- Verification method: Audio Test

**SAD-066**: The software architecture shall hide platform-native and fallback audio processing implementations behind the audio subsystem interface.

- Status: Baseline Candidate
- Type: Software Architecture Item
- Stage: P1 / Beta
- Allocated to: Audio Subsystem, Platform Audio Adapter
- Source SRS: SRS-191
- Verification method: Architecture Review, Audio Test

**SAD-067**: The software architecture shall isolate non-secret local persistence in a database repository layer and secret persistence in platform secure storage services.

- Status: Baseline Candidate
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Storage, Platform Secure Storage
- Source SRS: SRS-192
- Verification method: Storage Test, Security Audit

**SAD-068**: The software architecture shall use a stable typed bridge facade with schema-controlled DTO boundaries between Flutter and Rust.

- Status: Baseline Candidate
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Bridge Facade, Flutter State, Rust Core
- Source SRS: SRS-193
- Verification method: Integration Test, Architecture Review

**SAD-069**: The software architecture shall exclude automatic telemetry, automatic diagnostic upload, and automatic crash reporting from MVP components and release configuration.

- Status: Baseline Candidate
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Diagnostics, Privacy, Release Pipeline
- Source SRS: SRS-194
- Verification method: Privacy Review, Security Audit

**SAD-070**: The software architecture shall record the product decisions affecting platform baselines, connection scope, audio defaults, audio implementation path, storage, bridge, diagnostics, and crash reporting in the ADR and decision baseline.

- Status: Baseline Candidate
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Software Architecture, Documentation Control
- Source SRS: SRS-185 through SRS-194
- Verification method: Review, Inspection

**SAD-071**: The software architecture shall isolate desktop PTT into a `DesktopPttBackend` trait owned by the audio subsystem, with the active implementation selected at runtime by a `platform_input::select` factory. Only the factory and the audio engine know which implementation is active; the rest of the application sees only the trait surface and the published capability level.

- Status: Baseline Candidate
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Audio, Platform Input
- Source SRS: SRS-195
- Verification method: Architecture Review, Unit Test

**SAD-072**: The Windows PTT backend shall be a three-level ladder (`WindowsRawInputBackend` -> `WindowsHookBackend` -> `FocusedPttBackend`). The ladder is evaluated once at audio-engine start; the chosen rung is fixed for the lifetime of that engine and is reported as the backend identifier.

- Status: Baseline Candidate
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Audio (Windows)
- Source SRS: SRS-197
- Verification method: Platform Test (Windows), Architecture Review

**SAD-073**: The macOS PTT backend shall be a two-level ladder (`MacOSEventTapBackend` -> `FocusedPttBackend`) with explicit permission state surfaced through `PttCapabilityLevel`. The permission query shall not block the audio-engine start path; an undecided permission shall resolve to `L0` and may upgrade asynchronously when the user grants the permission.

- Status: Baseline Candidate
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Audio (macOS)
- Source SRS: SRS-198
- Verification method: Platform Test (macOS), Architecture Review

**SAD-074**: The Linux PTT backend shall be a two-level ladder (`LinuxGnomeWaylandBackend` using the freedesktop `org.freedesktop.portal.GlobalShortcuts` interface, -> `FocusedPttBackend`). Untested display servers, untested compositors, and missing D-Bus access shall all resolve to `L0`.

- Status: Baseline Candidate
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Audio (Linux)
- Source SRS: SRS-199
- Verification method: Platform Test (Linux, GNOME Wayland), Architecture Review

**SAD-075**: The audio engine shall expose `AudioTransmitGate`, a thin object that owns the `transmit_active` AtomicBool and exposes `set` and `load` operations only. The Opus encoder feed shall consult `AudioTransmitGate::load()` once per outbound frame; no other code path may flip `transmit_active`.

- Status: Baseline Candidate
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Audio
- Source SRS: SRS-201
- Verification method: Unit Test, Audio Test

**SAD-076**: The bridge shall expose PTT events through the existing `BridgeEvent` stream, adding a `BridgeEvent::PttCapability { level, backend_id }` variant. The bridge shall never carry raw key codes or scan codes across the FFI boundary; the trait surface and the event shape together enforce SRS-202 at the architectural layer.

- Status: Baseline Candidate
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Bridge, Audio, Diagnostics
- Source SRS: SRS-202
- Verification method: Architecture Review, Privacy Review

**SAD-077**: The diagnostics subsystem shall add a `PttSanitizer` decorator over the `RedactingLogLayer` log sink. The decorator shall scan each record's field set for the well-known names `key_code`, `scan_code`, `virtual_key`, `vk`, `keysym`, `keysym_string`, `key_sequence` and drop the record before it reaches storage.

- Status: Baseline Candidate
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Diagnostics
- Source SRS: SRS-202
- Verification method: Unit Test, Privacy Review

**SAD-078**: The Flutter UI shall consume `BridgeEvent::PttCapability` and render a small capability badge in the Voice Bar. When the capability resolves to `L0` on a platform that the user reasonably expected to support Global PTT (for example Windows or macOS with the relevant permission undecided), the UI shall render an explanation row pointing to the corresponding fix (run-as-administrator path, permission grant path, environment-not-supported note).

- Status: Baseline Candidate
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Flutter UI
- Source SRS: SRS-196, SRS-198
- Verification method: UI Review, User Acceptance Test

**SAD-079**: The audio engine shall own the missed-key-up watchdog as a single tokio task that subscribes to `transmit_active` transitions through a `tokio::sync::watch` channel; on a configured timeout (default 30 s, owner-tunable) without a release event, the task shall clear `transmit_active` and emit a sanitised diagnostic record.

- Status: Baseline Candidate
- Type: Software Architecture Item
- Stage: P0 / MVP
- Allocated to: Audio
- Source SRS: SRS-203
- Verification method: Unit Test, Integration Test

## 27. Updated SRS-to-SAD Coverage Matrix

| SRS Range | SAD Coverage |
|---|---|
| SRS-001 through SRS-184 | Covered by inherited SAD baseline `SAD-001` through `SAD-060` |
| SRS-185 through SRS-194 | Covered by `SAD-061` through `SAD-070` |
| SRS-195 through SRS-203 | Covered by `SAD-071` through `SAD-079` |


## 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 software-architecture items SAD-071 through SAD-079: backend isolation behind `DesktopPttBackend` trait, Windows three-rung ladder, macOS two-rung permission-aware ladder, Linux GNOME-Wayland portal ladder, `AudioTransmitGate` object, sanitised `BridgeEvent::PttCapability`, `PttSanitizer` log-sink decorator, UI capability badge with platform-specific explanation, missed-key-up watchdog task. Strict layered sourcing preserved (`SAD -> SRS` only). |