Chanora

Chanora is a cross-platform voice communication client for TeamSpeak-compatible servers.

It is built with a shared Flutter UI and a Rust core, with TeamSpeak-compatible protocol integration isolated behind tsclientlib.

Flutter UI + Rust Core + tsclientlib

Chanora is an independent project and is not affiliated with, endorsed by, sponsored by, or officially associated with TeamSpeak.

---

Status

Chanora is currently a baseline-candidate Flutter + Rust workspace. It is not production-ready and is not approved for public or store release.

Current documentation baseline: v0.9.x document set
Current status: Baseline Candidate
Implementation status: Not production-ready

The current engineering focus is:

• defining the system and software architecture;
• hardening the Flutter + Rust application structure;
• validating TeamSpeak-compatible protocol integration through tsclientlib;
• defining cross-platform audio behavior;
• preparing release, verification, security, privacy, and legal gates.

---

Target Platforms

Chanora is intended to support:

• Windows
• macOS
• Linux
• Android
• iOS / iPadOS

Current platform policy:

Platform	Baseline
iOS / iPadOS runtime target	iOS 16+ while Apple CoreML Silero VAD is linked
macOS runtime target	macOS 13+ while Apple CoreML Silero VAD is linked
App Store Connect upload gate	Xcode 26+ with iOS 26 / iPadOS 26 SDK+ for upload on or after 2026-04-28
Android runtime target	Android API 28+ per DEC-004, SysRS-288, SRS-187, and Gradle minSdk = 28
Google Play target API	Target the Google Play-required API level on upload date

The App Store / Play Store upload gates are release requirements. They are separate from local development and internal testing requirements.

Apple CoreML VAD development requires the private silero-coreml SwiftPM package checked out as a sibling of this repository, so the app checkout and package checkout share the same parent directory:

workspace/
  chanora/
  silero-coreml/

The iOS and macOS Xcode projects reference that package via ../../../../silero-coreml from their project files. GitHub CI skips the unsigned iOS build when the sibling package is unavailable, but local Apple builds need that checkout.

---

Architecture Overview

Chanora separates UI, protocol logic, state synchronization, audio processing, diagnostics, and platform services.

Flutter Application
  ├─ App Shell
  ├─ Material 3 / Chanora Design System
  ├─ Feature Modules
  ├─ View Models / State
  └─ Typed Flutter/Rust Bridge

Rust Core
  ├─ Connection Manager
  ├─ State Synchronization
  ├─ Protocol Adapter
  ├─ Audio Subsystem
  ├─ Storage Services
  └─ Diagnostics

Protocol Layer
  └─ tsclientlib
      └─ TeamSpeak-compatible server

Key architecture rules:

• Flutter does not call tsclientlib directly.
• Protocol-specific types do not leak into the Flutter UI layer.
• Rust Core owns protocol coordination, state synchronization, audio logic, storage services, diagnostics, and bridge-facing DTOs.
• Flutter owns presentation, navigation, Material 3 theming, accessibility, localization presentation, and platform UI behavior.
• Product localization and server-provided content are separated.
• UTF-8 is the internal cross-layer text representation.
• Non-UTF-8 conversion, if needed, occurs only at explicit protocol or platform boundaries.

---

MVP Direction

The current recommended MVP scope is:

Area	MVP decision
Active server connections	One active server connection per client instance
UI baseline	Material 3 + Chanora Design System
Product language	English UI first, i18n-ready architecture
Server content	Preserve Unicode and do not translate server-provided content
Audio processing defaults	Echo Canceller, Automatic Gain Control, Noise Suppression, and High-Pass Filter enabled where supported and stable
Audio implementation path	Platform-native first; fallback isolated behind the audio subsystem
Local non-secret storage	SQLite or equivalent embedded database
Secret storage	Platform secure storage
Flutter/Rust bridge	Stable typed bridge with generated or schema-controlled DTOs
Diagnostics	Local, user-initiated export only
Telemetry	None in MVP
Crash reporting	Disabled unless explicitly approved later

---

Desktop Push-to-Talk

Chanora's desktop Push-to-Talk (PTT) follows a capability-based design (see docs/architecture/desktop-ptt-architecture.md). Focused PTT — the user holds a bound key or mouse button inside the focused Chanora window — is mandatory on Windows, macOS, and Linux. Global PTT (recognised while the application is not focused) is capability-dependent: it requires the operating system, the user-granted permission set, the display server, and the available input backend to all permit it.

The application reports a PttCapabilityLevel (L0Focused, L1GlobalShortcut, L2GlobalHoldToTalk, L3GlobalWithMouseButtons) that matches actual runtime behaviour, not the platform's theoretical maximum. The UI capability badge shows the live value.

Per-platform strategy (resolved by owner rulings 2026-05-15, see docs/governance/product-decision-register.md DEC-023 through DEC-028):

• Windows — Raw Input first, low-level keyboard hook fallback, Focused PTT terminal fallback. Mouse side buttons supported. P0 / MVP.
• macOS — permission-aware Event Tap with Focused PTT fallback; Global PTT upgrades asynchronously when the user grants Input Monitoring / Accessibility. P0 / MVP.
• Linux — officially tested on GNOME on Wayland using the org.freedesktop.portal.GlobalShortcuts interface; every other Linux environment falls back to Focused PTT. Release notes do not claim Global PTT support outside the tested compositor.
• Raw key codes, scan codes, virtual-key values, keysyms, and key-press timing sequences are never logged or included in the user-initiated diagnostic export. The diagnostic export carries only capability level, backend identifier, and bound input class.

A missed-key-up watchdog (default 30 s) clears transmit_active when the OS suppresses a key-up event so a stuck-PTT bug class is ruled out by construction.

Repository Layout

