Requirements

Functional Requirements:

• Track and display the location of users and available drivers on a map.
• Request a ride and match users with the nearest available driver.
• Allow drivers to accept or reject ride requests.

Non-Functional Requirements:

**Availability**

- Core ride request and driver matching path should target 99.99% availability.

- Location display can degrade gracefully with slightly stale data.

**Latency**

- Driver location update ingestion: p95 < 200 ms.

- Nearby driver lookup: p95 < 300 ms.

- Ride match decision: p95 < 1-2 seconds.

- Driver accept/reject propagation: p95 < 500 ms.

**Scalability**

- Support millions of users and hundreds of thousands of concurrent drivers.

- Handle high-frequency location updates, for example every 2-5 seconds per active driver.

- Partition traffic geographically using city/region cells.

**Reliability and Fault Tolerance**

- Use durable event streams for ride state transitions.

- Use idempotency keys for passenger ride requests and driver accept actions.

- Use retries with exponential backoff and jitter.

- Use graceful degradation when maps, notifications, or real-time channels are partially unavailable.

**Resilience**

- Avoid synchronous dependency chains in the critical path.

- Use circuit breakers around Maps, ETA, Notification, and Pricing services.

- Use regional failover for critical services.

• - Use replayable Kafka topics for recovery.

API Design

### Passenger APIs

```http

POST /v1/rides

Authorization: Bearer <token>

Idempotency-Key: <uuid>

Content-Type: application/json

{

"pickup": {

"lat": 37.7749,

"lng": -122.4194

},

"destination": {

"lat": 37.7849,

"lng": -122.4094

},

"ride_type": "standard"

}

```

Response:

```json

{

"ride_id": "ride_123",

"status": "REQUESTED",

"estimated_wait_seconds": 180

}

```

```http

GET /v1/rides/{ride_id}

```

```json

{

"ride_id": "ride_123",

"status": "DRIVER_ASSIGNED",

"driver": {

"driver_id": "driver_456",

"location": {

"lat": 37.7751,

"lng": -122.4188

},

"eta_seconds": 180

}

}

```

```http

GET /v1/drivers/nearby?lat=37.7749&lng=-122.4194&radius_meters=3000

```

Response:

```json

{

"drivers": [

{

"driver_id": "driver_456",

"lat": 37.7751,

"lng": -122.4188,

"eta_seconds": 180

}

]

}

```

### Driver APIs

```http

POST /v1/drivers/{driver_id}/location

Authorization: Bearer <token>

Content-Type: application/json

{

"lat": 37.7751,

"lng": -122.4188,

"heading": 125,

"speed_mps": 8.5,

"timestamp_ms": 1716000000000

}

```

```http

POST /v1/rides/{ride_id}/accept

Authorization: Bearer <token>

Idempotency-Key: <uuid>

Content-Type: application/json

{

"driver_id": "driver_456",

"offer_id": "offer_789",

"offer_version": 3

}

```

```http

POST /v1/rides/{ride_id}/reject

Authorization: Bearer <token>

Content-Type: application/json

{

"driver_id": "driver_456",

"offer_id": "offer_789",

"reason": "TOO_FAR"

}

```

### Real-Time Channels

```text

WebSocket /v1/realtime/passenger

WebSocket /v1/realtime/driver

```

Used for:

- Driver location updates to passengers.

- Ride request offers to drivers.

- Ride status updates.

- Driver accept/reject responses.

- Fallback to push notifications if WebSocket is unavailable.

High-Level Design

Core Services

API Gateway

• Terminates TLS.
• Performs authentication, request validation, and rate limiting.
• Routes passenger and driver traffic to internal services.

Location Service

• Ingests driver and passenger location updates.
• Stores current driver locations in Redis GEO or an H3/geohash-indexed Redis cluster.
• Publishes location events to Kafka for analytics, fraud detection, and historical storage.
• Keeps only hot, recent location data in memory with TTL.

Nearby Driver Service

• Queries available drivers by geo cell.
• Expands search ring progressively: nearby cell first, then adjacent cells.
• Filters by driver availability, ride type, distance, ETA, fraud/risk flags, and active offer status.

Ride Service

