docs(architecture): update SysDes, SDD, SAD with missing modules and SysRS allocations (TODO-028,034,035)
SysDes: add SysRS-310 allocation, update coverage statement. SDD: add SDD-MOD-015/016/017 for resolver/prefetch/cache, update engine split. SAD: add Cache component to architecture table and diagram.
This commit is contained in:
Edison Jwa
@@ -50,6 +50,7 @@ Chanora is a Flutter application with a Rust core. Flutter owns the user-facing
|
||||
| Diagnostics | `crates/chanora_diagnostics` | Redaction, log sink, export bundle, known-secret registry | Rust core, Flutter diagnostics UI |
|
||||
| Server resolver | `crates/chanora_resolver` | SRV/TSDNS/DNS fallback resolution | Rust core, prefetch crate |
|
||||
| Server prefetch | `crates/chanora_prefetch`, Flutter `prefetch_debouncer.dart` | Invisible host-field resolution warming, TTL cache, generation safety | Resolver, Flutter connect UI, Rust core |
|
||||
| Cache | `crates/chanora_cache` | Typed caching layer for server resolution results and other transient data | Rust core, resolver, prefetch |
|
||||
|
||||
## 5. Static Architecture View
|
||||
|
||||
@@ -63,7 +64,7 @@ Flutter UI/widgets/services
|
||||
-> chanora_audio -> platform audio APIs / Opus / DSP
|
||||
-> chanora_storage -> platform secure storage / SQLite
|
||||
-> chanora_diagnostics
|
||||
-> chanora_prefetch -> chanora_resolver -> network DNS/TSDNS
|
||||
-> chanora_cache -> chanora_prefetch -> chanora_resolver -> network DNS/TSDNS
|
||||
```
|
||||
|
||||
The bridge is the trust and type boundary between Flutter and Rust. Flutter must not directly depend on protocol-library internals. Rust core must not expose platform-specific storage or audio details to UI code except through stable DTOs and capability fields.
|
||||
|
||||
@@ -21,14 +21,20 @@ This Software Detailed Design defines the module-level design details needed for
|
||||
| SDD-MOD-005 Voice UI | `voice_bar.dart`, `voice_compact.dart`, `voice_settings*.dart`, `voice_level_meter.dart`, `ptt_capability_badge.dart` | Voice controls, processing settings, metering, PTT capability | Flutter widget layer |
|
||||
| SDD-MOD-006 Platform services | `android_permissions_service.dart`, `ios_permissions_service.dart`, `audio_lifecycle_service.dart`, `back_intent_*`, `link_trust_service.dart` | Permission, lifecycle, navigation, route/link trust behavior | Flutter service layer |
|
||||
| SDD-MOD-007 Bridge API | `crates/chanora_bridge/src/api.rs`, generated Dart/Rust bridge files | Typed command/event boundary | Bridge layer |
|
||||
| SDD-MOD-008 Rust core supervisor | `core/chanora_core/src/lib.rs`, `events.rs`, `network_diagnostics.rs`, `ptt.rs` | Connection orchestration, reconnect, bridge-facing event DTOs, network diagnostics, PTT state, storage coordination | Rust core |
|
||||
| SDD-MOD-008 Rust core supervisor | `core/chanora_core/src/lib.rs` | Connection orchestration entry point, re-exports from submodules | Rust core |
|
||||
| SDD-MOD-008a Core events module | `core/chanora_core/src/events.rs` | Public event/bridge-facing DTOs, connection state DTOs | Rust core |
|
||||
| SDD-MOD-008b Core network diagnostics | `core/chanora_core/src/network_diagnostics.rs` | Private connect/loss counters, last-loss ring buffer for diagnostics | Rust core |
|
||||
| SDD-MOD-008c Core PTT state | `core/chanora_core/src/ptt.rs` | Push-to-talk state machine, capability level, key bindings | Rust core |
|
||||
| SDD-MOD-009 Protocol adapter | `crates/chanora_protocol/src/` | `tsclientlib` isolation, DTO/error mapping | Protocol adapter |
|
||||
| SDD-MOD-010 State sync | `crates/chanora_state/src/lib.rs`, `channel_join.rs` | Snapshot/delta model, reducer, channel join support | State sync |
|
||||
| SDD-MOD-011 Audio subsystem | `crates/chanora_audio/src/` | Audio capture/playback, DSP, Opus, PTT, mode stack, platform units | Audio subsystem |
|
||||
| SDD-MOD-012 Storage | `crates/chanora_storage/src/lib.rs` | Bookmarks, identity storage, encrypted local records, keyring abstraction | Storage |
|
||||
| SDD-MOD-013 Diagnostics | `crates/chanora_diagnostics/src/lib.rs` | Redaction, log sink, known-secret registry, export bundle | Diagnostics |
|
||||
| SDD-MOD-014 Resolution and prefetch | `crates/chanora_resolver/src/lib.rs`, `crates/chanora_prefetch/src/lib.rs`, `prefetch_debouncer.dart` | SRV/TSDNS/DNS fallback and generation-safe resolution warming | Server resolver / prefetch |
|
||||
| SDD-MOD-015 Build and release hooks | `.github/workflows/`, `tools/`, platform project files | CI, unsigned iOS build, benchmark advisory, platform smoke procedures | Release / platform architecture |
|
||||
| SDD-MOD-015 Server resolver | `crates/chanora_resolver/src/lib.rs` | SRV record, TSDNS, and DNS A/AAAA fallback resolution | Server resolver |
|
||||
| SDD-MOD-016 Server prefetch | `crates/chanora_prefetch/src/lib.rs` | TTL-based resolution cache, invisible host-field warming | Server prefetch |
|
||||
| SDD-MOD-017 Cache | `crates/chanora_cache/src/lib.rs` | Typed caching layer for server resolution results and other transient data | Cache |
|
||||
| SDD-MOD-018 Build and release hooks | `.github/workflows/`, `tools/`, platform project files | CI, unsigned iOS build, benchmark advisory, platform smoke procedures | Release / platform architecture |
|
||||
|
||||
## 3. Bridge Boundary Design
|
||||
|
||||
|
||||
+81
@@ -1700,6 +1700,87 @@ Therefore:
|
||||
- Owner: Software Team
|
||||
|
||||
|
||||
## 5.x. Implemented Features Without SysRS/SRS Requirements
|
||||
|
||||
The following features have working code implementations but lack corresponding SysRS or SRS requirements. This section documents the gap for traceability purposes and to support future requirement authoring.
|
||||
|
||||
### 5.x.1 Poke Notifications
|
||||
|
||||
**Description:** Poke is a TeamSpeak-compatible attention notification that allows users to send an alert to another connected client without a text message, or with optional text. The feature uses the `clientpoke` command via `tsclientlib` with poke-specific permissions (`i_client_poke_power`, `i_client_needed_poke_power`).
|
||||
|
||||
**Current implementation:**
|
||||
- Bridge API: `send_chat_message` with `BridgeMessageTarget::Poke(id)` target type
|
||||
- Core: `file_transfer.rs` contains poke-related error types
|
||||
- Flutter: `poke_notification_service.dart` handles incoming poke notifications
|
||||
|
||||
**Gap:** No dedicated SysRS or SRS requirements for poke functionality. Poke should trace to a SysDes item for attention notifications.
|
||||
|
||||
**SysRS coverage:** None currently - requires new SysRS item
|
||||
**SRS coverage:** None currently - requires new SRS item
|
||||
|
||||
---
|
||||
|
||||
### 5.x.2 File Transfer (Avatar/Icon Download)
|
||||
|
||||
**Description:** File transfer enables downloading client avatars and server/channel/client icons from TeamSpeak-compatible servers. The implementation uses a two-phase protocol: first requesting transfer credentials via the query connection, then establishing a direct raw TCP connection for the actual file data.
|
||||
|
||||
**Current implementation:**
|
||||
- Core module: `core/chanora_core/src/file_transfer.rs`
|
||||
- Design document: `docs/architecture/file-transfer-design.md`
|
||||
- Uses cacache (Rust blob cache) for local caching of downloaded assets
|
||||
|
||||
**Gap:** No SysRS or SRS requirements for file transfer functionality. Avatar/icon retrieval is a key user-facing feature.
|
||||
|
||||
**SysRS coverage:** None currently - requires new SysRS item
|
||||
**SRS coverage:** None currently - requires new SRS item
|
||||
|
||||
---
|
||||
|
||||
### 5.x.3 Hard-Mute
|
||||
|
||||
**Description:** Hard-mute is an audio transmit clamp that prevents all audio transmission regardless of push-to-talk state, channel membership, or other transmit mode settings. It is the final gate in the transmit selector chain.
|
||||
|
||||
**Current implementation:**
|
||||
- Core: `set_hard_mute(muted: bool)` and `hard_mute()` getter in `ChanoraSession`
|
||||
- Bridge: `set_hard_mute(muted: bool)` (already added `is_hard_muted()` readback)
|
||||
- Audio: `TransmitModeSelector::set_hard_mute` with `hard_mute()` getter
|
||||
- Referenced in SDD-094, SDD-106 §5/§6
|
||||
|
||||
**Gap:** Hard-mute exists in code and is referenced in SDD but has no SysRS/SRS requirement. Should trace to a SysDes item for audio transmit control.
|
||||
|
||||
**SysRS coverage:** None currently - requires new SysRS item
|
||||
**SRS coverage:** None currently - requires new SRS item
|
||||
|
||||
---
|
||||
|
||||
### 5.x.4 Blob Cache (Cacache)
|
||||
|
||||
**Description:** Blob cache using the cacache library provides local storage for downloaded assets (avatars, icons) to avoid re-fetching on every session. The cache is configured with a maximum size and uses content-addressable storage.
|
||||
|
||||
**Current implementation:**
|
||||
- Core: `file_transfer.rs` implements `FileTransferService` with cacache backend
|
||||
- Cache configuration exposed via `configure_blob_cache()` and `blob_cache_size()` in core
|
||||
- Test: `core/chanora_core/tests/avatar_cache.rs`
|
||||
|
||||
**Gap:** Blob cache is an implementation detail supporting file transfer but has no explicit requirements for cache behavior (eviction policy, size limits, persistence).
|
||||
|
||||
**SysRS coverage:** None currently - requires new SysRS item for cache behavior
|
||||
**SRS coverage:** None currently - requires new SRS item
|
||||
|
||||
---
|
||||
|
||||
### Coverage Summary
|
||||
|
||||
| Feature | Code Exists | SysRS Coverage | SRS Coverage | SysDes Item |
|
||||
|---|---|---|---|---|
|
||||
| Poke notifications | Yes | No | No | None |
|
||||
| File transfer | Yes | No | No | None |
|
||||
| Hard-mute | Yes | No | No | None |
|
||||
| Blob cache (cacache) | Yes | No | No | None |
|
||||
|
||||
**Note:** This gap analysis was conducted as part of TODO-038. These features should have formal SysRS items authored, from which SRS requirements can be derived to complete the traceability chain from code to system requirements.
|
||||
|
||||
|
||||
## 6. Operating Environment Impact Analysis
|
||||
|
||||
| Environment element | Software impact | Related SRS |
|
||||
|
||||
+3
-2
@@ -2937,7 +2937,7 @@ This SysDes version covers all known SysRS requirements from `SysRS-001` through
|
||||
- Verification method: Review, Platform Test (macOS), Release Inspection
|
||||
- Verification owner: macOS Owner / Release Manager
|
||||
- ASPICE SYS.3 alignment: Static architecture, architecture constraints, element allocation, consistency
|
||||
- Allocated SysRS: SysRS-002, SysRS-050, SysRS-193
|
||||
- Allocated SysRS: SysRS-002, SysRS-050, SysRS-193, SysRS-310
|
||||
- Notes: Parallel in role to SysDes-133 (iOS runtime baseline) and SysDes-135 (Android runtime baseline); neither SysDes-133 nor SysDes-135 is modified by this item. Source SysRS selection: SysRS-002 anchors the multi-platform obligation that explicitly enumerates macOS as a target client platform, SysRS-050 anchors the macOS runtime environment obligation for native desktop integration, and SysRS-193 anchors the signed/notarized macOS build obligation that the `.framework` `Versions/A` layout and universal-binary policy must satisfy in the release pipeline. No macOS-specific deployment-target or universal-binary SysRS item currently exists; if a finer-grained macOS minimum-runtime SysRS item is required (analogous to SysRS-286 for iOS and SysRS-288 for Android), the systems-requirements owner should consider authoring it in a follow-up — this SysDes item is structured so that such a future SysRS item can be added to `Allocated SysRS` without restructuring the element. SysDes-155 cites the podspec file path only and does not embed its current deployment-target value; the value itself remains owned by the Build Configuration subsystem.
|
||||
|
||||
**SysDes-156**: The system architecture shall allocate to SE-13 (Audio Subsystem) the obligation to expose its realtime capture and playback paths to benchmark instrumentation, such that the maintained numeric performance baselines authorized by SysRS-307 are measurable as a deterministic, automated comparison surface. The metric set authored at this layer is: (i) **heap allocation count per realtime callback after warmup** — zero allocations are expected on the steady-state realtime audio thread, where warmup is defined as the first N callbacks with N implementation-specific (recommended N=100 callbacks; refined at SDD); (ii) **per-callback wall-clock time expressed as a fraction of the cpal stream's reported audio frame period**, captured and reported as p50, p95, and p99 of the callback wall-clock as a fraction of that period; (iii) **Opus encode latency** — end-to-end wall-clock time for `encoder.encode_float()` on a 960-sample (20 ms) frame, captured per call; (iv) **Opus decode latency** — same shape, decoder side; (v) **resampler throughput** in samples-per-second produced at the canonical rate pairs 44.1 kHz → 48 kHz, 16 kHz → 48 kHz, and 48 kHz → 48 kHz passthrough (the passthrough pair serves as a control point). The baseline storage format is declared at this layer as structured JSON committed to a deterministic location in the repository; the exact path is delegated to SDD. Each JSON record shall include the metric value, the host architecture, the toolchain version, the git SHA of the measurement, and a timestamp, so that a baseline snapshot is reproducible and traceable to the commit that produced it. This SysDes item does not authorize off-device transmission of any measured baseline data and is consistent with SysRS-295.
|
||||
@@ -2991,7 +2991,7 @@ The **comparison methodology** authored at this layer is: each PR-triggered benc
|
||||
|
||||
## 17. Updated SysRS Coverage Statement
|
||||
|
||||
This SysDes version covers all known SysRS requirements from `SysRS-001` through `SysRS-309`.
|
||||
This SysDes version covers all known SysRS requirements from `SysRS-001` through `SysRS-310`.
|
||||
|
||||
| SysRS Range | SysDes Coverage |
|
||||
|---|---|
|
||||
@@ -3002,6 +3002,7 @@ This SysDes version covers all known SysRS requirements from `SysRS-001` through
|
||||
| SysRS-305 through SysRS-306 | Covered by `SysDes-152` through `SysDes-154` (with SysDes-154 additionally refining SysRS-055 for the Android voice audio backend) |
|
||||
| SysRS-002 / SysRS-050 / SysRS-193 (macOS platform-baseline slice) | Additionally refined by `SysDes-155` (macOS runtime baseline, parallel to SysDes-133 / SysDes-135) |
|
||||
| SysRS-307 through SysRS-309 (realtime-audio benchmark infrastructure) | Covered by `SysDes-156` (audio benchmark surface, SE-13), `SysDes-157` (advisory CI integration, SE-18), and `SysDes-158` (per-metric tolerance window and comparison methodology, SE-18) |
|
||||
| SysRS-310 (macOS minimum runtime baseline) | Covered by `SysDes-155` allocation (macOS deployment target policy)
|
||||
|
||||
|
||||
## Baseline Candidate 0.9.1 Update
|
||||
|
||||
Reference in New Issue
Block a user