UnityRide 🚗⛪

A production-ready carpooling platform connecting church communities in South Africa. Solving the "last-mile" transport problem for Sunday services through secure, role-based ride sharing.

---

📖 The Problem & Solution

The Problem: In many South African communities, getting to church is a logistical challenge. Public transport is unreliable on weekends, and fuel costs are high. Meanwhile, many members drive to the same service with 3 empty seats.

The Solution: UnityRide is a centralised, secure platform that bridges this gap.

• For Drivers: A verified space to offer lifts and share fuel costs.
• For Riders: A safe way to book a seat with a known community member.
• For Admins: A dashboard to oversee safety and manage events.

---

⚙️ How It Works (Detailed Workflows)

1. The "Verified Driver" Workflow 🛡️

Safety is the core feature. Unlike generic ride apps, not everyone can be a driver.

• Step 1: User signs up and selects the "Driver" role.
• Step 2: They are initially marked as Unverified. If they try to post a ride, the system blocks them with a "Verification Required" guardrail.
• Step 3: The user submits their License & Vehicle details.
• Step 4: An Admin reviews the data in the Admin Dashboard and clicks "Verify".
• Result: The driver can now access the "Offer Ride" form, which automatically pulls their saved car model and plate number to save time.

2. The Real-Time Booking Engine ⚡

We use Firestore's real-time capabilities to handle bookings instantly.

• Discovery: Riders browse rides linked to specific events (e.g., "Sunday Service @ 09:00").
• Booking: When a rider clicks "Book Seat":
  1. The system runs a Firestore Transaction to check if seatsAvailable > 0.
  2. If yes, it atomically decrements the seat count and creates a booking record.
  3. If no (e.g., someone else clicked 1 millisecond earlier), the transaction fails and tells the user "Ride Full".
• Ticket: The rider receives a digital ticket with the Driver's contact info and pickup point.

3. Role-Based Access Control (RBAC) 🔐

The app serves three distinct user types with separate interfaces:

• Riders: Can only view events and book rides. Cannot access the "Offer Ride" page.
• Drivers: Can view their "My Rides" dashboard to see who has booked a seat.
• Admins: Have a hidden route (/admin) to verify users and create new church events.

---

🛠️ Technical Architecture

This project is built on a Serverless Architecture to ensure low cost and high scalability.

Frontend: Next.js 15 (App Router)

• Server Components: Used for fetching Events and User Data securely on the server (SEO friendly & fast).
• Client Components: Used for interactive elements like the "Book Now" button and Real-time listeners.
• Tailwind CSS: A "Mobile-First" design approach ensures the app feels native on smartphones.

Backend: Firebase (BaaS)

• Authentication: Manages sessions and custom user claims (Roles).
• Cloud Firestore: A NoSQL database structured to handle relational data (Users <-> Rides <-> Bookings).
• Security Rules: Row-level security ensures:
  • Riders can only edit their own profile.
  • Drivers can only delete their own rides.
  • Admins are the only ones who can write to the events collection.

---

📸 Screen-by-Screen Breakdown

1. The "Offer Ride" Smart Form

Not just a standard input form.

• Logic: It checks the Driver's profile before rendering.
• Feature: If the driver has a saved vehicle (e.g., "Toyota Corolla - ABC 123 L"), the form pre-fills these fields as "Read Only" to prevent typos and fraud.
• Pricing: Drivers can toggle between "Paid Seat" (e.g., R20) or "Free Ride" for ministry.

2. The Marketplace (Event View)

• Filter: Rides are filtered by eventId so users don't see rides for last week's service.
• Status Indicators: Rides automatically show badges like "3 Seats Left", "1 Seat Left" (Red), or "FULL" (Grayed out).

3. Admin Dashboard

• Table View: Displays a list of all users with a status chip (Verified / Unverified).
• Action: A single click on the "Verify" button updates the database live, triggering a toast notification.

---

📸 Screenshots

💻 Getting Started Locally

Prerequisites

• Node.js 18+
• A Firebase Project (Free Tier)

Installation

1. Clone the repo

   git clone [https://github.com/Ernest-22/unity-ride.git](https://github.com/Ernest-22/unity-ride.git)
   cd unity-ride

2. Install dependencies

   npm install

3. Setup Environment Variables Create a .env.local file and add your Firebase keys:

   NEXT_PUBLIC_FIREBASE_API_KEY=...
   NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=...
   NEXT_PUBLIC_FIREBASE_PROJECT_ID=...

4. Run the development server

   npm run dev

---

🔮 Future Roadmap (v2.0)

I am currently working on the next phase of UnityRide:

• Google Maps Integration: Visual pickup points using the Maps API.
• Email Notifications: Automated confirmation emails using EmailJS.
• PWA Support: Making the app installable for offline usage.

---

📬 Contact

Singo Ndivhadzo Ernest *Junior Software Developer | Next.js & React *

---

Built with ❤️ in South Africa 🇿🇦