How To Design A Ride-hailing System?

This post is about to design a ride-hailing system such as Uber, Lyft.

Author: Wei Xia (hi@weixia.dev)

Introduction

This document is designed to be a reference of the Uber Ride-sharing System, and it describes architecture and sub-architecture with their associated interfaces, database schemas, and the motivations behind the chosen design. Both high-level and low-level designs are included in this document.

The challenge for the Uber Ride-sharing System as a whole is to satisfy the dynamic demand from passengers side and the dynamic supply from drivers side. This system design document is to provide the guideline to accomplish this challenge, and make the entire system work in a cost effective and time efficient manner.

Purpose

The ability to match ride demands from passengers and ride supplies from drivers are the essential function of this Uber Ride-sharing System. Uber App is currently providing ride sharing service in a 5M population urban city. After downloading the app, passengers can submit their ride request by sending their real-time location, and Uber App will match the nearby drivers within certain range of distances. With a successful match, the driver can pick up the passengers and start the route to the destination passenger request.

System Overview

The system is mainly providing the following functionalities:

1. Passengers and drivers can set up their profile while using Uber App.
2. Passengers and drivers can use Uber App to update their real-time location.
3. Passengers can use Uber App to submit their trip request.
4. Uber Ride-sharing System can match nearby drivers and assign them to each valid trip.
5. Drivers can use Uber App to pick up passengers, complete order and get earnings on each trip.

To effectively provide functionalities above, we have designed the following microservices below to enable Uber Ride-sharing System workflow:

1. Trip Gateway Service - Core service, match passenger’s demand and driver’s supply
2. Map & Route Service - Provide map service including routes, arrival time.
3. Driver Location Service - Store and retrieve drive location & availability status
4. Trip Service - Store trip information for retrieving purpose
5. Passenger Profile Service - Store passengers profile information
6. Driver Profile Service - Store driver profile information
7. Payment Service - Utility service to handle payment related functions
8. Review Service - Utility service to handle review functions

In the rest of this system design document, it will layout out how each microservice works in details, and how different microservices connect together.

Under each microservice section, it presents the diagram of incoming and outgoing services, also along with API architecture & definitions. Each section also presents API sample requests as reference, also with database design and schema samples if any database involves.

Design Consideration

Assumptions and Dependencies

End-user characteristics:

• Passengers:
  • Able to request a ride by giving their real-time location
  • Able to complete the ride with valid payment method
• Drivers:
  • Able to find a ride order by giving their real-time location
  • Able to pick up the passengers and drive them to the final destination

System Architecture

System Architecture Diagram

Sequence Diagram

System Microservices

Before jumping into microservices details, I would like to give brief background on how to select API architecture. All microservices are chosen to use either RPC (Remote Procedure Call) or REST(REpresentational State Transfer). Below are the differences between those two architecture, we choose either of them for each microservice based on business need and best performance.

RPC (Remote Procedure Call):

• Best practice for action call since it’s functions or methods driven.
• Request is optimized for speed.
• Data compression saves network bandwidth.

REST(REpresentational State Transfer):

• Best practice for handling well-organized entities, data and resource, such as profile, trip
• Supports most CRUD-based operations such as GET, POST, PUT, DELETE, OPTIONS

Trip Gateway Service

Trip Gateway Service is the core service to connect drivers and passengers clients, and is built with RPC architecture to provide quick and small data transfer request. Clients can establish the connection via WebSocket to provide real-time and continuous communication method.

The primary responsibilities and/or behavior of Trip Gateway Service as listed below:

• Create Web Socket connections with drivers client apps to get their real-time location
• Update drivers availability status
• Handle passengers’ book request
• Update trip details & status both for drivers and passengers

API Example

update-driver-location: this method will get drivers’ location for every 5 seconds, and send the location to Driver Location Service.

API request example:

