Caby Monorepo Documentation

Comprehensive setup, configuration, database initialization, and customization guide for the Caby Ride-Hailing Platform.

1. Architecture & Overview

Caby is an end-to-end, enterprise-grade on-demand taxi and ride-booking solution built on modern serverless architecture. The entire project is organized as a unified Yarn Workspaces Monorepo, sharing common state logic, Firebase schemas, and configuration files across all platforms.

1.1 Workspaces Breakdown

Directory / Workspace Tech Stack Role & Responsibility
customer-app/ React Native, Expo SDK 54, React 19 Rider mobile application for booking trips, fare estimation, live vehicle tracking, chat, and card/wallet payments.
driver-app/ React Native, Expo SDK 54, React 19 Driver mobile application for accepting rides, GPS navigation, background location tracking, loud dispatch alerts, and earnings.
web-app/ React 19, Vite, Material UI (MUI v5), Deck.gl Web Administration Dashboard, Dispatcher Console, Zone/Fare Management, and public landing/marketing CMS pages.
functions/ Node.js, Firebase Cloud Functions, Stripe SDK Serverless backend triggers, payment webhooks, ride dispatch algorithms, and email notifications.
common/ Redux, Redux-Thunk, Firebase SDK Shared business logic, state reducers, actions, translation hooks, and global utilities used by all apps.
installer/ Node.js scripts, JSON DB Schemas One-click Firestore database seeding, CMS landing page deployers, language updates, and backup tools.

1.2 System Ride Flow Architecture

  1. Customer Request: Rider selects pickup & destination on customer-app. Fare is calculated using Google Maps Routes & Car Type rates.
  2. Cloud Dispatch: Firestore triggers Firebase Cloud Functions to search for nearby online drivers within the service radius.
  3. Driver Alert: Driver receives real-time loud audio dispatch on driver-app with countdown timer to accept or reject.
  4. Live Tracking: Both parties track live coordinates synchronized via Firestore real-time listeners and in-app chat.
  5. Trip Completion & Payment: Driver marks trip completed. Customer's card is charged via Stripe, or cash/wallet balance is updated. Admin commission is automatically logged.

2. System Requirements & Setup

Before installing or running any workspace, ensure your workstation meets the following prerequisites:

2.1 Required Tools

2.2 Step-by-Step CLI Setup

Step 1
Install Global CLI Dependencies

Open your command prompt / terminal with administrator privileges and run:

# Install Yarn globally
npm install -g yarn

# Install Firebase CLI globally
npm install -g firebase-tools

# Install Expo EAS CLI globally
npm install -g eas-cli
Step 2
Install Project Dependencies

From the root folder of the project repository, execute:

yarn install

This command resolves and links all workspace packages (customer-app, driver-app, web-app, functions, common) in a single step.

3. Firebase Setup & Services

Firebase provides the serverless backend, real-time database, cloud functions, authentication, and file storage for Caby.

⚠️ BLAZE PLAN (PAY-AS-YOU-GO) REQUIRED
You must upgrade your Firebase project to the Blaze Plan. Google Cloud Functions require billing enabled to make outbound network calls to Google Maps Platform and Stripe Payment APIs. (Firebase gives generous monthly free credits).

3.1 Create Firebase Project

  1. Go to Firebase Console and click Add Project.
  2. Name your project (e.g., caby-taxi-prod) and proceed. Enable Google Analytics if desired.
  3. In the bottom-left corner, click Upgrade and choose the Blaze Plan.

3.2 Register Applications in Firebase

From your Firebase Project Overview dashboard, register 1 Web App and 4 Mobile Apps:

3.3 Enable Authentication & Test Phone Numbers

  1. Go to Build > Authentication, click Get Started.
  2. In the Sign-in method tab, enable the following providers:
    • Phone: Required for mobile user and driver login.
    • Email/Password: Required for Admin, Dispatcher, and Web Portal logins.
    • Google & Apple: (Optional / Recommended for social signups).
  3. Setup Bypass Test Numbers: Under Sign-in method > Phone, expand Phone numbers for testing and add: 
    Phone: +1 2011234567 | Verification Code: 123456
