# 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

## 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` |


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