voice-cat/docs/tech-stack.md

Tech Stack & Dependencies

Concrete library choices with versions and rationale. Everything in the core is C++ (C++20). UIs are Swift and C#. Build is CMake + vcpkg.

1. Core library (libvoicecat, C++20)

Concern	Choice	Version (as of 2026-06)	Why / notes
Sockets, timers, async	Standalone Asio	1.30.x	Header-only, no Boost dependency, cross-platform TCP+UDP+timers, one reactor for client and server. (Boost.Asio is interchangeable if we already pull Boost.)
TLS 1.3 (control)	mbedTLS 3.6 LTS	3.6.x (LTS ≥ Mar 2027)	Apache-2.0 (permissive — clean for eventual closed-source distribution). TLS 1.3 client+server, plus mbedtls_ssl_export_keying_material() to seed the media AEAD. Static-links cleanly → single self-host binary. OpenSSL 3.x (Apache-2.0) is an interchangeable alternative. No DTLS/wolfSSL (GPL) — see security.md §2.
Crypto primitives + password hashing + media AEAD	libsodium	1.0.20	ISC. Argon2id (crypto_pwhash), ChaCha20-Poly1305 (per-frame media encryption), Ed25519 server identity, X25519, CSPRNG. Audited, hard to misuse.
Audio codec	libopus	1.6 (2025-12)	Per-channel mono/stereo, bitrate, frame size; in-band FEC, DTX, PLC, and optional DRED deep redundancy; Opus HD/96 kHz available. The whole reason the design is codec-flexible.
Audio capture/playback	miniaudio	0.11.x	Single-header, public-domain, backends for WASAPI / CoreAudio / ALSA / PulseAudio. One real-time abstraction across all desktop targets; keeps the RT path identical.
Audio DSP — AEC/NS/AGC/VAD	webrtc-audio-processing (APM) — planned, not built	1.x (standalone APM)	BSD-3, but has no working Windows/MSVC build upstream (GCC-only Meson, MinGW support unfinished, hard abseil-cpp dep — see roadmap.md §2). v1 ships a lightweight, dependency-free energy/RMS VAD instead (core/src/audio/apm_processor.cpp); there is no AEC, NS, or AGC implementation at all yet. Real APM stays a tracked future swap behind the same ApmProcessor interface.
Resampling + jitter ref	speexdsp	1.2.x	BSD. Resampler for non-48 kHz devices; lightweight jitter-buffer reference. (No longer the NS/AGC/VAD source — APM replaces it.)
Control serialization	Protocol Buffers (protobuf-lite)	5.x (proto3)	Codegen for C++/C#/Swift; additive, forward/backward compatible; oneof envelopes. nanopb is a fallback if footprint matters.
Server persistence	SQLite	3.4x	Accounts, channels, bans, config. Zero-admin, single file, ships everywhere.
Logging	spdlog	1.14.x	Fast, async-capable; off the RT path.

Resampling note: Opus runs internally at 48 kHz; miniaudio can deliver 48 kHz directly, so explicit resampling (speexdsp/libsamplerate) is only needed when a device can't do 48 kHz.

2. Clients

macOS / iOS — Swift

Concern	Choice	Notes
Language	Swift 5.9+	Direct Swift↔C++ interop available, but we bind through the C ABI for parity with Windows.
UI	SwiftUI	Single UI codebase for macOS + iOS where practical; AppKit/UIKit shims as needed.
Audio session (iOS)	AVAudioSession	App owns category .playAndRecord + .voiceChat mode, mic permission, interruption/route-change handling; calls vc_audio_suspend/resume on the core. macOS uses CoreAudio via the core directly.
Packaging	Swift Package + Xcode project	Core shipped as an XCFramework (device + simulator + macOS slices).
Future	CallKit / PushKit	For background VoIP + incoming-call UX on iOS. Post-v1.

Windows — C#

Concern	Choice	Notes
Runtime	.NET 8+	LTS.
Interop	LibraryImport (source-gen P/Invoke) over the C ABI	Marshal the event callback as a function pointer ([UnmanagedCallersOnly]) to avoid delegate-lifetime bugs; keep the interface "chunky" not "chatty" to minimize managed↔native transitions.
UI	WinUI 3 (most native) or Avalonia	WinUI for a first-class Windows look; Avalonia if we later want one C# UI across desktop OSes.
Audio	handled by the core (miniaudio/WASAPI)	C# only drives device selection + meters.

3. Server (voicecat-server)

• Pure C++ linking the core; no GUI. Runs on Linux (primary), macOS, Windows.
• Config via a server.toml (allow_guests, ports, channel defaults, Opus policy, TLS cert paths or auto-self-signed + Ed25519 identity, Argon2id cost params, rate limits).
• SQLite for state. Single process for v1; interfaces drawn so a multi-node build is possible later but explicitly out of scope.
• Packaging: static-ish binary per OS; systemd unit + Docker image for Linux.

4. Build & tooling

Tool	Use
CMake (3.25+)	One build graph for core + server + test CLI; UI projects consume the built core.
vcpkg (manifest mode)	Pin C/C++ deps (opus, libsodium, mbedtls, protobuf, sqlite3, spdlog, asio, miniaudio — see vcpkg.json). webrtc-audio-processing/speexdsp are not in the manifest: no working vcpkg port / no working Windows/MSVC build exists upstream for the former; the latter was never actually wired up (the lightweight VAD needs no resampler). Reproducible across OSes.
protoc	Generate C++/C#/Swift from core/proto/*.proto (single source of truth).
clang-format / clang-tidy	Style + static analysis on the core.
CTest + a fuzz target	Unit/integration tests; fuzz the frame parser and protobuf boundary (security-sensitive).
GitHub Actions (or similar)	Matrix CI: Linux/macOS/Windows core+server; Xcode build for Apple; dotnet build for Windows.

5. Licensing — permissive only (hard rule)

The code will eventually be distributed in closed-source form, so no GPL/LGPL dependencies are permitted. Every dependency below is BSD / MIT / ISC / Apache-2.0 / public-domain:

• mbedTLS — Apache-2.0 ✅ · libsodium — ISC ✅ · libopus — BSD ✅ · miniaudio — public domain / MIT-0 ✅ · protobuf — BSD ✅ · SQLite — public domain ✅ · Asio (standalone) — Boost ✅ · spdlog — MIT ✅. webrtc-audio-processing would be BSD-3 ✅ if/when it's actually built in (see §1) — not a live dependency today, so not part of the resolved vcpkg graph the license scanner below checks.
• Explicitly rejected: wolfSSL (GPLv2/commercial) and any DTLS stack that would drag in copyleft. The exported-keys + AEAD media design (security.md §2) removes the need for one entirely.
• CI runs a license scanner over the resolved vcpkg graph and fails the build on any GPL/LGPL transitive dependency, so this rule can't silently regress.

6. Why not the obvious alternatives

• WebRTC — explicitly rejected: ICE/SDP/TURN complexity, huge dependency, opaque. We want plain TCP+UDP we fully control.
• QUIC — capable (reliable streams + datagrams + TLS 1.3 in one), but heavier and drifts toward the complexity we're avoiding. Revisit only if NAT traversal/multiplexing pain appears.
• gRPC for control — pulls HTTP/2 and a lot of surface for what is a simple framed message stream over TLS. Plain protobuf-over-framed-TLS is enough.
• A Rust core — viable and memory-safe, but the user prefers C++ and the Swift/C# binding story is marginally simpler from C++ (Swift can even consume C++ directly).