Phone: +1 2021234567 | Verification Code: 123456
Phone: +1 2031234567 | Verification Code: 123456

    This allows you and app reviewers to test mobile logins freely without consuming SMS quotas.

3.4 Enable Firestore Database, Storage & Hosting

3.5 Generate Private Service Account Key

The backend installer and Cloud Functions require administrator access via a private key file:

  1. In Firebase Console, click the Gear icon (Project Settings) > Service Accounts tab.
  2. Click Generate New Private Key and download the JSON file.
  3. Rename the file to service-account.json and place it in the root of your project directory (or inside functions/ as configured).

4. Expo & EAS Cloud Build

Expo Application Services (EAS) handles cloud builds and stores cryptographic signing credentials for both iOS and Android apps.

4.1 Create & Link Expo Project

  1. Register an account on expo.dev.
  2. On your Expo dashboard, click Create a Project and name it caby.
  3. Both Customer and Driver apps share this same project. Copy the Owner, Slug, and Project ID (UUID).

4.2 Generate Firebase CI Token for EAS

To let EAS build servers download your project configs securely, generate a CI token:

# Run in terminal
firebase login:ci

Copy the output token. Then go to your project on expo.dev > Settings > Environment Variables / Secrets, and create a secret named FIREBASE_TOKEN with this token value.

5. Google Maps Platform Setup

Google Maps is critical for geocoding, autocomplete search, route polylines, real-time map rendering, and driver distance matrices.

5.1 Enable the 7 Required Google Maps APIs

Go to Google Cloud Console, select your Firebase project, and enable these 7 APIs in APIs & Services > Library:

  1. Maps SDK for Android (Renders Android map view)
  2. Maps SDK for iOS (Renders iOS map view)
  3. Maps JavaScript API (Renders Web Admin & Landing Page maps)
  4. Places API (New) (Search autocomplete and place details)
  5. Geocoding API (Coordinate to address conversion)
  6. Routes API / Directions API (Trip routing, turn-by-turn polyline, and distance)
  7. Distance Matrix API (Calculates distance from multiple drivers to pickup point)

5.2 Create & Restrict 6 API Keys

In APIs & Services > Credentials, create 6 separate API keys to protect against quota theft:

