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

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

1297 lines
46 KiB
Markdown
Raw Blame History

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