MODULE 07 · LOCATION, MAPPING & AUTH

Uber — Live Location, Map Tiles & Auth

Library-agnostic mobile architecture for adaptive GPS batching, 60fps vector tile caching, and single-flight 401 token refresh storms.

Act I · Scope & Device Budgets

Real-Time Navigation & Auth Guarantees

Step 1 of 5
Functional & Non-Functional Scope
Core Requirements
  • Adaptive Location Ingestion: Smooth raw GPS via Kalman filtering, interpolate at 60fps locally, and batch uploads every 5s (moving) or 30s (stationary) to avoid cellular radio tail-energy drain.
  • Vector Map Tile Pipeline: Cache compact Protobuf vector tiles (.mvt) across L1 RAM + L2 Disk with 1-ring viewport prefetching for 60fps pan/zoom and instant dark/light theme swaps.
  • Single-Flight 401 Token Refresh: Coalesce simultaneous 401 Unauthorized responses behind a single mutex so rotating refresh tokens are never consumed twice and users are never falsely logged out.
  • Offline & Tunnel Resilience: Persist unsent coordinates in an ordered SQLite WAL outbox and render cached vector tiles + dead-reckoning during underground signal loss.
Concrete Device Budgets
4 Hard Limits
Battery Drain
< 3.5% / hr

Batched 5s / 30s cellular radio duty cycle avoids RRC tail-energy waste.

GPS Smoothing
≤ 8m P95

On-device Kalman filter + 60fps bearing/road-snap interpolation.

Tile Cache Cap
32 MB / 150 MB

L1 RAM / L2 Disk LRU cap (~25 KB .mvt vs 180 KB PNG).

Auth Fan-Out
1x Refresh / Storm

Mutex single-flight guarantee with generation ID check.

Act II · API, Wire & Storage Contracts

Location Batch, Vector Tile & Rotating Auth Contracts

Step 2 of 5
Network & Auth Wire Contracts
Local SSOT & Secure Vault Schema (SQLite WAL)
Act III · Interactive 5-Node Topology & Chaos Simulator

Adaptive GPS Batching, MVT Caching & Single-Flight 401 Simulator

TRIP ACTIVE · NOMINAL
Step 1 / 6
5-Node Topology · Adaptive Location Batching
KALMAN SMOOTH
navigation Map Viewport & UI 60fps GPU · Road-Snap 60FPS · SMOOTH my_location Location & Outbox Kalman · SQLite WAL 5s BATCH · 0 QUEUED map Vector Tile Cache L1 32MB · L2 150MB 94% HIT · MVT READY vpn_key Single-Flight Auth Mutex · Secure Vault VALID · GEN #14 cloud Edge Gateway & CDN Ingest · MVT · Auth ONLINE · 200 OK
KALMAN SMOOTH

Loading simulator...

Invariant active
Live Event Console
Live Telemetry HUD
Real-Time
Radio & Battery
2.6% / hr · 5s Batch
Moving duty cycle
Location Outbox
0 pending
SQLite WAL FIFO
Tile Cache Hit
94% (L1+L2)
1-ring prefetch warm
Auth Flight State
VALID · 0 queued
Gen #14 in Vault
Chaos Engineering Switchboard
0 Active
Act IV · Zero-Dependency Kotlin Contracts & Platform Mapping

Library-Agnostic Core & Android / iOS Equivalents

Auto-Synced to Simulator
Platform Mapping Strip (Android & iOS Equivalents) 6 Agnostic Primitives
Agnostic Primitive Android Equivalent iOS Equivalent Key Invariant
Adaptive Location Provider FusedLocationProviderClient CLLocationManager Stationary backoff (5s → 30s)
Vector Map Renderer MapLibre / Maps SDK (GL/Vulkan) MapLibre / MapKit (Metal) 60fps GPU tessellation & style swap
Secure Token Vault Android Keystore + EncryptedPrefs Keychain Services Hardware-backed atomic rotation
Single-Flight 401 Guard OkHttp Authenticator + Mutex URLSession Retrier + Swift actor Token-generation check avoids double refresh
Local Outbox & Tile Index SQLite WAL (Room / SQLDelight) SQLite WAL (GRDB / Core Data) Crash-safe FIFO batch & LRU metadata
Background Trip Execution Foreground Service (location) Background Location + BGTask Survives screen lock & OS suspension
Act V · Architectural Tradeoffs & Production SLOs

Engineering Tradeoffs & Reliability Targets

Step 5 of 5
Tradeoff 01 7x Smaller

Vector Tiles (MVT) vs. Raster Tiles (PNG)

Pros: Vector (.mvt)

~25 KB Protobuf payloads, crisp retina scaling at any zoom, rotated labels, and zero-network Dark/Light map theme switches.

Cons: Raster (PNG)

~180 KB per tile, blurry between zoom levels, and requires re-downloading every tile to switch day/night map styles.

Verdict Vector (.mvt) wins for navigation: 7x lower cellular egress and smooth 60fps GPU camera tilt/rotation.
Tradeoff 02 Radio Safe

Batched HTTP Uploads vs. Persistent WebSocket

Pros: Batched HTTP

Lets the cellular modem drop into low-power idle between 5s/30s bursts and aligns naturally with SQLite WAL FIFO outbox retries.

Cons: Always-On WS

1Hz upstream pings keep RRC radio pinned in DCH high-power state, draining 8–12% battery/hr on weak LTE links.

Verdict Use Batched HTTP for driver telemetry ingest; reserve bi-directional push/WS strictly for dispatch offers and ETA updates.
Tradeoff 03 Zero False Logout

Single-Flight Mutex + Generation ID vs. Naive 401 Retry

Pros: Mutex + Gen ID

Caller #1 refreshes once while #2–#4 suspend; upon wakeup they see vault.genId != failedGenId and replay immediately.

Cons: Naive Retry

4 concurrent 401s fire 4 refresh calls; the auth server flags reuse of a rotated refresh token and revokes the entire session!

Verdict Single-Flight Mutex + Generation ID is mandatory whenever backends enforce rotating refresh-token security.
Tradeoff 04 60fps Smooth

On-Device Kalman Smoothing vs. Server-Only Map Matching

Pros: On-Device Kalman

Rejects urban-canyon GPS jumps in <1ms locally, powers 60fps puck interpolation, and works offline inside tunnels.

Cons: Server-Only

Adds 150–400ms network RTT before the car icon moves, freezes in tunnels, and still needs noisy raw data uploaded.

Verdict Hybrid: Run lightweight Kalman smoothing on-device for 60fps UI, and run full road-graph map matching server-side for fare & ETA accuracy.
Production Observability SLOs
Trip Reliability Targets
Location Batch Delivery 99.95% Zero-loss SQLite WAL Outbox
Vector Tile Cache Hit ≥ 92% L1 RAM + L2 Disk combined
False Logout Rate (401) < 0.001% Protected by Single-Flight Mutex
Active Trip Battery < 3.5% / hr Adaptive 5s / 30s duty cycle