# 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

```bash
./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:

```bash
./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.