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:

SysRS -> SysDes -> SRS -> SAD -> SDD

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

Rules:

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

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

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

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

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

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

8.4 Outgoing voice

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

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

8.6 Product-localized text rendering

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

8.7 Server-content rendering

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

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.