curl --request POST \
  --url https://www.example.com/api/v1/trip-gateway \
  --header 'Authorization: Bearer 1g1ZDYYW6.yPIJwOM56nzz8V6O' \
  --header 'Content-Type: application/json' \
  --header 'cache-control: no-cache' \
  --data '{
		"jsonrpc": "2.0",
		"method": "update-driver-location",
		"params": [{
			"driver-user-id": "1234567",
			"latitude": "40.7499014",
			"longitude": "-73.8859444"}],
		"id": 1
	}'

update-driver-status: this method will get or update drivers’ availability status, and send the status to Driver Location Service.

API request example:

curl --request POST \
  --url https://www.example.com/api/v1/trip-gateway \
  --header 'Authorization: Bearer 1g1ZDYYW6.yPIJwOM56nzz8V6O' \
  --header 'Content-Type: application/json' \
  --header 'cache-control: no-cache' \
  --data '{
		"jsonrpc": "2.0",
		"method": "update-driver-status",
		"params": [{
			"driver-user-id": "1234567",
			"status": "active"}],
		"id": 1
	}'

submit-trip-request: this method will handle passengers’ book request, once the submission is successful, it will generate a unique trip-id to store in Trip Record Service.

API request example:

curl --request POST \
  --url https://www.example.com/api/v1/trip-gateway \
  --header 'Authorization: Bearer 1g1ZDYYW6.yPIJwOM56nzz8V6O' \
  --header 'Content-Type: application/json' \
  --header 'cache-control: no-cache' \
  --data '{
		"jsonrpc": "2.0",
		"method": "submit-trip-request",
		"params": [{
			"passenger-user-id": "1234567-98765",
			"pick-up-latitude": "40.7499014",
			"pick-up-longitude": "-73.8859444",
			"destination-latitude": "38.74329041",
			"destination-longitude": "-75.8853444"}],
		"id": 1
	}'

update-trip-detail: this method will provide the ability to update the exiting trip details both for drivers and passengers. In the request example, it helps passengers to update their destinations.

API request example:

curl --request POST \
  --url https://www.example.com/api/v1/trip-gateway \
  --header 'Authorization: Bearer 1g1ZDYYW6.yPIJwOM56nzz8V6O' \
  --header 'Content-Type: application/json' \
  --header 'cache-control: no-cache' \
  --data '{
		"jsonrpc": "2.0",
		"method": "update-trip-detail",
		"params": [{
			"trip-id": "1234567-98765",
			"destination-latitude": "30.74329041",
			"destination-longitude": "-77.8853444"}],
		"id": 1
	}'

cancel-trip: this method will help passengers and drivers submit trip cancellation request.

API request example:

curl --request POST \
  --url https://www.example.com/api/v1/trip-gateway \
  --header 'Authorization: Bearer 1g1ZDYYW6.yPIJwOM56nzz8V6O' \
  --header 'Content-Type: application/json' \
  --header 'cache-control: no-cache' \
  --data '{
		"jsonrpc": "2.0",
		"method": "cancel-trip",
		"params": [{
			"trip-id": "1234567-98765"}],
		"id": 1
	}'

Map & Route Service

Map & Route Service is a utility service to provide any map related functionalities.

It’s built with RPC architecture.

The primary responsibilities and/or behavior of Map & Route Service as listed below:

• Generate the route by passing two point locations
• Calculate the estimated time for picking up passengers and sending them to the destination.

API Example

get-route: this method will generate the route for drivers by passing starting location and ending location.

API request example:

curl --request POST \
  --url https://www.example.com/api/v1/map-and-reoute \
  --header 'Authorization: Bearer 1g1ZDYYW6.yPIJwOM56nzz8V6O' \
  --header 'Content-Type: application/json' \
  --header 'cache-control: no-cache' \
  --data '{
		"jsonrpc": "2.0",
		"method": "get-route",
		"params": [{
			"start-latitude": "30.74329041",
			"start-longitude": "-77.8853444",
			"end-latitude": "33.35129041",
			"end-longitude": "-74.4673442"}],
		"id": 1
	}'