The repository documentation is expected to live under docs/.

docs/
  requirements/
    sysrs.md
    srs.md

  architecture/
    sysdes.md
    sad.md
    sdd.md

  verification/
    verification-master-plan.md
    swe4-unit-verification-plan.md
    swe5-software-integration-verification-plan.md
    swe6-software-verification-plan.md
    sys4-system-integration-verification-plan.md

  release/
    release-readiness-go-nogo-record.md
    platform-release-policy.md

  security/
    security-privacy-legal-guideline.md
    threat-model.md
    secure-storage-audit-report.md
    diagnostic-redaction-audit-report.md
    dependency-and-supply-chain-report.md

  privacy/
    privacy-policy.md

  legal/
    trademark-and-attribution-review.md

  ui-ux/
    material3-guideline.md
    material3-design-tokens.md
    material3-component-catalog.md
    adaptive-layout-platform-guide.md

  i18n/
    localization-architecture.md

  governance/
    document-index.md
    document-naming-convention.md
    traceability-matrix.md
    baseline-approval-record.md
    baseline-candidate-validation-report.md
    document-review-report.md
    product-decision-register.md
    decision-impact-assessment.md
    git-commit-message-convention.md
    repo-format-validation-report.md
    path-migration-map.md

  references/
    external-references.md
    aspice-swe2-swe3-integration-note.md

Implementation source folders are present in this workspace. The current high-level structure is:

apps/
  chanora_flutter/

core/
  chanora_core/

crates/
  chanora_protocol/
  chanora_audio/
  chanora_state/
  chanora_storage/
  chanora_diagnostics/
  chanora_bridge/

The exact implementation layout may continue to evolve as maintainability reviews split or merge Modules, but the repository scaffold exists.

---

Documentation Entry Points

Start here:

Topic	Document
System requirements	docs/requirements/sysrs.md
Software requirements	docs/requirements/srs.md
System architecture	docs/architecture/sysdes.md
Software architecture	docs/architecture/sad.md
Software detailed design	docs/architecture/sdd.md
Verification strategy	docs/verification/verification-master-plan.md
Release readiness	docs/release/release-readiness-go-nogo-record.md
Platform release policy	docs/release/platform-release-policy.md
Product decisions	docs/governance/product-decision-register.md
Traceability	docs/governance/traceability-matrix.md
Security/privacy/legal gates	docs/security/security-privacy-legal-guideline.md

---

Engineering Process

Chanora follows this documentation hierarchy:

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

Direct traceability rules:

Document	Direct upstream source
SysDes	SysRS
SRS	SysDes only
SAD	SRS only
SDD	SAD only

Verification mapping:

SDD -> SWE.4 Unit Verification
SAD + SDD -> SWE.5 Software Integration Verification
SRS -> SWE.6 Software Verification
SysDes -> SYS.4 System Integration Verification

Release readiness is tracked separately through the Go/No-Go record.

---

Release Readiness

A release is not approved by design documents alone.

Before an external or public release, the project must complete:

docs/release/release-readiness-go-nogo-record.md

The release decision must explicitly state:

Go
Conditional Go
No-Go

Release readiness must include:

• release scope;
• build number;
• commit SHA;
• Git tag;
• artifact hashes;
• satisfied P0/MVP requirements;
• deferred requirements;
• verification results;
• waivers;
• security review status;
• platform readiness;
• legal and OSS review status;
• privacy policy status;
• approval decision and approvers.

---

Security, Privacy, and Legal Gates

Security, privacy, and legal evidence are required before public or store release.

Required documents include:

docs/security/threat-model.md
docs/security/secure-storage-audit-report.md
docs/security/diagnostic-redaction-audit-report.md
docs/security/dependency-and-supply-chain-report.md
docs/privacy/privacy-policy.md
docs/legal/trademark-and-attribution-review.md

Important gates:

• identity secrets and server passwords must use platform secure storage;
• logs and diagnostic exports must redact secrets;
• diagnostic export must be user-initiated unless a later approved policy changes this;
• dependency licenses and vulnerabilities must be reviewed;
• OSS notices must be prepared where required;
• public wording must not imply official TeamSpeak affiliation;
• privacy policy must describe local storage, diagnostics, permissions, and data handling.

---

Git Commit Convention

Chanora uses a Conventional Commits style format:

<type>(<scope>): <summary>

Examples:

feat(voice): add push-to-talk state handling
fix(protocol): recover channel tree after reconnect snapshot
docs(sad): add interface catalog and performance view
i18n(ui): add fallback behavior for missing localization keys
sec(diagnostics): redact server password from export bundle
release(android): prepare internal alpha build metadata

See:

docs/governance/git-commit-message-convention.md

---

Development

Common local commands include:

flutter pub get
flutter test
cargo test
cargo clippy
cargo fmt

Android runtime success also requires an available Android NDK toolchain and an authorized device or emulator for build/install/smoke verification.

---

Contributing

Before making a change:

1. Check the affected requirement/design document.
2. Confirm the correct traceability layer.
3. Use the Git commit convention.
4. Update docs and verification plans when the change affects requirements, architecture, detailed design, release behavior, security, privacy, or legal gates.

---

License

Chanora is dual-licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)

at your option. This dual-license model was Accepted on 2026-05-14 as decision DEC-020 in docs/governance/product-decision-register.md.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Chanora by you, as defined in the Apache-2.0 license, shall be dual-licensed as above, without any additional terms or conditions.

Third-party software bundled or linked by Chanora is listed in NOTICE with its own licenses. The complete legal review of the dependency tree (DEC-012) must complete before any public/store release. See:

docs/governance/product-decision-register.md
docs/security/dependency-and-supply-chain-report.md
docs/legal/trademark-and-attribution-review.md