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

```text
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 in early planning and baseline-candidate design.

```text
Current documentation baseline: v0.9.2
Current status: Baseline Candidate
Implementation status: Not production-ready
```

The current engineering focus is:

- defining the system and software architecture;
- preparing 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 13+ unless Flutter, plugin, audio, or product constraints require raising it |
| 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 24+ unless Flutter, plugin, audio, or product constraints require raising it |
| 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.

---

## Architecture Overview

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

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

---

## Repository Layout

The repository documentation is expected to live under `docs/`.

```text
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 may be added later. A likely structure is:

```text
apps/
  chanora_flutter/

core/
  chanora_core/

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

The exact implementation layout should be finalized when the repository scaffold is created.

---

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

```text
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:

```text
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:

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

The release decision must explicitly state:

```text
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:

```text
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:

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

Examples:

```text
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:

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

---

## Development

Implementation commands will be added after the repository scaffold is finalized.

Expected future commands may include:

```bash
flutter pub get
flutter test
cargo test
cargo clippy
cargo fmt
```

Do not treat these as authoritative until the actual Flutter/Rust workspace has been created.

---

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

TBD.

The license model must be confirmed before public release. See:

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