PillionPal – Real-Time Ride-Sharing Backend

FastAPI backend powering a motorcycle & scooter ride-sharing platform. Supports secure OTP login, JWT sessions, WebSocket GPS streaming, user wallets, and mileage-based pricing through FairSplit.

FastAPI

PostgreSQL

WebSockets

JWT Auth

OTP Login

FairSplit Engine

Live Demo Source Code

Backend Architecture

Client → FastAPI → WebSockets → PostgreSQL

OTP login → JWT session (access + refresh)
Live WebSocket channel for driver ↔ rider location
Wallet balance synced with ride completion
FairSplit calculates fare using mileage & fuel factor
Uses MapBox for distance & route visualization

API Endpoints

JSON APIs consumed by Flutter mobile client.

AUTH
POST /auth/send-otp               -> Sends OTP
POST /auth/verify-otp            -> Issues JWT tokens (HTTP-only cookies)
PUT  /auth/change_password       -> Change user password
DELETE /auth/delete_account      -> Removes account

BIKE & RIDER
POST /bike/register              -> Register bike details
POST /rider/register             -> Register rider profile
GET  /get-rider-details          -> Fetch bike & rider linked info

RIDES
POST /rider/request_ride         -> Rider requests trip
GET  /pillion/ride_requests      -> Pillion sees pending requests
PUT  /pillion/update_ride        -> Accept / cancel / complete ride

HISTORY
GET  /history/rider              -> Rider ride history
GET  /history/pillion            -> Completed pillion trips

Sample Requests & Responses

Used by mobile client and testing scripts.

# Login (OTP Verification)
POST /auth/verify-otp
{
  "phone": "9876543210",
  "otp": "543210"
}

# Response
{
  "message": "Login successful",
  "token": "JWT_TOKEN",
  "refresh": "REFRESH_TOKEN"
}

# Requesting a Ride
POST /rider/request_ride
{
  "from": "MVP Colony",
  "to": "Rushikonda",
  "distance_km": 8
}

# Response
{
  "ride_id": 22,
  "fare": 58.0,
  "status": "waiting_for_pillion"
}

# WebSocket Live Location
ws://api.pillionpal.com/live?ride_id=22
{
  "latitude": 17.7829,
  "longitude": 83.3832,
  "speed": 42
}

Authentication & Sessions

Zero-password flow using OTP + JWT.

✅ OTP verification issues JWT (access + refresh)

✅ Tokens stored in HTTP-only cookies → cannot be stolen by JS

✅ Refresh endpoint renews expired sessions safely

Real-Time GPS (WebSockets)

Driver broadcasts, rider receives live map updates.

Low latency streaming
Auto-reconnect on network drop
Arrival detection & trip closure based on GPS

FairSplit – Mileage-Based Pricing

fare = base_fare + (distance_km * (1/mileage) * fuel_cost)

Fair to both rider & pillion based on real fuel usage.

Wallet System

Balance stored in PostgreSQL
Deduction only after ride success
Ledger history for transparency

Challenges & Solutions

GPS delay → optimized broadcast interval
Network drops → auto reconnect sync
Ride fraud → audit timestamps + user actions

What I Learned

✅ WebSocket event pipelines

✅ OTP login + JWT refresh tokens

✅ Pricing & billing logic

✅ Mobile network handling in real-time apps