🚗 RoadMate

On-Demand Roadside Assistance Platform

Connecting stranded drivers with nearby mechanics — in real time.

---

📖 Overview

RoadMate is a real-time roadside assistance marketplace. When a driver breaks down, they raise a request; nearby mechanics are notified instantly, accept the job, and navigate to the driver — with live location tracking, in-app chat, and fare estimation throughout.

The platform sustains itself through a prepaid mechanic wallet: since driver↔mechanic payments happen in cash, RoadMate pre-collects revenue at recharge time and deducts a commission (default 5%) from the mechanic's wallet after each completed job.

Status: Feature-complete, pre-launch. Preparing for Google Play release — see the Roadmap.

---

✨ Features

👤 For Drivers

Feature	Description
🔧 Request Assistance	Broadcast a breakdown request to nearby mechanics in real time
🗺️ Find Mechanics	Browse nearby mechanics and workshops on an interactive map
📍 Live Tracking	Watch the assigned mechanic approach in real time
💬 In-App Chat	Message the mechanic directly once the request is accepted
🧠 Smart Diagnosis	Rule-based guided wizard that narrows down the likely fault before you call anyone
💰 Fare Estimation	Distance-based fare preview before confirming
🚨 SOS	One-tap emergency screen for critical situations
⭐ Ratings & Reviews	Rate the mechanic after job completion
📜 History	Full record of past requests and services

🔧 For Mechanics

Feature	Description
📢 Job Requests	Receive live push notifications for nearby breakdowns
🟢 Online / Offline	Toggle availability to control incoming jobs
👛 Prepaid Wallet	Top up balance; commission is auto-deducted per completed job
💳 Recharge	Submit an Easypaisa / JazzCash transaction for admin verification
🧾 Profile & Verification	Workshop details, services offered, experience, CNIC upload
📈 Earnings & Ratings	Auto-aggregated rating, computed server-side by Cloud Functions

🛡️ For Admins

Feature	Description
✅ Recharge Approval	Verify incoming payments and credit mechanic wallets
👥 User Management	Oversee drivers and mechanics
⚙️ Remote Pricing Config	Change commission rate, minimum balance, and visit fee from Firestore — no app rebuild required

---

🏗️ Architecture

RoadMate follows Clean Architecture with the MVVM presentation pattern. State is managed with provider.

lib/
├── models/          # Firestore-mapped data structures
│                    #   UserModel · DriverModel · MechanicModel
│                    #   ServiceRequestModel · WalletModel · ReviewModel
│                    #   ChatMessageModel · PricingConfig · NearbyMechanic
│
├── repositories/    # Data access — the ONLY layer that touches Firebase
│                    #   Auth · User · ServiceRequest · Tracking
│                    #   Review · Wallet · Storage · Diagnosis
│
├── viewmodels/      # State + business logic (ChangeNotifier)
│                    #   Auth · Request · Chat · Wallet
│
├── pages/           # Screens (Views)
│                    #   Auth · Driver/Mechanic/Admin Dashboards
│                    #   Chat · Wallet · Recharge · SOS · Profile · History …
│
├── components/      # Reusable widgets
│                    #   MapComponent · DiagnosisWizard · PaymentDialog
│                    #   RatingDialog · AppDrawer · MobileLayout
│
├── services/        # Domain services, framework-agnostic
│                    #   DiagnosisEngine · FareEstimator · LocationService
│                    #   MechanicFinder · NearbyShops · Notifications · EmailOTP
│
└── theme/           # Design system

Data flow

View  ──▶  ViewModel  ──▶  Repository  ──▶  Firebase
 ▲                                              │
 └──────────  notifyListeners()  ◀──────────────┘

Backend — Firebase

Service	Role
Cloud Firestore	Primary datastore — users, requests, wallets, reviews, chat
Realtime Database	High-frequency GPS location streaming (cheaper & faster than Firestore for this)
Cloud Storage	Profile photos, CNIC images
Cloud Messaging (FCM)	Push notifications for new & accepted requests
Cloud Functions	onNewRequest → notify nearby mechanics · onRequestAccepted → notify the driver · rating aggregation
App Check	Abuse protection

---

🚀 Getting Started

Prerequisites