• Owns the ride state machine.
• Stores durable ride records in a relational database such as PostgreSQL, CockroachDB, or Spanner.
• Ensures valid state transitions.

Matching Service

• Selects candidate drivers.
• Sends offers using a controlled dispatch strategy.
• Handles driver accept/reject/timeout.
• Uses leases to avoid assigning the same driver to multiple passengers.

Dispatch/Notification Service

• Sends ride offers to drivers over WebSocket.
• Falls back to push notifications.
• Applies fanout limits, jitter, and backpressure.

Driver Availability Service

• Tracks whether a driver is available, offered, accepted, on-trip, offline, or suspended.
• Uses short-lived leases to prevent double assignment.

ETA/Maps Service

• Calculates route distance and ETA.
• Uses cache and circuit breaker because external map APIs can be slow or unavailable.

Event Bus

• Kafka/Pulsar used for ride events, location events, matching events, notification events, and audit logs.

Storage

Redis GEO / H3 Index

• Hot current locations.
• TTL-based expiry, for example 10-30 seconds.
• Partitioned by region/city/cell.

Relational DB

• Source of truth for ride lifecycle, driver assignment, payment reference, and audit metadata.

Cassandra/Scylla/Bigtable

• High-volume location history and event logs.
• Optimized for append-heavy writes.

Kafka

• Durable asynchronous communication.
• Replayable event stream for recovery and analytics.

Detailed Component Design

5.1 Location Tracking

Drivers send location updates every few seconds while online.

Flow:

1.DriverApp sends location update.

2.API Gateway authenticates and rate-limits the request.

3.Location Service validates freshness and accuracy.

4.Current location is written to Redis GEO/H3 index with TTL.

5.Location event is published to Kafka.

6.Location history is asynchronously persisted.

Important details:

• Ignore stale updates using timestamp_ms.
• Use TTL to automatically remove inactive drivers.
• Partition by city or geo cell to avoid global hot partitions.
• Use client-side batching or adaptive frequency to reduce load.
• Do not write every location update to the relational database.

Example Redis key strategy:

5.2 Nearby Driver Display

Passenger map does not need perfectly accurate real-time global state.

Flow:

1.Passenger app requests nearby drivers.

2.Nearby Driver Service queries Redis GEO/H3 cells around passenger pickup.

3.Service filters unavailable or stale drivers.

4.Service optionally estimates ETA.

5.Service returns a small sample of nearby drivers.

Optimizations:

• Return approximate driver markers, not exact full fleet state.
• Cache nearby driver results for a few seconds.
• Downsample map updates under load.
• Use WebSocket updates for active ride tracking only.

5.3 Ride Request Flow

Flow:

1.Passenger calls POST /v1/rides with an idempotency key.

2.Ride Service creates a ride in REQUESTED state.

3.Ride Service publishes RideRequested event.

4.Matching Service consumes the event.

5.Matching Service queries nearby available drivers.

6.Matching Service creates a short-lived offer for one or a small batch of drivers.

7.Dispatch Service sends offer to driver.

8.Driver accepts, rejects, or times out.

9.First valid accept transitions ride to DRIVER_ASSIGNED.

Ride state machine:

5.4 Matching Algorithm

Basic matching score:

Candidate search:

• Start with pickup H3/geohash cell.
• Expand to neighboring rings.
• Stop when enough candidates are found or max radius is reached.
• Prefer ETA over raw distance.

Dispatch strategy:

• Do not broadcast to all nearby drivers.
• Send to best driver first.
• If timeout, send to next candidate.
• Optionally send to a small batch, for example 2-3 drivers, with strict accept arbitration.

5.5 Driver Accept/Reject Handling

Driver acceptance must be race-safe.

Use:

• offer_id
• offer_version
• ride_id
• driver_id
• idempotency key
• compare-and-swap state transition

Accept logic:

Then atomically:

• Set ride status to DRIVER_ASSIGNED.
• Set assigned driver ID.
• Mark driver as ON_TRIP or ASSIGNED.
• Expire competing offers.

This can be implemented using:

• DB transaction with conditional update.
• Optimistic locking using ride version.
• Redis lease plus durable DB commit.
• Unique constraint on active driver assignment.