get-arrival-time: this method will return the arrival time by calculating starting location and ending location based on parameters.

API request example:

curl --request POST \
  --url https://www.example.com/api/v1/map-and-reoute \
  --header 'Authorization: Bearer 1g1ZDYYW6.yPIJwOM56nzz8V6O' \
  --header 'Content-Type: application/json' \
  --header 'cache-control: no-cache' \
  --data '{
		"jsonrpc": "2.0",
		"method": "get-arrival-time",
		"params": [{
			"start-latitude": "30.74329041",
			"start-longitude": "-77.8853444",
			"end-latitude": "33.35129041",
			"end-longitude": "-74.4673442"}],
		"id": 1
	}'

Driver Location Service

Driver Location Service is a service to store drivers locations in order to provide nearby driver list for passenger’s trip request.

It’s built with RPC architecture.

The primary responsibilities and/or behavior of Driver Location Service as listed below:

• Convert drivers’ location from longitude and latitude format into geohash and store them into the database
• Retrieve the nearby drivers list by giving a specific location and range

Database Table Schema

API Example

store-driver-location: this method will convert driver’s latitude and longitude location format into geohash and store them into the database for retrieving purpose.

API request example:

curl --request POST \
  --url https://www.example.com/api/v1/driver-location \
  --header 'Authorization: Bearer 1g1ZDYYW6.yPIJwOM56nzz8V6O' \
  --header 'Content-Type: application/json' \
  --header 'cache-control: no-cache' \
  --data '{
		"jsonrpc": "2.0",
		"method": "store-driver-location",
		"params": [{
			"driver-user-id": "1234567",
			"location-latitude": "30.74329041",
			"location-longitude": "-77.8853444"}],
		"id": 1
	}'

get-nearby-driver: this method will retrieve nearby driver-user-id list by passing the location and defined range.

API request example:

curl --request POST \
  --url https://www.example.com/api/v1/driver-location \
  --header 'Authorization: Bearer 1g1ZDYYW6.yPIJwOM56nzz8V6O' \
  --header 'Content-Type: application/json' \
  --header 'cache-control: no-cache' \
  --data '{
		"jsonrpc": "2.0",
		"method": "get-nearby-driver",
		"params": [{
			"passenger-location-latitude": "30.74329041",
			"passenger-location-longitude": "-77.8853444",
			"range": "300"}],
		"id": 1
	}'

Dispatch Service

Dispatch Service is a service to assign a driver for a trip based on different measures. Also it can process trip completion request and store the update in the Trip Record Service.

It’s built with RPC architecture.

The primary responsibilities and/or behavior of Dispatch Service as listed below:

• Assign the trip driver based on nearby driver location and their status, also update the driver into the trip record
• Complete the trip once passengers arrive the destination, and update the trip detail into the trip record

API Example

assign-trip-driver: this method will assign a driver to a specific trip based on availability and other measures

API request example:

curl --request POST \
  --url https://www.example.com/api/v1/dispatch-service \
  --header 'Authorization: Bearer 1g1ZDYYW6.yPIJwOM56nzz8V6O' \
  --header 'Content-Type: application/json' \
  --header 'cache-control: no-cache' \
  --data '{
		"jsonrpc": "2.0",
		"method": "assign-trip-driver",
		"params": [{
			"trip-id": "1234567-98765",
			"driver-list": [{
				"driver-user-id": "124-1234",
				"driver-distance": "10",
				"driver-arrival-time": "11"
			}, {
				"driver-user-id": "324-1232",
				"driver-distance": "12",
				"driver-arrival-time": "6"
			}, {
				"driver-user-id": "235-21321",
				"driver-distance": "14",
				"driver-arrival-time": "5"
			}]
		}],
		"id": 1
	}'

complete-trip: this method will mark this trip complete, and update in the trip record service

API request example:

