Map Performance & Failover

This document describes map tile performance monitoring for the web application.

Overview

Find map tiles use MapLibre GL JS with OpenFreeMap styles (tiles.openfreemap.org). Radar is used only for geocoding and place autocomplete — not for the map shell. Mapbox tile failover is deferred.

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.

  • Status Query: The client reads Convex for OpenFreeMap health metrics (recommendations no longer switch providers to Mapbox).

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.

Style Fallback (client)

When an OpenFreeMap style URL cannot be fetched:

  1. The client probes the preferred style JSON, then tries other OpenFreeMap styles (liberty, bright, positron, …).

  2. If every OpenFreeMap style fails, Find shows a clear on-screen error.

  3. Neither Radar nor Mapbox is required for tiles.

Database Schema

The following Convex tables support this system:

  • mapLatencyReports: Individual reports from polling users.

  • mapProviderMetrics: Aggregated health statistics (OpenFreeMap; historical Mapbox rows may remain).

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

Configuration

Ensure the following environment variables are set (see Environment variables for full context):

Variable

Description

NEXT_PUBLIC_MAP_PROVIDER

Tile provider (openfreemap). Mapbox deferred.

NEXT_PUBLIC_RADAR_PUBLISHABLE_KEY

Radar publishable key for geocoding / autocomplete only — not required to render Find map tiles.