Key Name Used By Recommended Restriction
Web App Key Web Admin Portal HTTP referrers (e.g., https://yourdomain.com/*, http://localhost:3000/*)
Server Key Firebase Functions API restriction (Places, Geocoding, Routes, Distance Matrix)
Android Customer Key Customer App (Android) Android apps (Package com.yourcompany.caby + SHA-1 Fingerprint)
Android Driver Key Driver App (Android) Android apps (Package com.yourcompany.cabydriver + SHA-1 Fingerprint)
iOS Customer Key Customer App (iOS) iOS apps (Bundle ID com.yourcompany.caby)
iOS Driver Key Driver App (iOS) iOS apps (Bundle ID com.yourcompany.cabydriver)

6. Configuration Files (JSON)

All core settings are centralized inside functions/config/. Configure these files before deploying:

6.1 functions/config/common.json (Backend & Master Admin)

{
  "firebaseProjectId": "YOUR_FIREBASE_PROJECT_ID",
  "functionsRegion": "us-central1",
  "googleApplicationCredentials": "../service-account.json",
  "expo_owner": "YOUR_EXPO_USERNAME",
  "expo_slug": "YOUR_EXPO_PROJECT_SLUG",
  "expo_project_id": "YOUR_EXPO_PROJECT_UUID",
  "admin_email": "admin@yourdomain.com",
  "admin_password": "YOUR_ADMIN_PASSWORD",
  "demo_numbers": [
    "+12011234567",
    "+12021234567",
    "+12031234567",
    "+12041234567"
  ],
  "demo_otp": "123456"
}

6.2 functions/config/customer.json (Customer Mobile App)

{
  "app_name": "Caby",
  "app_description": "Caby customer app",
  "app_identifier": "com.yourcompany.caby",
  "ios_app_version": "1.0.0",
  "ios_build_number": "1",
  "android_app_version": "1.0.0",
  "android_version_code": 1,
  "googleApiKeys": {
    "ios": "YOUR_IOS_CUSTOMER_MAPS_KEY",
    "android": "YOUR_ANDROID_CUSTOMER_MAPS_KEY",
    "server": "YOUR_SERVER_MAPS_KEY"
  }
}

6.3 functions/config/driver.json (Driver Mobile App)

{
  "app_name": "Caby Driver",
  "app_description": "Caby driver app",
  "app_identifier": "com.yourcompany.cabydriver",
  "ios_app_identifier": "com.yourcompany.cabydriver",
  "ios_app_version": "1.0.0",
  "ios_build_number": "1",
  "android_app_version": "1.0.0",
  "android_version_code": 1,
  "googleApiKeys": {
    "ios": "YOUR_IOS_DRIVER_MAPS_KEY",
    "android": "YOUR_ANDROID_DRIVER_MAPS_KEY",
    "server": "YOUR_SERVER_MAPS_KEY"
  }
}

6.4 functions/config/web.json (Web Admin Dashboard)

{
  "app_name": "Caby Admin",
  "app_description": "Caby admin panel",
  "googleApiKeys": {
    "web": "YOUR_WEB_MAPS_KEY",
    "server": "YOUR_SERVER_MAPS_KEY"
  }
}

7. DB Seeding & Master Setup

After setting up your JSON configs and service-account.json, initialize your Firestore database with default master tables:

Command
Run Database Seeder
# Populate default collections and create Master Admin user
node installer/index.js initialize

This script seeds vehicle categories (Sedan, SUV, Bike, Mini), cancellation reasons, promo templates, language translations, and creates the default Administrator user using credentials from common.json.

7.1 First Time Admin Dashboard Setup

  1. Open the Web Portal at http://localhost:3000 or your live hosted domain.
  2. Login using your admin_email and admin_password.
  3. Navigate to Cars / Car Types: Configure base fares, per KM rates, waiting charges, and admin commission percentage.
  4. Navigate to Service Locations / Zones: Set up your operating cities and geo-fenced boundaries.
  5. Navigate to Driver Documents: Configure required driver onboarding documents (Driving License, National ID, Vehicle Registration).

8. Payments & Wallet System

Caby supports Stripe for direct credit/debit card processing, in-app customer wallets, and cash on delivery.

8.1 Stripe Gateway Configuration

  1. Log into your Stripe Dashboard at dashboard.stripe.com.
  2. Copy your Publishable Key (pk_live_...) and Secret Key (sk_live_...).
  3. In Caby Web Admin Dashboard, navigate to App Settings > Payment Settings.
  4. Enable Stripe, paste the Publishable Key & Secret Key, and save.
  5. Set your default Currency Code (e.g., USD, EUR, GBP, PKR) and currency symbol.

8.2 In-App Wallets & Driver Payouts

9. Full Customization Guide (Web, Customer, Driver)

This section provides a complete, organized reference for white-labeling and rebranding every element of the Caby platform (Logos, Color Palettes, Alert Sounds, Fonts, and Screen Pages) across the Web Portal, Customer Mobile App, and Driver Mobile App.

9.1 Quick Customization Reference Table

Component / Asset Target Workspace Exact File Path What It Controls
Web Header & Admin Logo web-app/ src/assets/logo_admin.png Top navigation bar brand logo in Admin and Public Portal.
Web Footer Logo & Favicon web-app/ src/assets/logo_footer.png & public/favicon.ico Browser tab icon and footer branding.
Web Theme & Colors web-app/ src/muiAppTheme.js Primary brand colors, buttons, card borders, and Material UI styles.
Web Landing & Public Pages web-app/ src/views/public/ & src/marketing/ Landing page hero banner, About, Services, FAQ, Contact, and Privacy pages.
Customer App Icons & Splash customer-app/ assets/images/logo_android.png, splash.png Rider mobile app launcher icon and startup loading splash graphic.
Customer App Theme Colors customer-app/ src/theme/colors.js Primary accent color, ride booking button gradients, card backgrounds.
Customer App Screens customer-app/ src/screens/MapScreen.js, BookedCabScreen.js Main booking map, search autocomplete, live trip tracking, and user profile.
Driver App Icons & Splash driver-app/ assets/images/logo_android.png, splash.png Driver mobile app launcher icon and launch splash screen.
Driver Dispatch Audio Ringtone driver-app/ assets/sounds/ride_alert.wav Loud dispatch ringtone played during incoming ride requests.
Driver App Theme Colors driver-app/ src/theme/colors.js Driver duty toggle switch, earnings card highlights, and header themes.
Driver App Screens driver-app/ src/screens/BookedCabScreen.js, DriverIncomeScreen.js Live trip navigation, daily earnings dashboard, and document uploads.

9.2 Web App Customization (Web Portal & Admin Panel)

The Web workspace includes both the public-facing landing portal and the protected Administrator/Dispatcher dashboards.

A. Logos & Graphical Assets

B. Colors, Themes & Typography

Edit web-app/src/muiAppTheme.js to adjust the Material UI styling palette:

// web-app/src/muiAppTheme.js
export const colors = {
    primary: "#ffcc33",       // Main taxi brand color
    primaryDark: "#e6b800",   // Darker shade for hover states
    secondary: "#24292e",     // Secondary accent color
    screenBackground: "#f4f6f9", // Dashboard background color
    cardBackground: "#ffffff",// Surface card color
    textPrimary: "#1f2937",   // Primary typography color
    headerBackground: "#111827"// Top navigation bar color
};

C. Public Landing & Informational Pages

All front-facing pages are located in web-app/src/views/public/ and can be edited directly to match your company's copy:

D. Admin Dashboard Views & Lists

9.3 Customer App (User App) Customization

The Customer App provides riders with intuitive ride booking, instant fare estimates, live driver tracking, and digital payments.

A. App Icons & Launch Splash Screen

B. Color Palette & UI Tokens

Edit customer-app/src/theme/colors.js to update the color palette across all rider screens:

// customer-app/src/theme/colors.js
export const colors = {
    PRIMARY: "#ffcc33",        // Main theme color (Buttons, highlights, badges)
    PRIMARY_DARK: "#e6b800",   // Pressed state color
    SECONDARY: "#1e293b",      // Dark accent color
    BACKGROUND: "#ffffff",     // Screen background color
    CARD_BG: "#f8fafc",        // Vehicle card background
    TEXT_MAIN: "#0f172a",      // Main heading typography
    TEXT_MUTED: "#64748b",     // Subtitles and hints
    SUCCESS: "#10b981",        // Completed / Confirmed status green
    DANGER: "#ef4444"          // Cancelled / Alert status red
};

C. Key Customer Screens

9.4 Driver App Customization

The Driver App is designed for high performance with loud audio dispatches, background location broadcasting, and daily revenue statistics.

A. App Icons & Launch Splash

B. Dispatch Ringtones & Audio Alerts

When a customer requests a ride nearby, the Driver App rings loudly to notify the driver even if the app is in the background:

C. Driver Colors & Theme

Edit driver-app/src/theme/colors.js to adjust driver UI elements:

// driver-app/src/theme/colors.js
export const colors = {
    PRIMARY: "#ffcc33",        // Driver theme accent
    PRIMARY_DARK: "#e6b800",   // Darker accent
    ONLINE_GREEN: "#22c55e",   // "Online / On Duty" active switch green
    OFFLINE_RED: "#ef4444",    // "Offline" inactive switch red
    BACKGROUND: "#ffffff",     // Screen background
    CARD_BG: "#f8fafc",        // Duty card background
    TEXT_MAIN: "#0f172a"       // Text color
};

D. Key Driver Screens

10. Web Admin & CMS Portal

The Web workspace contains the full Admin Console, Dispatcher interface, and public marketing landing pages.

10.1 Local Development

# Start Vite development server
yarn web

10.2 Deploying to Firebase Hosting

# Build and deploy Web Hosting only
yarn web:deploy

# Deploy complete backend (Cloud Functions, Firestore Rules, Storage, and Hosting)
yarn deploy

10.3 CMS Landing Page Customization

Landing page text, hero banners, app download badges, and footer links can be customized in web-app/src/marketing/ or deployed via node installer/deployCmsLanding.js.

11. Customer Mobile App

The Customer App allows riders to book rides, schedule trips, track drivers, and pay securely.

11.1 Running Locally

# Start Metro Dev Server for Customer App
yarn app:customer

11.2 Customizing Branding & Theme

12. Driver Mobile App

The Driver App provides turn-by-turn navigation, background location broadcasting, dispatch alerts, and earnings analytics.

12.1 Running Locally

# Start Metro Dev Server for Driver App
yarn app:driver

12.2 Customizing Alerts & Ringtones

13. Production Build & Release

Generate standalone installable binaries and store-ready releases using Expo EAS CLI directly from the root directory:

13.1 Android Builds

# 1. Build Standalone Installable APK (for testing & distribution)
yarn app:build-android-apk          # Customer App APK
yarn app:driver:build-android-apk   # Driver App APK

# 2. Build Production AAB (for Google Play Console submission)
yarn app:build-android              # Customer App AAB
yarn app:driver:build-android       # Driver App AAB

13.2 iOS Builds

# 1. Build iOS Simulator / Dev Client
yarn app:build-dev-client           # Customer App Dev Client
yarn app:driver:build-dev-client    # Driver App Dev Client

# 2. Build Production iOS IPA (for Apple TestFlight / App Store Connect)
yarn app:build-ios                  # Customer App IPA
yarn app:driver:build-ios           # Driver App IPA

13.3 Automated Store Submission

yarn app:submit                     # Submit Customer App to Stores
yarn app:driver:submit              # Submit Driver App to Stores

14. Troubleshooting & FAQ

❓ Q1: Google Maps shows blank screen or "REQUEST_DENIED" error

Solution: Ensure your Google Cloud Project has Billing enabled. Verify that all 7 required APIs (especially Places API (New), Geocoding API, and Routes API) are enabled. Check that your API key restrictions match your domain name or Android package name and SHA-1 fingerprint.

❓ Q2: Phone SMS OTP is not being received on mobile

Solution: For initial testing, add test phone numbers (e.g. +1 2011234567 with code 123456) in Firebase Console under Authentication > Sign-in method > Phone > Phone numbers for testing. For production SMS, ensure Firebase Blaze plan has sufficient SMS quotas.

❓ Q3: Firebase Cloud Functions deployment timeout

Solution: We have pre-configured cross-env FUNCTIONS_DISCOVERY_TIMEOUT=120 in root package.json. If your internet connection is slow, run yarn deploy:functions directly.

❓ Q4: How do I change the default currency and language?

Solution: Login to the Web Admin Portal, go to App Settings > Global Settings to set your currency symbol, code, and default language. You can also run node installer/index.js override-language to batch update language packs.

15. Help, Support & Changelog

Need customization, branding services, or help with installation? Contact our dedicated support engineering team:

Changelog

Version 1.0.0 (Initial Release)