• Flutter SDK ≥ 3.0.0 · Dart ≥ 3.0.0
• Node.js (for Cloud Functions)
• Firebase CLI — npm install -g firebase-tools
• A Google Maps API key

1. Clone & install

git clone https://github.com/abdullahsokay/RoadMate.git
cd RoadMate
flutter pub get

2. Firebase setup

Create a project in the Firebase Console, then enable:

• Authentication → Anonymous (backs the app's email-OTP session)
• Firestore Database
• Realtime Database (live location tracking)
• Cloud Storage (profile / CNIC uploads)
• Cloud Messaging

Register your Android app and drop google-services.json into android/app/. For iOS, drop GoogleService-Info.plist into ios/Runner/.

📄 Detailed walkthrough: FIREBASE_SETUP.md

3. Google Maps

Enable Maps SDK for Android / iOS in the Google Cloud Console, generate an API key, then:

Android — android/app/src/main/AndroidManifest.xml

<meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="YOUR_API_KEY_HERE"/>

iOS — ios/Runner/AppDelegate.swift

GMSServices.provideAPIKey("YOUR_API_KEY_HERE")

⚠️ Before going public: restrict the key to your Android SHA-1 + package name in the Cloud Console. An unrestricted Maps key that leaks will be abused and billed to your account.

4. Deploy Cloud Functions

cd functions
npm install
firebase login
firebase deploy --only functions

5. Security rules

firebase deploy --only firestore:rules,storage:rules,database

Rules live in firestore.rules, storage.rules, and database.rules.json.

6. Run

flutter run

---

💸 Wallet & Commission

Payments between driver and mechanic are settled in cash — so the platform can't skim a cut from the transaction itself. Instead:

1.  Mechanic recharges  PKR 1000   →  money lands in the platform account
2.  Wallet shows        PKR 1000   →  credit (a liability owed as service)
3.  Job completed       −5%        →  a slice becomes recognised revenue
4.  Balance < minimum   ⛔          →  mechanic can't accept new jobs until they top up

Revenue is therefore pre-collected at recharge time — no chasing commission payments, and only one account to manage.

Recharge is currently manual: the mechanic pays via Easypaisa/JazzCash and submits the Transaction ID; an admin verifies and credits the wallet. A payment-gateway integration (Safepay / PayFast / Paymob) is the planned upgrade for scale.

Commission rate, minimum balance, starting bonus, and visit fee are all read from Firestore (config/pricing) — change them without shipping a new build.

📄 Full details: RECHARGE_AND_COMMISSION.md · WALLET_SETUP.md

---

🧪 Testing

flutter test

Covers the diagnosis engine and the auth view-model.

---

🗺️ Roadmap to Production

• Change applicationId from com.example.roadmate to a real domain — Play Store rejects com.example.*
• Release signing — generate a keystore, wire up key.properties, sign the App Bundle
• Restrict the Maps API key to the release SHA-1 + package name
• Harden Firestore rules — the current identity model (anonymous auth keyed by an email-derived id) prevents per-owner rules; migrating to Firebase-native email/password auth would make request.auth.uid trustworthy
• Target SDK 35 — mandatory for new Play Store submissions
• Privacy Policy hosted at a public URL — required, as the app collects location, phone, and payment data
• Data Safety form in the Play Console
• Payment gateway integration to automate recharges
• Store listing assets — icon, feature graphic, screenshots

---

🛠️ Tech Stack

Layer	Technology
Framework	Flutter · Dart
State	Provider (MVVM)
Backend	Firebase — Firestore · Realtime DB · Storage · Auth · FCM · Functions · App Check
Maps & Location	google_maps_flutter · flutter_map · geolocator · location
Media	image_picker · flutter_image_compress
Utilities	flutter_local_notifications · url_launcher · share_plus · crypto · intl

---

📁 Project Layout

RoadMate/
├── lib/                 # Flutter application source
├── functions/           # Firebase Cloud Functions (Node.js)
├── android/  ios/       # Native platform shells
├── web/  windows/  …    # Additional Flutter targets
├── test/                # Unit & widget tests
├── firestore.rules      # Firestore security rules
├── storage.rules        # Cloud Storage security rules
├── database.rules.json  # Realtime Database rules
└── firebase.json        # Firebase project config

---

Built with Flutter & Firebase