siprouter/CLAUDE.md

# Project Notes

## Architecture: Hub Model in Rust (Call as Centerpiece)

The call hub lives in the Rust proxy-engine (`rust/crates/proxy-engine/`). TypeScript is the **control plane only** — it configures the engine, sends high-level commands (`hangup`, `make_call`, `webrtc_offer`, etc.), and receives events (`incoming_call`, `call_answered`, `device_registered`, `webrtc_audio_rx`, …). No raw SIP/RTP ever touches TypeScript.

The `Call` is still the central entity: it owns N legs and a central mixer task that provides mix-minus audio to all participants. Legs can be `SipProvider`, `SipDevice`, `WebRtc`, or `Tool` (recording/transcription observer).

### Key Rust files (`rust/crates/proxy-engine/src/`)

- `call_manager.rs` — singleton registry, call factory methods, SIP routing (inbound/outbound/passthrough), B2BUA state machine, inbound route resolution
- `call.rs` — the `Call` hub + `LegInfo` struct, owns legs and the mixer task
- `sip_leg.rs` — full SIP dialog management for B2BUA legs (INVITE, 407 auth retry, BYE, CANCEL, early media)
- `rtp.rs` — RTP port pool (uses `Weak<UdpSocket>` so calls auto-release ports on drop) + RTP header helpers
- `mixer.rs` — 20 ms-tick mix-minus engine (48 kHz f32 internal, per-leg transcoding via `codec-lib`, per-leg denoising)
- `jitter_buffer.rs` — per-leg reordering/packet-loss compensation
- `leg_io.rs` — spawns inbound/outbound RTP I/O tasks per SIP leg
- `webrtc_engine.rs` — browser WebRTC sessions (werift-rs based), ICE/DTLS/SRTP
- `provider.rs` — SIP trunk registrations, public-IP detection via Via `received=`
- `registrar.rs` — accepts REGISTER from SIP phones, tracks contacts (push-based device status)
- `config.rs` — `AppConfig` deserialized from TS, route resolvers (`resolve_outbound_route`, `resolve_inbound_route`)
- `main.rs` — IPC command dispatcher (`handle_command`), event emitter, top-level SIP packet router
- `sip_transport.rs` — owning wrapper around the main SIP UDP socket
- `voicemail.rs` / `recorder.rs` / `audio_player.rs` / `tts.rs` — media subsystems
- `tool_leg.rs` — per-source observer audio for recording/transcription tools
- `ipc.rs` — event-emission helper used throughout

### Key TS files (control plane)

- `ts/sipproxy.ts` — entrypoint, wires the proxy engine bridge + web UI + WebRTC signaling
- `ts/proxybridge.ts` — `@push.rocks/smartrust` bridge to the Rust binary, typed `TProxyCommands` map
- `ts/config.ts` — JSON config loader (`IAppConfig`, `IProviderConfig`, etc.), sent to Rust via `configure`
- `ts/voicebox.ts` — voicemail metadata persistence (WAV files live in `.nogit/voicemail/{boxId}/`)
- `ts/webrtcbridge.ts` — browser WebSocket signaling, browser device registry (`deviceIdToWs`)
- `ts/call/prompt-cache.ts` — the only remaining file under `ts/call/` (IVR prompt caching)

### Rust SIP protocol library

`rust/crates/sip-proto/` is a zero-dependency SIP data library (parse/build/mutate/serialize messages, dialog management, SDP helpers, digest auth). Do not add transport or timer logic there — it's purely data-level.

## Event-push architecture for device status

Device status flows **via push events**, not pull-based IPC queries:

1. Rust emits `device_registered` when a phone REGISTERs
2. TS `sipproxy.ts` maintains a `deviceStatuses` Map, updated from the event
3. Map snapshot goes into the WebSocket `status` broadcast
4. Web UI (`ts_web/elements/sipproxy-devices.ts`) reads it from the push stream

There used to be a `get_status` pull IPC for this, but it was never called from TS and has been removed. If a new dashboard ever needs a pull-based snapshot, the push Map is the right source to read from.

## Inbound routing (wired in Commit 4 of the cleanup PR)

