Geolocation & Routing is the spatial substrate of RideNow. It answers “where are our drivers right now, which of them are near this pickup, how long until that pickup, which route is best, and is this area surging?” It has almost no lifecycle state of its own — it is a continuous ingestion of location updates plus a set of fast-read services that other contexts (primarily Ride Management) consume. The one piece of active domain logic is surge: detect imbalance in a zone, publish a multiplier, retire it when supply catches up. The ubiquitous language — GeoCoordinate, Route, ETA, SurgeMultiplier, SurgeZone — is shared with the system requirements and domain model.

Product statement

Vision. Geolocation is invisible when it works and catastrophic when it doesn’t. RideNow’s spatial services are fast, accurate, and honest — they reject garbage inputs, they say “I don’t know” rather than guess, and they show surge pricing before a rider commits.

Scope. Location-update ingestion, online-driver positioning, nearby-driver queries ordered by ETA to pickup, ETA and route computation, periodic destination-ETA refresh during a ride, ETA variance alerts, dynamic route recalculation on traffic changes, surge-zone detection and deactivation, surge multiplier cap.

Non-goals. Map rendering (frontend concern), turn-by-turn navigation UX (driver-app concern), historical trip analytics, long-term driver-trajectory storage beyond the current online session.

Problem statement (SCQ)

  • Situation. Ride Management needs to find the closest driver fast; riders need accurate ETAs both at offer time and continuously during the ride; drivers need optimal routes adjusted for traffic; the platform needs to balance supply and demand in congested zones.
  • Complication. Location signals are noisy (low-accuracy GPS, stale timestamps, ghost-online drivers); ETAs drift quickly in urban traffic; surge pricing is a PR and regulatory landmine if set too high or applied silently; once a fare is committed at confirmation, later surge cannot retroactively apply without breaking the upfront-fare promise.
  • Question. How do we deliver fast, accurate spatial services under real-world data-quality conditions, refresh ETAs often enough to stay trustworthy, and apply surge pricing that clears demand without feeling predatory or surprising the rider after commit?

Personas & jobs

  • Ride Management (system persona). The main consumer. Jobs: “find me the closest match-eligible driver for this pickup”, “tell me the ETA at offer time and while the ride runs”, “give me the route”, “tell me if the ETA suddenly grew so I can warn the rider”.
  • Full-time driver / Part-time driver (indirect). Their devices stream position updates while online; they consume routes and re-routes. Job: “keep me match-eligible without manual action; show me the best way to pickup and to dropoff, and update when traffic changes”.
  • Daily commuter rider / Occasional traveler rider (indirect). See ETAs and surge multipliers in the rider app. Jobs: “trust the ETA I’m seeing”, “see surge before I commit, never after”.
  • Operations / Pricing team. Tunes surge thresholds and the per-market multiplier cap. Job: “detect and clear supply-demand imbalance without triggering customer backlash or regulatory exposure”.

Features, stories & acceptance criteria

Feature: real-time driver positioning

Problem addressed: all downstream functions (matching, ETA, in-ride tracking) depend on accurate, fresh position data.

  • Story — Position updates in the background. “As a full-time driver, I want my position to update in the background, so that I stay match-eligible without manual action.”
    • AC: When an online driver’s device sends a location update, the system records the position with a timestamp and makes it available for proximity queries. (REQ-GEO-001)
    • AC: While the driver is online, updates are accepted and persisted at a minimum frequency of one every 5 seconds. (REQ-GEO-002)
    • AC: If a driver’s last update is older than 60 seconds, the driver is marked ineligible for matching and Driver Management is notified. (REQ-GEO-003)
  • Story — Filter low-accuracy fixes. (platform-driven)
    • AC: Updates with horizontal accuracy worse than 100 meters are discarded. (REQ-GEO-004)

Feature: ETA and routing

