map.ping On-Device Proximity Engine

map.ping turns any Google My Map into location-aware reminders. Import a map of places you care about - favourite restaurants, viewpoints, a scavenger-hunt route, store branches - and the app quietly watches your location in the background. Come within your chosen radius of a pin and it taps you on the shoulder with a local notification.

"Import a map. Go about your day. Get the ping - even with the app closed or the phone locked."

No Backend, By Design

map.ping has zero servers. Everything - import, storage, scanning, and notifications - happens on the device. That is the architecture: the privacy guarantee and the operating cost ($0) both fall out of the same decision. The only network calls the app ever makes are an optional fetch of a public Google My Map's KML and, for Pro users, an OAuth round-trip to read their own Drive maps.

map.ping/
├── src/
│   ├── background/      # Engine: geolocation.ts, scanRunner.ts,
│   │                    #   headlessTask.ts, BackgroundScanController.tsx
│   ├── import/          # kmlParse.ts (pure), kmlImport.ts (file/URL/Drive IO)
│   ├── utils/           # backgroundTaskLogic.ts (gates), geo, proximity,
│   │                    #   scanLogic, quietHours, notificationSetup, secureStorage
│   ├── storage/         # mapStore.ts — AsyncStorage CRUD + snooze
│   ├── context/         # DataContext, SettingsContext (local state)
│   ├── monetization/    # RevenueCat entitlements (Free / Pro)
│   ├── screens/         # Maps, MapView, ImportMap, Settings, Paywall, Onboarding
│   ├── components/      # MapCard, ErrorBoundary, Toast, modals
│   ├── share/           # iOS Share Extension sheet
│   └── i18n/            # en / he / fr / ru / ar (strict-typed)
├── index.ts            # registers the Android headless task
├── index.share.js      # Share Extension entry
└── app.config.js       # dev/prod variants, plugins, privacy manifest

On-Device Data Flow

Motion-Aware Background Geolocation

The GPS spine is react-native-background-geolocation v5, configured for the New Architecture with the nested { geolocation, app, logger } shape. Its defining trait is motion awareness: the OS hands the engine a fix only while the device is actually moving, then lets it idle when you stop - so the app can run all day without draining the battery. Every fix, foreground or headless, funnels into one self-contained runScan().

Smart Driving - Adaptive GPS Tiers

Walking and driving need very different GPS cadence. A hysteresis state machine (ported from the parent Choers engine, kept as pure, tested functions) promotes and demotes through tiers based on sustained speed readings inside a time window - never on a single noisy sample:

7 Gates Between a GPS Fix and a Ping

The hard problem in a proximity app isn't detecting a nearby pin - it's not nagging you. Every fix runs a deterministic gate chain; the notification only fires if all gates pass. The gate logic lives in pure, unit-tested functions.

Three Sources, One Pure Parser

File, public link, and Drive imports all converge on a single pure parser (parseKmlBytes / parseKmlString) that handles both raw KML and zipped KMZ. Keeping the parser pure is what makes the import logic unit-testable with no device.

Privacy isn't a setting in map.ping - it's the architecture. There is no account system and no backend to send data to, so there is nothing to leak. Location is used for exactly one thing: deciding whether to show you a local alert.

Free / Pro Tiers

Subscriptions run through RevenueCat, which gates the Pro capabilities below behind an active subscription. If the RevenueCat keys are absent, the app fails safe to Free rather than unlocking Pro by accident.

Testing Strategy

The riskiest logic - proximity geometry, the notification gates, KML parsing, and the Free/Pro rules - is deliberately extracted into pure functions with no React, RN, or Expo imports, so it runs in a plain ts-jest node environment with no simulator. That's what makes the engine's decisions deterministic and cheap to verify.

Tooling & Resilience