voice-cat/CLAUDE.md

VoiceCat developer guide

VoiceCat is a self-hosted encrypted voice and text chat system. The supported implementation is .NET 10. Read AGENTS.md for working rules and PROGRESS.md for the current short status.

Build and test

./dotnet/build-native.ps1
dotnet restore dotnet/VoiceCat.slnx --locked-mode
dotnet build dotnet/VoiceCat.slnx -c Release --no-restore
dotnet test dotnet/VoiceCat.slnx -c Release --no-build
./dotnet/check-licenses.ps1

Apple client builds require macOS, Xcode, and the .NET macOS/iOS workloads:

./dotnet/build-native-ios.sh
dotnet restore clients/apple/dotnet/VoiceCat.Apple.slnx
dotnet build clients/apple/dotnet/VoiceCat.Apple.slnx -c Debug --no-restore

Windows publishing uses clients/windows/publish-client.ps1. Server publishing uses dotnet/publish-server.ps1. See docs/building.md while it is being rewritten; prefer the scripts themselves when historical text disagrees with them.

Current architecture

• proto/voicecat.proto is the control-plane wire schema.
• dotnet/src/VoiceCat.Protocol owns protobuf framing and generated types.
• dotnet/src/VoiceCat.Crypto owns TLS, TOFU, media AEAD, identity, and password hashing.
• dotnet/src/VoiceCat.Server owns the TLS/UDP server and SQLite state.
• dotnet/src/VoiceCat.Core owns client connection and protocol state.
• dotnet/src/VoiceCat.Audio, .Codec, and .Dsp own voice processing.
• dotnet/src/VoiceCat.Cli is the supported headless client.
• clients/windows is the WinForms client.
• clients/apple/dotnet contains the AppKit and UIKit clients.
• native/media and native/rnnoise are the required Opus/RNNoise native boundary.
• native/apple/broadcast is the required Swift ReplayKit extension.

The old C++ implementation and old Swift applications are unsupported retirement sources. They are not architectural authorities and compatibility with them is not a requirement.

Invariants

• TLS control and encrypted UDP media are mandatory; do not add plaintext transports.
• No GPL or LGPL dependencies.
• Audio callbacks must not allocate, lock, block, or perform network I/O.
• Treat proto/voicecat.proto, persisted database formats, and the ReplayKit ring layout as explicit versioned contracts.
• A passing build is not enough: add or update behavior tests for observable changes.
• Keep PROGRESS.md concise; do not append a historical changelog.