curl --request POST \
  --url https://www.example.com/api/v1/dispatch-service \
  --header 'Authorization: Bearer 1g1ZDYYW6.yPIJwOM56nzz8V6O' \
  --header 'Content-Type: application/json' \
  --header 'cache-control: no-cache' \
  --data '{
		"jsonrpc": "2.0",
		"method": "assign-trip-driver",
		"params": [{
			"trip-id": "1234567-98765"
		}],
		"id": 1
	}'

Trip Record Service

Trip Record Service is a service to store and update trip related information, such as starting & ending location, driver id, passenger id, trip cost, and etc.

It’s built with REST API (HTTP) architecture.

The primary responsibilities and/or behavior of Trip Record Service as listed below:

• Update the trip details including starting and ending time, trip route, pickup and destination location, etc.
• Retrieve the trip details for drivers and passengers.

Database Table Schema

API Example

get-trip-detail: this method will return the trip metadata from database by passing tripId as unique identifier.

API request example:

curl --request GET \
  --url https://www.example.com/api/v1/trip-record/trips/123456789 \
  --header 'Authorization: Bearer 1g1ZDYYW6.PxT3AP2yJVYLCYX5' \
  --header 'cache-control: no-cache'

update-trip-record: this method will update the trip metadata in database by passing tripId and other field values.

API request example:

curl --request POST \
  --url https://www.example.com/api/v1/trip-record/trips/123456789 \
  --header 'Authorization: Bearer 1g1ZDYYW6.PxT3AP2yJVYLCYX5' \
  --header 'Content-Type: application/json' \
  --header 'cache-control: no-cache' \
  --data '{
		"trip-cost": "12"
	}'

Passenger Profile Service

Passenger Profile Service is a service to update passenger profile information related functionalities, such as home or work address, profile image, payment, and etc.

It’s built with REST API (HTTP) architecture.

The primary responsibilities and/or behavior of Passenger Profile Service as listed below:

• Retrieve & Update passenger’s profile information by passing passenger-user-id
• Retrieve this passenger’s trip history
• Add or update passenger’s payment method

Database Table Schema

API Example

get-passenger-info: this method will retrieve passenger’s profile by passing this passenger’s passenger-user-id

API request example:

curl --request GET \
  --url https://www.example.com/api/v1/passenger-service/profile/passengers/123456789 \
  --header 'Authorization: Bearer 1g1ZDYYW6.PxT3AP2yJVYLCYX5' \
  --header 'cache-control: no-cache'

update-passenger-info: this method will update passenger’s profile by passing this passenger-user-id and properties need to update.

API request example:

curl --request POST \
  --url https://www.example.com/api/v1/passenger-service/profile/passengers/123456789 \
  --header 'Authorization: Bearer 1g1ZDYYW6.PxT3AP2yJVYLCYX5' \
  --header 'Content-Type: application/json' \
  --header 'cache-control: no-cache' \
  --data '{
		"passenger-profile": {
			"home-address": "163 William Street, New York, NY 10001"
		}
	}'

retrieve-history-trip: this method will retrieve this passenger’s trip history

API request example:

curl --request GET \
  --url https://www.example.com/api/v1/passenger-service/profile/passengers/123456789/history-trip \
  --header 'Authorization: Bearer 1g1ZDYYW6.PxT3AP2yJVYLCYX5' \
  --header 'cache-control: no-cache'

update-payment-method: this method will help passenger to add or update payment methods.

API request example:

curl --request POST \
  --url https://www.example.com/api/v1/passenger-service/profile/passengers/123456789/payment \
  --header 'Authorization: Bearer 1g1ZDYYW6.PxT3AP2yJVYLCYX5' \
  --header 'Content-Type: application/json' \
  --header 'cache-control: no-cache' \
  --data '{
		"passenger-payment": {
			"card-number": "372653880041123",
			"card-type": "american-express",
			"card-verification-numer": "1234",
			"expiry-date": "2025-05",
			"zip-code": "10001"
		}
	}'