Inbound route resolution goes through `config.resolve_inbound_route(provider_id, called_number, caller_number)` inside `create_inbound_call` (call_manager.rs). The result carries a `ring_browsers` flag that propagates to the `incoming_call` event; `ts/sipproxy.ts` gates the `webrtc-incoming` browser fan-out behind that flag.

**Known limitations / TODOs** (documented in code at `create_inbound_call`):
- Multi-target inbound fork is not yet implemented — only the first registered device from `route.device_ids` is rung.
- `ring_browsers` is **informational only**: browsers see a toast but do not race the SIP device to answer. True first-to-answer-wins requires a multi-leg fork + per-leg CANCEL, which is not built yet.
- `voicemail_box`, `ivr_menu_id`, `no_answer_timeout` are resolved but not yet honored downstream.

## WebRTC Browser Call Flow (Critical)

The browser call signaling order is strict:

1. Browser initiates outbound via a TS API (e.g. `POST /api/call`) — TS creates a pending call in the Rust engine via `make_call` and notifies the browser with a `webrtc-incoming` push.
2. Browser sends `webrtc-offer` (with its own `sessionId`) → Rust `handle_webrtc_offer` creates a **standalone** WebRTC session (NOT attached to any call yet).
3. Browser sends `webrtc_link` (with `callId` + `sessionId`) → Rust links the standalone session to the Call and wires the WebRTC leg through the mixer.

**The WebRTC leg cannot be fully attached at call-creation time** because the browser's session ID is unknown until the `webrtc-offer` arrives.

### WebRTC audio return channel (Critical)

The SIP→browser audio path goes through the mixer, not a direct RTP relay:

1. Provider sends RTP → received on the provider leg's UDP socket (`leg_io::spawn_sip_inbound`)
2. Packet flows through `jitter_buffer` → mixer's inbound mpsc channel
3. Mixer decodes/resamples/denoises, computes mix-minus per leg
4. WebRTC leg receives its mix-minus frame, encodes to Opus, and pushes via the WebRTC engine's peer connection sender

Browser→SIP works symmetrically: `ontrack.onReceiveRtp` → WebRTC leg's outbound mpsc → mixer → other legs' inbound channels.

## SDP/Record-Route NAT (fixed in Commit 3 of the cleanup PR)

The proxy tracks a `public_ip: Option<String>` on every `LegInfo` (populated from provider-leg construction sites). When `route_passthrough_message` rewrites SDP (`c=` line) or emits a `Record-Route`, it picks `advertise_ip` based on the destination leg's kind:

- `SipProvider` → `other.public_ip.unwrap_or(lan_ip)` (provider reaches us via public IP)
- `SipDevice` / `WebRtc` / `Tool` / `Media` → `lan_ip` (everything else is LAN or proxy-internal)

This fixed a real NAT-traversal bug where the proxy advertised its RFC1918 LAN IP to the provider in SDP, causing one-way or no audio for device-originated inbound traffic behind NAT.

## Build & development

- **Build:** `pnpm run buildRust` (never `cargo build` directly — tsrust cross-compiles for both `x86_64-unknown-linux-gnu` and `aarch64-unknown-linux-gnu`)
- **Cross-compile setup:** the aarch64 target requires `gcc-aarch64-linux-gnu` + `libstdc++6-arm64-cross` (Debian/Ubuntu). See `rust/.cargo/config.toml` for the linker wiring. A committed symlink at `rust/.cargo/crosslibs/aarch64/libstdc++.so` → `/usr/aarch64-linux-gnu/lib/libstdc++.so.6` avoids needing the `libstdc++-13-dev-arm64-cross` package.
- **Bundle web UI:** `pnpm run bundle` (esbuild, output: `dist_ts_web/bundle.js`)
- **Full build:** `pnpm run build` (= `buildRust && bundle`)
- **Start server:** `pnpm run start` (runs `tsx ts/sipproxy.ts`)

## Persistent files

- `.nogit/config.json` — app config (providers, devices, routes, voiceboxes, IVR menus)
- `.nogit/voicemail/{boxId}/` — voicemail WAV files + `messages.json` index
- `.nogit/prompts/` — cached TTS prompts for IVR menus