The "Fog of War" Concept

HexTrek is a mobile application built on the "fog of war" mechanic found in many exploration games. It encourages users to walk and explore their physical surroundings by tracking their real-world movements and converting those tracks into a "revealed" percentage of a map.

The crucial differentiator of HexTrek is its strict adherence to local-first privacy. Unlike commercial tracking or fitness apps, HexTrek does not transmit continuous GPS telemetry to a remote server. All data is securely processed, encrypted, and stored entirely on the user's device. The application can function completely offline once the initial map tiles for a city are downloaded.

Core Functionality

  • Background Location Tracking: The app continuously monitors the user's location via the device's GPS while they are walking.
  • Hexagonal Grid Indexing: Instead of saving raw latitude/longitude points (which are heavy and difficult to calculate area with), the app converts GPS coordinates into Hexagon IDs using Uber's H3 grid system.
  • Encrypted Local Storage: The generated Hexagon IDs are saved to a local, heavily encrypted database (SQLCipher). The database only stores unique IDs, keeping the file size incredibly small even after years of use.
  • Offline Map Rendering: When the user opens the app, it queries the local database for all visited Hexagon IDs, converts them back into geographical polygons, and renders them as a colored "revealed" overlay on an offline vector map.
  • Neighborhood Completion: The app calculates what percentage of a specific neighborhood or suburb has been explored by comparing the user's visited hexagons against the total number of hexagons that fit within the neighborhood's geometric boundaries (sourced from OpenStreetMap).

Technical Architecture & Stack

The application is built using a cross-platform approach with a strong emphasis on high-performance native bridges (JSI) for database operations.

1. The Frontend Framework: React Native

React Native is used for the UI and business logic. It provides the necessary ecosystem for cross-platform development while offering robust plugins for background tasks and hardware-level encryption APIs.

2. The Map Engine: MapLibre GL Native

MapLibre (@maplibre/maplibre-react-native) is chosen because it is fully open-source and free of the hidden telemetry or background tracking often found in commercial mapping SDKs. Offline Capability: MapLibre’s offlineManager is utilized to download vector tile packs locally. The map is configured with a custom styleURL pointing to these local assets, ensuring zero network calls are made to render the map during an exploration session.

3. The Grid Engine: Uber H3

Uber’s H3 system (via the h3-reactnative community fork) divides the world into a continuous grid of hexagons. The app uses a high resolution (Resolution 10 or 11), equating to hexagons a few meters across—ideal for street-level walking. The native fork ensures heavy mathematical operations required for grid indexing run smoothly within the React Native environment.

The Encrypted Database: OP-SQLite + SQLCipher

This is the core of the privacy architecture (@op-engineering/op-sqlite):

  • JSI Performance: OP-SQLite uses the JavaScript Interface (JSI), bypassing the slower JSON bridge used by older React Native SQLite libraries. This allows for incredibly fast, synchronous database inserts during rapid GPS updates without draining the battery or lagging the UI.
  • SQLCipher Encryption: OP-SQLite provides native support for SQLCipher, enabling transparent 256-bit AES encryption of the database file.

4. Native Security: Keychain/Keystore

To ensure the database encryption key is never exposed, HexTrek utilizes react-native-keychain. On the first launch, a cryptographically secure, random 256-bit key is generated. This key is immediately stored in the device's native hardware-backed security module (the Secure Enclave on iOS or the Keystore on Android). Every time the app launches, it securely retrieves this key from the enclave and passes it to OP-SQLite to unlock the local database.