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) 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 – Connection-speed-aware audio/video codecs and point-to-multipoint.
• Communications module: modules/communications/domain/.
• Core common: core/common/ (CircuitBreaker, QoS, ConnectivityManager).