Driver Profile Service

Driver Profile Service is a service to update driver profile information related functionalities, such as driver car information, driver profile image, payout method, and etc.

It’s built with REST API (HTTP) architecture.

The primary responsibilities and/or behavior of Driver Profile Service as listed below:

• Retrieve & Update driver’s profile information by passing driver’s uid

Database Table Schema

API Example

get-driver-info: this method will retrieve driver’s profile by passing this driver-user-id.

API request example:

curl --request GET \
  --url https://www.example.com/api/v1/driver-service/profile/drivers/123456789 \
  --header 'Authorization: Bearer 1g1ZDYYW6.PxT3AP2yJVYLCYX5' \
  --header 'cache-control: no-cache'

update-driver-info: this method will update driver’s profile by passing this driver-user-id and update information fields.

API request example:

curl --request POST \
  --url https://www.example.com/api/v1/driver-service/profile/drivers/123456789/payment \
  --header 'Authorization: Bearer 1g1ZDYYW6.PxT3AP2yJVYLCYX5' \
  --header 'Content-Type: application/json' \
  --header 'cache-control: no-cache' \
  --data '{
		"driver-profile": {
			"music-preference": "jazz"
		}
	}'

Payment Service

Payment Service is a utility service to provide payment related functionalities, such as pre-verify passenger’s payment before submitting trip request, and send payout to drivers.

It’s built with RPC architecture.

The primary responsibilities and/or behavior of Payment Service as listed below:

• Pre-auth passenger’s payment before submitting trip request and avoiding any potential fraud activities.
• Send out driver’s payouts when drivers select to cash out.

API Example

payment-pre-auth-check: this method will validate passenger’s payment method, and allow or deny trip request.

API request example:

curl --request POST \
  --url https://www.example.com/api/v1/payment \
  --header 'Authorization: Bearer 1g1ZDYYW6.yPIJwOM56nzz8V6O' \
  --header 'Content-Type: application/json' \
  --header 'cache-control: no-cache' \
  --data '{
		"jsonrpc": "2.0",
		"method": "payment-pre-auth-check",
		"params": [{
			"credit-card": {
				"card-number": "372653880041123",
				"card-type": "american-express",
				"card-verification-numer": "1234",
				"expiry-date": "2025-05",
				"zip-code": "10001"}
		}],
		"id": 1
	}'

send-payout: this method will submit driver’s payout choice, and cash out their earnings.

API request example:

curl --request POST \
  --url https://www.example.com/api/v1/payment \
  --header 'Authorization: Bearer 1g1ZDYYW6.yPIJwOM56nzz8V6O' \
  --header 'Content-Type: application/json' \
  --header 'cache-control: no-cache' \
  --data '{
		"jsonrpc": "2.0",
		"method": "send-payout",
		"params": [{
			"driver-user-id": "1234567",
			"payout-account": "3274823647823"
		}],
		"id": 1
	}'

Review Service

Review Service is a utility service to provide review and rating related functionalities, such as drivers and passengers can submit reviews and rating for each other.

It’s built with RPC architecture.

The primary responsibilities and/or behavior of Review Service as listed below:

• Allow drivers and passengers to submit their reviews for each other
• Update the review and rating both for drivers and passengers

API Example

submit-review: this method will let drivers and passengers to submit reviews and rating.

API request example:

curl --request POST \
  --url https://www.example.com/api/v1/review \
  --header 'Authorization: Bearer 1g1ZDYYW6.yPIJwOM56nzz8V6O' \
  --header 'Content-Type: application/json' \
  --header 'cache-control: no-cache' \
  --data '{
		"jsonrpc": "2.0",
		"method": "send-payout",
		"params": [{
			"review-from": "1234567",
			"review-to": "4327423",
			"review-content": "very good driver",
			"rating": "5"
		}],
		"id": 1
	}'

---

This is the end of post