Architecture

A technical overview of NavGate’s Kotlin navigation core, Android adapters, route providers, local storage, MapLibre map, and ARCore renderer.

Updated 1 November 2026 Development manual

In this guide

A shared engine beneath each view

NavGate is a native Kotlin application. Jetpack Compose presents the journey screens; a ViewModel connects user actions and platform observations to a navigation backend. The navigation core holds route and session behavior independently of the Android interface.

Runtime architecture

Rendering diagram…

Compose and its ViewModel coordinate one shared navigation session. Routing, discovery, persistence, and Android sensors feed the map, steps, and camera presentations.

View Mermaid source

flowchart TD
  UI[Compose journey screens] --> VM[NavGate ViewModel]
  VM --> Core[Navigation backend and session]
  Sensors[Android location and motion sensors] --> Core
  Core --> Router[Connectivity-aware routing]
  Router --> Valhalla[Online Valhalla]
  Router --> BRouter[Local BRouter and installed tiles]
  VM --> Search[Local indexes and online Photon search]
  Core --> Room[Room trip state and route cache]
  VM --> Prefs[DataStore preferences]
  Core --> Shared[Shared route and progress]
  Shared --> Map[MapLibre map and steps]
  Shared --> AR[ARCore and camera rendering]

Where responsibilities sit

Area	Responsibility
app	Compose interface, Android location and sensors, service lifecycle, providers, persistence, map and camera integration
navigation-core	Route geometry and integrity, progress, maneuver advancement, arrival, recovery, and provider contracts
brouter	Included on-device routing engine used with installed segment files and profiles
scripts	Build public-source place indexes and region assets; these are build-time tools rather than a live route service
website	Next.js product story and illustrative browser demo; it does not run the Android navigation engine

Route state is distinct from presentation

A planned route carries geometry, destination, profile, and maneuvers. Location updates are checked and projected against that geometry to estimate progress. The same session supplies remaining distance, maneuver information, arrival, and recovery status to each presentation.

Route calculation and session progression are deterministic code paths; they do not require a generative AI service.
Map camera movement, vehicle styling, and AR rendering are presentation concerns, not alternative sources of truth for route progress.
A geometry or provider failure must produce an unavailable state rather than a fabricated straight connecting line.

Local state and external providers

Room stores trip-related state and route caches. DataStore stores interface and guidance preferences. File-backed packs supply offline map and routing data. Online discovery uses Photon; online road routing uses Valhalla; map data is displayed with MapLibre and OpenFreeMap/OpenStreetMap sources.

What each kind of verification establishes

Evidence	What it can establish
JVM or script tests	Behavior of the tested logic and fixtures in a controlled runtime
Android instrumentation	The particular screens, persistence, lifecycle, and device conditions exercised
Recorded or simulated routes	Behavior under selected replayed inputs; not independent outdoor accuracy
Physical journeys	Observed behavior on the tested route, phone, signal, light, and power conditions
Website demo	Browser interaction and illustrative storytelling, not native app or provider acceptance

Source basis

This guide describes development source reviewed on 1 November 2026. The Android working tree contains changes beyond the public revision; repository links are reference locations and may show an earlier implementation. An installed build may differ.