Problem addressed: matching, in-ride tracking, and rider trust all depend on ETAs that reflect reality, not a static estimate.

  • Story — Nearby driver query. (Ride Management requests, Geolocation responds)
    • AC: When queried with a pickup location and search radius, the system returns online, match-eligible drivers within the radius, ordered by estimated time to pickup. (REQ-GEO-010)
  • Story — Pickup ETA computation. (Ride Management requests at offer time)
    • AC: When an ETA is requested between a driver’s current location and a pickup point, the system returns a traffic-aware travel time. (REQ-GEO-011)
  • Story — Route computation. (consumed by driver app and rider app)
    • AC: When a route is requested between pickup and dropoff, the system returns the optimal polyline with total distance and estimated duration. (REQ-GEO-012)
  • Story — Destination ETA stays accurate during the ride. “As a daily commuter rider, I want the ETA to destination to stay accurate during the ride, so that I can let the person I am meeting know when I will arrive.”
    • AC: While a ride is in progress, a refreshed destination ETA is published to Ride Management at least every 30 seconds. (REQ-GEO-013)
    • AC: While a ride is in progress, if the refreshed destination ETA grows more than 5 minutes from the previous published value, an ETA variance alert is raised to Ride Management. (REQ-GEO-014)
  • Story — Dynamic route recalculation. (platform-driven)
    • AC: While a ride is in progress, when traffic changes significantly on the current route, the route is recomputed and Ride Management is notified. (REQ-GEO-015)

Feature: surge zone transparency

Problem addressed: supply-demand imbalance must be cleared; riders must not feel gouged or surprised; drivers must be incentivized to move; surge must respect the upfront-fare promise.

  • Story — Detect and declare a surge zone. (platform-driven)
    • AC: When the ride-requests-to-available-drivers ratio in a zone exceeds the surge threshold, the zone is declared surging and a SurgeActivated event is published with the multiplier and contributing factor. (REQ-GEO-020)
  • Story — Deactivate when supply catches up. (platform-driven)
    • AC: When the ratio returns below threshold for at least 5 minutes, surge is deactivated and a SurgeDeactivated event is published. (REQ-GEO-021)
  • Story — Hard cap on surge multiplier. (regulatory / PR protection)
    • AC: The system enforces a platform-wide maximum surge multiplier of 5.0x, with a lower per-market cap where regulation requires it. (REQ-GEO-022)
  • Story — Surge visible at fare estimate. “As a daily commuter rider, I want to see the surge multiplier before I confirm, so that there are no surprises.”
    • AC: When a rider requests a fare estimate in a surging zone, the multiplier and contributing factor are included in the response and shown on the fare estimate screen. (REQ-GEO-023)
  • Story — Surge frozen at confirmation. “As a daily commuter rider, I want the fare I confirmed to be the fare I pay.”
    • AC: Surge adjustments are not applied to a ride after the fare has been committed at confirmation. (REQ-GEO-024)

Goals & success metrics

  • Nearby-driver query latency p95 ≤ 500 ms. (REQ-GEO-NFR-001) — matching latency budget flows directly into Geolocation response time; above this, the 60-second match SLO breaks.
  • ETA computation latency p95 ≤ 500 ms. (REQ-GEO-NFR-002) — ETA is on the fare-estimate critical path; the rider’s 3-second target depends on it.
  • Location-update ingestion ≥ 10,000 updates per second per market. (REQ-GEO-NFR-003) — every online driver pushes a position every 5 seconds, so peak traffic scales with supply density.
  • Granular location retention ≤ 90 days. (REQ-GEO-NFR-004) — older data is aggregated into non-personal summaries; retain the minimum necessary under GDPR and equivalents.
  • Surge zone half-life ≤ 15 minutes under normal conditions. Persistent surge means the supply response is broken — investigate before raising thresholds.
  • Discard rate for incoming location updates ≤ 5% (stale + low-accuracy combined). Above this, driver-app telemetry is the bottleneck; below 1% the filters may be too loose.

Constraints

  • Regulatory. Surge pricing is capped by regulation in several jurisdictions (some bar surge during declared emergencies). The 5.0x ceiling is an internal floor; market-specific policies may cap lower, applied through configuration rather than code changes. Source: PRD risk “Regulator caps or bans surge pricing in a key market”.
  • Privacy. Driver real-time position is only available to Ride Management during an active ride context; no bulk access outside authorized operational contexts. Granular location history is retained no longer than 90 days under GDPR / CCPA equivalents.
  • Technical. Location data is transient — Geolocation does not retain historical driver trajectories beyond the current online session; long-term movement analytics live in a separate analytics context (out of scope).
  • Operational. The platform-wide surge cap is enforced at the value-type level (SurgeMultiplier.value <= 5.0); per-market caps are applied as configuration before activation.

Traceability. Every feature above references REQ-GEO-… identifiers formalized in the System Requirements page. Those requirements become value types, entities, queries, services, and events in the Domain Model page. Surge events (SurgeActivated, SurgeDeactivated) cross the boundary into Ride Management through a Published Language pattern; nearby-driver queries are exposed as an Open Host Service; stale-position notifications cross to Driver Management through an Anti-Corruption Layer.