WinWin — African Rideshare App 🚗

A React Native Expo rideshare app built for African communities. No Stripe. No cash. No commissions. Pay via M-Pesa (TinyPesa) for Kenya and Paystack for all other African countries. When a driver accepts your ride, both driver and passenger see animated "Win Win!" bubbles and hear a jingle.

---

Screenshots

Driver App

Home (Online Toggle)	Registration (4-Step)	Car Customization

Subscription	Driver Community	Safety Center

---

Passenger App

Home & Map	Book a Ride	Seat Selection

Price Negotiation	Confirm + WinWin Bubble	Passenger Community

---

Admin Dashboard (Moderator)

Overview	Safety Alerts	Driver Management	Payments

Admin is a moderator only. Admins can view and resolve safety alerts, verify drivers, and see payment logs. They cannot modify ride data or user profiles.

---

Features

Driver Side

• Registration — Name, phone, email, tax ID, driver's license photo (base64), passport photo, areas covered (54 African countries + counties)
• Online/Offline Toggle — On the home screen; only online drivers appear on the passenger map
• Ride Requests — Accordion notification bar drops from top with a 15-second hourglass countdown, non-optional vibration, and the countdown-driver-jingle.mp3 sound
• Car Customization — Choose from 10 colors; tap car to play Beep Beep or Win Win jingle (optional per driver setting)
• Subscription — Month 1 free (no deposit); Month 2+ $40 one-time registration + $20/month
• Community — All drivers joined automatically; post and read discussions
• Safety — Report incidents anonymously (identity hidden from other users, visible to admin)

Passenger Side

• Book a Ride — Search destination, view nearby drivers on map (real GPS when available)
• Seat Selection — Choose Shotgun, Back Left, or Back Right before confirming
• Price Negotiation — Max 2 rounds; 45-second countdown timer with tick sounds in the last 10 seconds; price auto-locks if timer expires
• Confirm Ride — Driver car icon shown; tap it to cycle through colors and play Beep Beep
• Arrival Alert — Passenger jingle plays from 10 seconds before driver arrives (for visually impaired users); optional vibration toggle
• Payment — M-Pesa (Kenya) or Paystack (other countries); webhook auto-confirms; animated success overlay with confetti
• Community — Unlocks after 5 completed WinWin rides; progress bar shown until unlocked
• Safety — View alerts, report incidents; identity not disclosed

Payment System

Country	Provider	Method
Kenya	TinyPesa	M-Pesa STK Push
All other African countries	Paystack	Mobile money / card
Foreigners (no mobile money)	Paystack	Card, $20 refundable deposit
Stripe	Never	Not used anywhere

Payment confirmation happens via webhook (/(api)/payment/webhook). The app polls the webhook endpoint every 3 seconds and shows an animated success overlay when confirmed.

Notification System

Both driver and passenger get an accordion notification bar that slides down from the top of the home screen:

Role	Triggers
Driver	New ride request (15s hourglass + non-optional vibration + jingle)
Passenger	Driver accepted ride, driver arriving, ride complete

The bar retracts (accordion collapse) after the user accepts, declines, or dismisses.

Safety Features

• License plate alerts — Reported vehicles pop up as periodic alerts for all drivers until verified found; go to Safety archive after 24 hours
• Anonymous incident reporting — User identity not disclosed; admin sees phone number only
• Ride ID recovery — Lost phone? Share phone number with support to retrieve rides by registration email

Privacy & Data

• Ride history is immutable — no delete endpoint; 12-month max retention
• Passwords can only be reset from the web browser (not from the app)
• Community data is gated by role (driver/passenger) and ride count (5 rides for passengers)

---

Tech Stack

Layer	Technology
Framework	React Native + Expo SDK 51
Auth	Clerk (email + phone)
Database	NeonDB (PostgreSQL)
Payments	TinyPesa (M-Pesa) + Paystack
Maps	Google Maps (data-saving mode)
Storage	expo-image-picker (base64)
Notifications	expo-notifications + NotificationBar component
Audio	expo-av
State	Zustand
Styling	NativeWind (Tailwind CSS)

---

Environment Variables

Create a .env.local file based on .env.example:

EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_...
DATABASE_URL=postgresql://...@...neon.tech/neondb
EXPO_PUBLIC_PLACES_API_KEY=AIza...
EXPO_PUBLIC_DIRECTIONS_API_KEY=AIza...
TINYPESA_API_KEY=...
PAYSTACK_SECRET_KEY=sk_...
EXPO_PUBLIC_PAYSTACK_PUBLIC_KEY=pk_...

---

Getting Started

# 1. Install dependencies
cd winwin-app
npm install

# 2. Set up environment variables
cp .env.example .env.local
# Fill in your keys

# 3. Run database schema
# Copy database/schema.sql and run against your NeonDB instance

# 4. Start the app
npx expo start

# 5. For webhook testing (local dev), use ngrok:
ngrok http 8081
# Then set PAYSTACK_WEBHOOK_URL and TINYPESA_CALLBACK_URL to your ngrok URL + /(api)/payment/webhook

---

Database Schema

See database/schema.sql for the full PostgreSQL schema including:

• users — passengers and drivers
• driver_profiles — registration, GPS, car color, subscription
• rides — immutable ride history (12-month filter)
• community_posts — driver and passenger communities
• safety_alerts — anonymous incident reports (24h to archive)
• driver_subscriptions — free trial detection + paid plans
• payment_logs — webhook-confirmed payment records
• price_negotiations — negotiation round history
• tourist_deposits — refundable $20 deposits for foreigners

---

Sound Assets

File	Used When
winwin-ride.mp3	Driver accepts ride (WinWin bubble)
countdown-driver-jingle.mp3	New ride request arrives for driver (15s)
passenger-arrival-jingle.mp3	Driver is 10 seconds from passenger location
beep-beep.mp3	Car icon tapped on map; timer tick sounds
winwin-bonus.mp3	Bonus events

---

Repository

GitHub: https://github.com/komerela/winwin
Branch: main
Built with ❤️ for African communities — Win Win! 🎉