Map Performance & Failover

This document describes the robust map performance monitoring and failover system implemented for the Food Truck Nerdz application.

Overview

The application utilizes a hybrid map provider setup designed for reliability and performance. OpenFreeMap is the default tile provider, with Mapbox serving as a high-availability fallback.

Performance Monitoring System

To ensure a smooth user experience, we actively monitor map tile load latency from client applications.

Client-Side Monitoring

Client applications use the useMapPerformance hook to track the latency of map tile requests:

  • Short-term Statistics: The hook maintains a local sample of recent tile load durations.

  • Anomaly Detection: If median latency exceeds 1000ms, the client detects a "local anomaly" or degradation.

  • Failover Polling: When excessive latency is detected, the client polls the Convex backend for the current "recommended" provider.

Polling & Reporting Pool

To minimize server load while maintaining accurate metrics, we use a selective reporting system:

  • 10 Users Per Tile: The backend maintains a baseline of up to 10 active pollers per map tile (indexed by zoom/x/y).

  • Joining the Pool: Clients attempt to join the polling pool when they move to a new area.

  • Reporting: Only users in the active polling pool send latency metrics back to the server.

  • Outlier Release: If a user’s device reports statistics that are consistently slow (outliers) compared to global averages (e.g., due to a slow phone or poor local cellular signal), they are released from the polling system to make room for another active user in that area.

Failover Implementation

When OpenFreeMap experiences performance degradation or outages:

  1. Server-side statistics (aggregated from pollers) identify the issue.

  2. The mapProviderMetrics table is updated with a degraded or outage status.

  3. Client applications, upon polling or through reactive queries, receive "mapbox" as the recommended provider.

  4. The map automatically re-initializes with Mapbox tiles using the NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN.

Database Schema

The following Convex tables support this system:

  • mapLatencyReports: Individual reports from polling users.

  • mapProviderMetrics: Aggregated health statistics for each provider.

  • users.isPerformancePoller: Tracks which users are currently active pollers.

Configuration

Ensure the following environment variables are set:

Variable

Description

NEXT_PUBLIC_MAP_PROVIDER

Initial map provider (openfreemap, mapbox, or radar).

NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN

Required for Mapbox fallback tiles.