Example constraint:

5.6 Thundering Herd Handling

A thundering herd can happen when many passengers request rides during peak time, or when one ride request is broadcast to too many drivers.

Mitigations:

• Use controlled candidate fanout instead of broadcast.
• Use staged dispatch: first best driver, then next few after timeout.
• Add random jitter to retries and offer timeouts.
• Use per-region matching queues.
• Use backpressure when matching queues grow.
• Use surge pricing or demand shaping as product-level load control.
• Use token buckets per region for matching attempts.
• Cache ETA results to avoid hammering Maps Provider.
• Use circuit breakers around external dependencies.
• Apply per-driver offer locks so one driver is not spammed by many ride requests.

Example:

5.7 Idempotency

Idempotency is required because clients retry during mobile network failures.

Passenger ride request:

• Client sends Idempotency-Key.
• Server stores result by (user_id, idempotency_key).
• Repeated request returns the original ride_id.
• Prevents duplicate rides.

Driver accept:

• Client sends Idempotency-Key.
• Server deduplicates by (driver_id, ride_id, offer_id, idempotency_key).
• If accept already succeeded, return same success response.
• If another driver already accepted, return conflict.

Location update:

• Use timestamp and sequence number.
• Ignore older updates.
• Location updates are naturally idempotent because latest value wins.

5.8 Rate Limiting

Apply layered rate limits.

At API Gateway:

• Per user.
• Per driver.
• Per IP/device.
• Per endpoint.

Examples:

Adaptive controls:

• Lower location update frequency during overload.
• Return cached nearby driver results.
• Shed non-critical map display traffic before ride request traffic.
• Use HTTP 429 with retry-after.
• Use WebSocket backpressure for real-time channels.

5.9 Reliability and Resilience

Critical-path reliability:

• Ride state is stored durably before dispatch begins.
• Ride events are published to Kafka using transactional outbox pattern.
• Matching workers are stateless and horizontally scalable.
• Failed matching jobs can be retried from Kafka.
• Expired offers are handled by scheduled workers or delayed queues.

Transactional outbox:

1.Write ride state and outbox event in same DB transaction.

2.Outbox publisher sends event to Kafka.

3.Consumer processes event idempotently.

4.Consumer stores processed event ID to avoid duplicate side effects.

Failure examples:

• If WebSocket fails, use push notification fallback.
• If Maps Provider fails, use cached ETA or haversine distance.
• If Redis fails, degrade nearby display and use replicated Redis cluster.
• If Matching Service fails, Kafka retains ride request events for retry.
• If one region fails, route users to backup region when possible.

5.10 Availability and Scalability

Scale by geography:

• Partition users, drivers, and ride matching by region.
• Keep matching local to a city/region.
• Avoid cross-region synchronous calls during matching.

Service scaling:

• API Gateway scales horizontally.
• Location Service scales by Kafka partitions and geo shards.
• Matching Service scales by regional queues.
• Redis GEO cluster scales by region and H3/geohash partition.
• Kafka scales by topic partitions.

Data partitioning:

5.11 Performance Metrics

Track both system and product metrics.

System metrics:

• API request latency p50/p95/p99.
• Location ingestion QPS.
• Location update freshness.
• Redis GEO query latency.
• Kafka consumer lag.
• Matching queue depth.
• Matching latency.
• DB transaction latency.
• WebSocket connection count.
• Notification delivery latency.
• Error rate by service.
• Retry rate and timeout rate.
• External Maps Provider latency/error rate.

Product metrics:

• Ride request to driver assigned latency.
• Driver acceptance rate.
• Driver rejection rate.
• No-driver-found rate.
• Passenger cancellation rate.
• Driver cancellation rate.
• Average pickup ETA.
• Completed rides per region.
• Supply-demand imbalance per region.

Suggested SLOs:

5.12 Security and Privacy

• Authenticate all passenger and driver requests.
• Authorize driver actions against driver_id.
• Encrypt data in transit and at rest.
• Store only necessary location history.
• Restrict exact driver location visibility before assignment.
• Use fraud detection for GPS spoofing, impossible movement, and fake availability.
• Redact sensitive data from logs.