Network Health and Quality Monitoring

Relevant source files

The following files were used as context for generating this wiki page:

• web/src/components/NetworkDiagnostics.tsx
• core/src/health-check.ts
• V1_PRODUCTION_IMPLEMENTATION_PLAN.md
• PROGRESS.md
• V1_COMPLETE_TASK_LIST.md
• CONTRIBUTING.md

The Network Health and Quality Monitoring system is a suite of tools and modules designed to provide comprehensive, real-time insight into the status and performance of the Sovereign Communications mesh network. Its purpose is to ensure network stability, optimize routing decisions, and provide developers and users with diagnostic information.

The system is composed of several key parts: a global HealthChecker for monitoring application-wide subsystems, a ConnectionMonitor for assessing the quality of individual peer connections, a peer health monitor for managing peer liveness within the mesh, and a NetworkDiagnostics UI component for visual feedback. These components work together to maintain a robust and resilient decentralized network.

System Health Checker

The HealthChecker class provides a holistic view of the application's health by periodically checking critical subsystems: cryptography, storage, network, and performance. It aggregates these checks into an overall health status.

Sources: core/src/health-check.ts

Architecture

The HealthChecker is a singleton class that can be initiated to run checks automatically at a configured interval. It performs a series of checks on different components and consolidates the results into a single HealthCheckResult object.

The diagram below shows the structure of the HealthChecker and its related data models.

Health Check Process

The performHealthCheck method orchestrates the checks for each subsystem. The overall status is determined by the collective results: healthy if all components are healthy, degraded if any component reports a 'warning', and critical if any component reports an 'error'.

This flowchart illustrates the logic within the performHealthCheck method and its private check helpers.
Sources: core/src/health-check.ts:51-81, 86-224

Health Status and Results

The health check produces a HealthCheckResult object containing the status of each component.

HealthCheckResult Property	Type	Description
healthy	boolean	true if all components are healthy, otherwise false.
status	'healthy' | 'degraded' | 'critical'	The overall system health status.
checks	object	An object containing a ComponentHealth result for crypto, storage, network, and performance.
timestamp	number	The timestamp when the check was performed.
uptime	number	The application uptime in milliseconds.

Sources: core/src/health-check.ts:8-18

ComponentHealth Property	Type	Description
healthy	boolean	true if the component status is not 'error'.
status	'ok' | 'warning' | 'error'	The health status of the individual component.
details	string	A human-readable description of the component's status.
metrics	Record<string, number>	Optional performance metrics, e.g., signVerifyTime or memoryUsedMB.
lastCheck	number	The timestamp of the last check for this component.

Sources: core/src/health-check.ts:20-26

Connection Quality Monitoring

This subsystem is responsible for evaluating the quality of individual peer-to-peer connections based on real-time network metrics.

Sources: V1_PRODUCTION_IMPLEMENTATION_PLAN.md

Connection Metrics and Quality Levels

The ConnectionMonitor class tracks several key metrics to determine connection quality.

Metric	Type	Description
latency	number	Average round-trip time in milliseconds (ms).
packetLoss	number	Packet loss as a percentage.
bandwidth	number	Estimated bandwidth in bytes per second.
jitter	number	Variance in latency, measured in ms.

Sources: V1_PRODUCTION_IMPLEMENTATION_PLAN.md

Based on these metrics, the calculateConnectionQuality function assigns a qualitative score.

Quality Level	Latency Threshold	Packet Loss Threshold
excellent	< 50 ms	< 1%
good	< 100 ms	< 5%
fair	< 200 ms	< 10%
poor	>= 200 ms	>= 10%
offline	Infinity	N/A

Sources: V1_PRODUCTION_IMPLEMENTATION_PLAN.md

The logic for this calculation is as follows:

Peer Health Monitoring

The mesh network core includes a peer health monitoring system to ensure the routing table remains populated with responsive peers. This is primarily achieved through a heartbeat mechanism. Unresponsive peers are eventually timed out and removed to maintain efficient message routing.

Sources: PROGRESS.md, V1_COMPLETE_TASK_LIST.md, CONTRIBUTING.md

Network Diagnostics UI

The NetworkDiagnostics.tsx component provides a real-time user interface for observing the health and performance of the mesh network. It fetches statistics at a configurable interval and presents them in a user-friendly dashboard.

Sources: web/src/components/NetworkDiagnostics.tsx

Data Flow

The component uses the useMeshNetwork hook to get statistics from the core mesh network. It runs an interval timer to periodically call getStats() and update its local state, which causes the UI to re-render with the latest data.

This diagram shows the data polling loop that powers the real-time updates in the diagnostics panel.
Sources: web/src/components/NetworkDiagnostics.tsx:48-121

Displayed Metrics

The diagnostics panel displays a variety of metrics, categorized for clarity.

Category	Metric	Description	Source
Overview	Connected Peers	The number of currently connected peers.	newStats.peers.connectedPeers
	Messages	Count of messages sent (forwarded) and received.	newStats.relay.messagesForwarded, newStats.relay.messagesReceived
	Latency	Average, min, and max round-trip time to peers.	Calculated from WebRTC remote-inbound-rtp reports.
	Packet Loss	Total packets lost across all connections.	Calculated from WebRTC remote-inbound-rtp reports.
	Uptime	Time since the diagnostics component was mounted.	Date.now() - startTime
Bandwidth	Upload	Current upload speed in bytes/sec.	Calculated from report.bytesSent over time.
	Download	Current download speed in bytes/sec.	Calculated from report.bytesReceived over time.
Connections	Distribution	A visual breakdown of BLE vs. WebRTC connections.	stats.bleConnections, stats.webrtcConnections

Sources: web/src/components/NetworkDiagnostics.tsx:29-46, 60-118

The UI also uses color-coding to indicate the health of latency and packet loss metrics, providing at-a-glance status information.

• Latency: Good <= 50ms, Warn <= 100ms, Bad > 100ms
• Packet Loss: Good <= 1%, Warn <= 3%, Bad > 3%

Sources: web/src/components/NetworkDiagnostics.tsx:167-172, 219, 230

Conclusion

The Network Health and Quality Monitoring system is a vital part of the Sovereign Communications project. It provides multi-layered visibility into the application's status, from high-level subsystem health down to the quality of individual peer connections. The HealthChecker ensures overall application stability, the ConnectionMonitor informs routing decisions, and the NetworkDiagnostics UI offers an essential tool for debugging and observing network behavior in real-time. Together, these components contribute to a more resilient, performant, and transparent mesh network.