smoa/docs/reference/SMART-ROUTING-AND-QOS.md

# Smart Routing, QoS, Lag Reduction, and System Stability

## Overview

SMOA implements **smart routing** and **QoS (Quality of Service)** for media (voice/video) to improve quality, reduce lag, manage infrastructure, and keep the system stable under poor conditions.

## Components

### Core (core/common)

| Component | Purpose |
|-----------|---------|
| **CircuitBreaker** | Per-endpoint failure handling: after N failures the circuit opens and calls fail fast until reset timeout. Used by InfrastructureManager for STUN/TURN/signaling. |
| **QoSPolicy / TrafficClass** | Traffic classification (VOICE, VIDEO, SIGNALING, DATA) and priority; policy caps (max concurrent sessions, max total send bitrate) for stability. |
| **ConnectivityManager** | Extended with `getActiveTransportType()` (WIFI, CELLULAR, VPN, ETHERNET) and `getCellularGeneration()` (4G LTE, 5G, 5G MW) for path selection. |
| **NetworkTransportType** | Enum for transport used by routing policy. |
| **CellularGeneration** | When on cellular: LTE_4G, NR_5G, NR_5G_MW (millimeter wave), UNKNOWN. Used to prefer 5G / 5G MW over 4G. |

### Communications (modules/communications)

| Component | Purpose |
|-----------|---------|
| **MediaRoutingPolicy** | Path preference: prefer low latency, prefer VPN when required, transport order, path failover, min bandwidth for video. |
| **NetworkPathSelector** | Selects best network path for media using ConnectivityManager, VPNManager, and MediaRoutingPolicy; exposes `SelectedPath` (transport, cellularGeneration when CELLULAR, recommendedForVideo). On cellular, ranks 4G LTE, 5G, and 5G MW per policy. |
| **InfrastructureManager** | Manages STUN/TURN/signaling endpoint lists; uses CircuitBreaker for health; `getHealthyStunUrls()`, `getHealthyTurnServers()`, `getHealthySignalingUrl()`; `buildWebRTCConfig()` for WebRTC with failover. |
| **ConnectionStabilityController** | Reconnection exponential backoff; degradation mode (NONE, AUDIO_ONLY, REDUCED_VIDEO); session count and bitrate caps from QoSPolicy. |
| **SmartRoutingService** | Orchestrates path selection, infra, stability, and adaptive codecs; exposes `RoutingState`, `getWebRTCConfig()`, `tryStartSession()`, `recordConnectionSuccess/Failure`, `updateFromConnectionQuality()`, `onConnectivityChanged()`. |

## QoS and Lag Reduction

- **Traffic classes**: Voice (highest), Video, Signaling, Data. Used for scheduling and prioritization hints.
- **Path selection**: Prefer Wi-Fi/VPN over cellular when policy says so; when on cellular, prefer 5G MW > 5G > 4G LTE (configurable via `cellularGenerationPreferenceOrder`). Avoid sending video when path is not recommended.
- **Adaptive codecs**: Connection-speed-aware codecs (see [MEDIA-CODECS-AND-P2M.md](MEDIA-CODECS-AND-P2M.md)) reduce bitrate on slow links, reducing buffering and lag.
- **Reconnection backoff**: Exponential backoff after connection failures to avoid hammering endpoints and reduce perceived instability.
- **Graceful degradation**: When connection tier is VERY_LOW (or policy says so), switch to AUDIO_ONLY to preserve voice and reduce load.

## Infrastructure Management

- **STUN/TURN/signaling**: Configure via `InfrastructureManager.setStunEndpoints()`, `setTurnEndpoints()`, `setSignalingEndpoints()`.
- **Health**: Each endpoint is protected by a circuit breaker; after a threshold of failures the endpoint is skipped until reset timeout.
- **Failover**: `getHealthyStunUrls()` / `getHealthyTurnServers()` / `getHealthySignalingUrl()` return only endpoints with closed circuits; WebRTC config is built from these for automatic failover.

## System Stability

- **Session cap**: `QoSPolicy.maxConcurrentSessions` limits concurrent media sessions; `SmartRoutingService.tryStartSession()` enforces it.
- **Bitrate cap**: `QoSPolicy.maxTotalSendBitrateBps` can be enforced by the app when sending (ConnectionStabilityController.isWithinBitrateCap()).
- **Circuit breakers**: Prevent cascading failures to unhealthy STUN/TURN/signaling servers.
- **Degradation**: AUDIO_ONLY and REDUCED_VIDEO reduce load when quality is poor.

## Integration

- **WebRTCManager**: Uses `SmartRoutingService.getWebRTCConfig()` for ICE/signaling config (healthy infra) and adaptive codec constraints.
- **VideoTransport** (meetings): Uses `SmartRoutingService.tryStartSession()` / `notifySessionEnded()`, `getRoutingState().recommendedForVideo` to decide audio-only vs video, and `recordConnectionSuccess/Failure()` for backoff.
- **Connectivity changes**: Call `SmartRoutingService.onConnectivityChanged()` when connectivity or VPN state changes so path selection and routing state are updated.
- **Quality updates**: When WebRTC stats (or network callback) provide new bandwidth/RTT/loss, update the connection quality monitor and call `SmartRoutingService.updateFromConnectionQuality()` to adapt codecs and degradation.

## Configuration

- **MediaRoutingPolicy**: Default prefers low latency and VPN when required; customize transport order, `cellularGenerationPreferenceOrder` (4G LTE, 5G, 5G MW), and `minBandwidthKbpsForVideo` per deployment. Cellular generation is derived from `TelephonyManager` (API 29+ for 5G NR; API 31+ for 5G MW when `OVERRIDE_NETWORK_TYPE_NR_ADVANCED` is reported).
- **QoSPolicy**: Set via `SmartRoutingService.setQoSPolicy()` (session cap, bitrate cap).
- **Circuit breaker**: Threshold and reset timeout are in InfrastructureManager (e.g. 3 failures, 60s reset); adjust as needed.
- **StabilityController**: `minBackoffMs`, `maxBackoffMs`, `backoffMultiplier` control reconnection backoff.

## Related

- [MEDIA-CODECS-AND-P2M.md](MEDIA-CODECS-AND-P2M.md) – Connection-speed-aware audio/video codecs and point-to-multipoint.
- Communications module: `modules/communications/domain/`.
- Core common: `core/common/` (CircuitBreaker, QoS, ConnectivityManager).