HandyHive Documentation

Key Features

What's Included

The HandyHive monorepo bundles every piece you need to launch an on-demand home-services platform:

• Customer App — Flutter mobile app (Android & iOS) where end users browse and book services (folder: handyhive_customer/).
• Partner App — Flutter mobile app for service providers / business owners to manage their team, services and earnings (folder: handyhive_partner/).
• Worker App — Flutter mobile app for field workers / handymen to accept jobs, track location and chat with customers (folder: handyhive_worker/).
• Admin Panel — Flutter web dashboard for the platform owner. Modules include Dashboard, Users, Providers, Workers, Order History, Order Detail, Services, Categories, Subcategories, Coupons, Subscription Plans & History, Payout Requests, Verify Documents, Support Tickets, Banners, Reviews, Zones, Currencies, Tax, Languages, Payment Gateways, Onboarding Slides, Landing Page, Status, Privacy / Terms / About settings & more (folder: admin_panel/).
• Landing Page — Static HTML / CSS / JS marketing site that reads its content from Firestore in realtime, fully editable from the admin (folder: landing_page/).
• Cloud Functions — Firebase Functions for FCM push, auto-cancel of unaccepted bookings, automatic refund-to-wallet on cancellation, scheduled tasks and more (folder: function/).
• Firestore Data — Pre-built collections (firestore.indexes.json) and security rules (firestore.rules) for a one-click setup.
• Documentation — This guide, inside documentation/.

Before starting the setup, make sure you have the following tools and accounts ready.

Required Software

Required Accounts

• Google Account - For Firebase Console & Google Cloud
• Firebase Account - Project hosting, database, authentication, and functions
• Google Cloud Console - For Google Maps API keys
• Apple Developer Account (optional) - Required for iOS deployment & Apple Sign-In
• Google Play Console (optional) - For publishing to Google Play Store

Follow these steps in order for a smooth setup experience. Each step links to the detailed section below.

To set up Flutter on both Windows and macOS, follow these step-by-step instructions.

Setting Up Flutter on Windows

System Requirements

• Operating System: Windows 10 or later (64-bit)
• Disk Space: At least 2.8 GB (excluding IDE and tools)
• Required Tool: Git for Windows

Download Flutter SDK

• Visit the official Flutter installation page.
• Download the latest stable version of the Flutter SDK (ZIP file).
• Extract the ZIP and move the flutter folder to a preferred location, e.g., C:\src\flutter.

Add Flutter to System Path

• Open the Start Menu, search for "Environment Variables", and click "Edit the system environment variables".
• In the System Properties window, click Environment Variables.
• Under User variables, locate the Path variable.
• If it exists, click Edit and append the path to flutter\bin (e.g., C:\src\flutter\bin) at the end, separated by a semicolon.
• If it doesn't exist, click New, name it Path, and enter the path to flutter\bin.

Verify Installation

• Open Command Prompt and run:

flutter doctor

• This will analyze your environment and report any missing dependencies (like Android Studio or toolchains).

Install Android Studio

• Download Android Studio from developer.android.com.
• Launch the installer and complete the setup wizard, which installs:
• Android SDK
• Android SDK Command-line Tools
• Android SDK Build-Tools
• After installation, go to Android Studio > Settings > Plugins and install both Flutter and Dart plugins.

Set Up an Android Emulator

• Open Android Studio.
• Go to Tools > AVD Manager.
• Follow the prompts to create and configure a new Android Virtual Device (AVD).

Final Setup Check

• Run the following again to ensure everything is configured:

flutter doctor

• Resolve any remaining issues shown in the output.

Setting Up Flutter on macOS

System Requirements

• Operating System: macOS 10.15 (Catalina) or later
• Disk Space: At least 2.8 GB (excluding IDE and tools)
• Required Tools: Git, Xcode (for iOS development)

Download Flutter SDK

• Visit the official Flutter installation page for macOS.
• Download and extract the Flutter SDK to a preferred location, e.g., ~/development/flutter.

Add Flutter to PATH

• Open your shell profile file (.zshrc or .bashrc) and add:

export PATH="$PATH:$HOME/development/flutter/bin"

• Then run source ~/.zshrc (or restart your terminal) to apply the changes.

Install Xcode

• Install Xcode from the Mac App Store.
• After installation, run the following commands to configure Xcode CLI tools:

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -runFirstLaunch

Install CocoaPods

• CocoaPods is required for iOS dependency management:

sudo gem install cocoapods

Verify Installation

flutter doctor

• Resolve any issues reported by Flutter Doctor before proceeding.

HandyHive supports three authentication methods. Enable each one in the Firebase Console.

1. Enable Phone Authentication

• Go to the Firebase Console.
• Select your project from the dashboard.
• In the left sidebar, click on "Authentication".
• Navigate to the "Sign-in method" tab.
• Locate "Phone" and click on the edit icon.
• Toggle the switch to Enable phone authentication.
• Click Save.

2. Enable Google Sign-In

• Open the Firebase Console and choose your Firebase project.
• Go to the Authentication section from the sidebar.
• Under the "Sign-in method" tab, find "Google" and click the edit icon.
• Toggle the Enable switch.
• If prompted, configure the OAuth consent screen by providing:
• App name
• Support email
• Developer contact details
• Save your changes.

3. Enable Apple Sign-In

• Visit the Firebase Console and select your project.
• Go to Authentication > Sign-in method.
• Scroll to Apple and click the edit icon.
• Enable the provider and provide the required Apple Developer credentials:
• Team ID (from your Apple Developer account)
• Service ID
• Key ID
• Private Key (.p8 file)
• Save your configuration.

Import the pre-built database collections to quickly populate your Firestore database with the required structure.

1. Install Node.js and npm

• Visit the official Node.js website: https://nodejs.org
• Download and install the LTS version compatible with your operating system.
• After installation, verify the setup using:

node -v
npm -v

2. Extract Database Files

• Locate your database.zip file from the project package.
• Extract its contents to a folder on your computer using your OS's built-in zip utility, WinRAR, or 7-Zip.

3. Open Terminal or Command Prompt

• Navigate into the extracted folder using your terminal:

cd path/to/extracted/folder

4. Generate Firebase Service Account Key

• Go to the Firebase Console.
• Select your project. Click the gear icon (⚙) next to "Project Overview" in the top-left sidebar.
• Select "Project settings" from the dropdown menu.
• In the Project Settings page, click the "Service accounts" tab at the top (next to General, Cloud Messaging, Integrations, etc.).
• You will see the Firebase Admin SDK section. Make sure "Node.js" is selected as the platform (it should be selected by default).
• Click the Generate new private key button at the bottom of the page.
• A confirmation dialog will appear. Click "Generate key".
• A JSON key file will be downloaded automatically to your computer.
• Replace the existing config.json in your project folder with this newly downloaded file (rename it to config.json if needed).

5. Prepare config.json

• If config.json is not pre-existing:
• In Firebase Console, go to Project Settings > General.
• Scroll down to Your Apps > Firebase SDK snippet > Config.
• Copy the config object (not the script tag).
• Create a file named config.json in your project folder and paste the config content inside.

6. Run Import Command

• Inside the extracted database folder, run:

npm install firestore-export-import

node import

1. Navigate to Your Firebase Project Folder

• Open your terminal or command prompt.
• Use the cd command to move into your Firestore index project folder:

cd path/to/firestore_index

• Replace path/to/firestore_index with the actual directory path where your Firestore project files are located.

Step A: Run firebase init

• Inside your project directory, initialize Firebase:

firebase init

• The terminal will display the Firebase ASCII logo and the message:

You're about to initialize a Firebase project in this directory:
  C:\path\to\your\firestore_index

? Are you ready to proceed? (Y/n)

• Type y and press Enter to proceed.

Step B: Select Firebase Features

• You will see a list of Firebase features. Use the arrow keys to navigate and press Space to select:

(*) Firestore: Configure security rules and indexes files for Firestore

Step C: Choose Firebase Project

• Select Use an existing project when prompted.
• A list of your Firebase projects will appear. Use the arrow keys to highlight your HandyHive project and press Enter.

Step D: Set Up Firestore Rules and Indexes

• When prompted for the Firestore rules file (firestore.rules), press Enter to accept the default.
• If the file already exists, type y to overwrite.
• When prompted for the Firestore indexes file (firestore.indexes.json), press Enter to accept the default. Overwrite if asked.
• You will see the message: Firebase initialization complete!

Step E: Deploy Firestore Indexes

• Now deploy the indexes defined in firestore.indexes.json:

firebase deploy --only firestore:indexes

Deployment Complete

• You should see the following output in your terminal:

=== Deploying to 'your-project-id'...

i  firestore: reading indexes from firestore.indexes.json...
i  cloud.firestore: checking firestore.rules for compilation errors...
+  cloud.firestore: rules file firestore.rules compiled successfully
i  firestore: deploying indexes...
+  firestore: deployed indexes in firestore.indexes.json successfully

+  Deploy complete!

Project Console: https://console.firebase.google.com/project/your-project-id/overview

1. Install Firebase CLI Tools

• Ensure the Firebase CLI is installed globally:

npm install -g firebase-tools

• Verify the installation by checking the version:

firebase --version

2. Firebase Project Setup

Log in to Firebase:

• Authenticate your CLI session:

firebase login

Initialize Firebase (if not already initialized):

• Navigate to your project root and initialize Firebase:

firebase init

During this process, follow these prompts:

? Are you ready to proceed? Yes
? Which Firebase features do you want to set up?
  (*) Functions: Configure a Cloud Functions directory and its files

=== Project Setup
? Please select an option: Use an existing project
? Select a default Firebase project: your-project-id

=== Functions Setup
? What language would you like to use? JavaScript
? Do you want to use ESLint? No
? Do you want to install dependencies with npm now? Yes

• Wait for npm to install all dependencies. You should see:

+  Wrote functions/package.json
+  Wrote functions/index.js
+  Wrote functions/.gitignore
+  Wrote configuration info to firebase.json
+  Wrote project information to .firebaserc

+  Firebase initialization complete!

3. Install Function Dependencies

• Navigate to the functions/ directory and install all required Node.js packages:

cd functions
npm install

4. Deploy Your Functions

• Once everything is set up, deploy your functions to Firebase:

firebase deploy --only functions

• You should see the following output:

=== Deploying to 'your-project-id'...

i  deploying functions
i  functions: preparing codebase default for deployment...
i  functions: ensuring required API cloudfunctions.googleapis.com is enabled...
+  functions: required API cloudfunctions.googleapis.com is enabled
i  functions: Loading and analyzing source code...

+  Deploy complete!

Project Console: https://console.firebase.google.com/project/your-project-id/overview

• This deploys only the cloud functions without affecting other Firebase services.

Here you will find all the setup guides for Admin Panel configuration.

Update HTML Title

• Open: web/index.html
• Inside the <head> section, update the content of the <title> tag:

<head>
  ...
  <title>Your New App Name</title>
  ...
</head>

1. Install Firebase CLI Tools

npm install -g firebase-tools

2. Authenticate Firebase CLI

firebase login

• A browser window will open to complete authentication with your Google account.

3. Create a Firebase Project

• Create a project directly from the terminal:

firebase projects:create

OR

• Create one via the Firebase Console.
• Enter a name and press Continue, then click Create Project.
• Now add an app in Firebase:

$ dart pub global activate flutterfire_cli

$ flutterfire configure --project=YOUR_PROJECT_ID

4. Initialize Firebase in Your Flutter App

• Open Android Studio and go to the Terminal tab.
• Run the initialization commands:

dart pub global activate flutterfire_cli

flutterfire configure --project=YOUR_PROJECT_ID

• The CLI will ask which platforms you want to configure. Since this is the Admin Panel:

? Which platforms should your configuration support?
  ( ) android
  ( ) ios
  ( ) macos
  (*) web        <-- Select ONLY this
  ( ) windows

• When asked "firebase_options.dart already exists. Do you want to override it?", type yes and press Enter.
• Setup is complete when you see: Firebase configuration file lib/firebase_options.dart generated successfully.

1. Generate a Google Maps API Key

• Go to the Google Cloud Console.
• Create a new project or select an existing one.
• Enable the following APIs for your project:
• Maps SDK for Android
• Maps SDK for iOS
• Maps JavaScript API
• Go to APIs & Services > Credentials.
• Click "Create Credentials" > "API key".
• Copy the newly generated API key.

2. Add API Key to Flutter Web

• Open: web/index.html
• Inside the <head> section, add:

<script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places"></script>

Flutter Web

For Flutter web, the favicon represents your application in the browser tab.

Replace Favicon:

• Design your favicon in the proper size and format (typically favicon.ico or PNG, 32x32 or 16x16 pixels).
• Go to your Flutter project's web/ directory.
• Replace the existing favicon.png or favicon.ico with your own file using the same filename to maintain the reference.

CORS (Cross-Origin Resource Sharing) must be configured on your Firebase Storage bucket to allow the web panel to load images and files.

1. Open the Google Cloud Console

• Go to Google Cloud Console.

2. Select Your Project

• At the top-left of the Google Cloud Console, you will see your project name. Click on it to ensure you are working in the correct project.

3. Activate Google Cloud Shell

• In the top-right corner of the Google Cloud Console, look for the Activate Cloud Shell icon (it looks like a terminal/command prompt icon: □>_).
• Click it. A Cloud Shell terminal window will open at the bottom of the screen.
• Wait for the terminal to initialize. You will see a message like:

Welcome to Cloud Shell! Type "help" to get started.
Your Cloud Platform project in this session is set to your-project-id.
Use 'gcloud config set project [PROJECT_ID]' to change to a different project.

4. Create a CORS Configuration File

• In the Cloud Shell terminal, run the following command:

echo '[{ "origin": ["*"], "method": ["GET"], "maxAgeSeconds": 3600, "responseHeader": ["Content-Type"] }]' > cors-config.json

• Press Enter. This creates a file called cors-config.json in the Cloud Shell environment.

5. Get Your Storage Bucket Name

• To find your bucket name: Go to Firebase Console → Storage (in the left sidebar).
• At the top of the Storage page, you will see your bucket URL (e.g., gs://your-project-id.appspot.com). Copy the bucket name part.

6. Apply the CORS Configuration to Your Bucket

• Back in the Google Cloud Shell, run:

gsutil cors set cors-config.json gs://YOUR_BUCKET_NAME

• Replace YOUR_BUCKET_NAME with your actual bucket name (e.g., handyhive-3d7fa.appspot.com).
• Press Enter to apply the CORS configuration.

1. Create the Build for Server Upload

• Run the following commands in order:

flutter clean

flutter pub get

flutter build web --release

• You will see output like:

Compiling lib/main.dart for the Web...
✓ Built build\web                                          19.5s

• After running the above commands, Flutter generates the optimized build inside:

build/web/

• Upload the contents of the build/web/ folder to your server or hosting provider (via FTP, cPanel, or SSH).

1. Build and Deploy Using Firebase Hosting

• Install Firebase CLI (if not already installed):

npm install -g firebase-tools

• Login to Firebase:

firebase login

• Initialize Firebase inside your project folder:

firebase init

? Are you ready to proceed? (Y/n) y

? Which Firebase features do you want to set up?
  (*) Hosting: Configure files for Firebase Hosting
      and (optionally) set up GitHub Action deploys

=== Project Setup
? Please select an option: Use an existing project
i  Using project your-project-id

=== Hosting Setup
? What do you want to use as your public directory? build/web
? Configure as a single-page app (rewrite all urls to /index.html)? Yes
? Set up automatic builds and deploys with GitHub? No

• You should see: + Firebase initialization complete!

• Now build the release version:

flutter build web --release

• Then deploy to Firebase Hosting:

firebase deploy

=== Deploying to 'handyhive-3d7fa'...

i  deploying firestore, hosting
i  hosting[handyhive-3d7fa]: beginning deploy...
i  hosting[handyhive-3d7fa]: found 516 files in build/web
+  hosting[handyhive-3d7fa]: file upload complete
+  hosting[handyhive-3d7fa]: version finalized
+  hosting[handyhive-3d7fa]: release complete

+  Deploy complete!

Project Console: https://console.firebase.google.com/project/handyhive-3d7fa/overview
Hosting URL: https://handyhive-3d7fa.web.app

The same setup steps below apply to all three Flutter mobile apps — Customer (handyhive_customer/), Partner (handyhive_partner/) and Worker (handyhive_worker/) — for both Android and iOS.

Changing the package name of a Flutter project involves updating multiple files and configurations for both Android and iOS platforms.

Android

Update the applicationId in build.gradle:

• Open: android/app/build.gradle
• Inside the defaultConfig block, find and replace the applicationId:

defaultConfig {
    applicationId "com.new.package.name"
}

Rename Java Package Directories:

• Go to: android/app/src/main/java/
• Rename the directory folders to match your new package structure (e.g., com/new/package/name).
• Make sure the new folder path matches the applicationId you set above.

Update AndroidManifest.xml:

• Open: android/app/src/main/AndroidManifest.xml
• Update the package attribute in the root <manifest> tag:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.new.package.name">
</manifest>

Update Other Manifest Files:

• Also update the package attribute in:
• android/app/src/debug/AndroidManifest.xml
• android/app/src/profile/AndroidManifest.xml

iOS

Update PRODUCT_BUNDLE_IDENTIFIER in Xcode:

• Open the iOS project in Xcode: ios/Runner.xcworkspace
• Select the Runner target, then go to the Build Settings tab.
• Search for PRODUCT_BUNDLE_IDENTIFIER.
• Replace it with your new bundle identifier (e.g., com.new.package.name).

Update Bundle Identifier in Info.plist:

• Open: ios/Runner/Info.plist
• Locate the CFBundleIdentifier key and update its value.

Prerequisites

• Flutter SDK is installed
• A Flutter project is already created
• You understand the basic Flutter project structure

Android

Update AndroidManifest.xml:

• Navigate to: android/app/src/main/AndroidManifest.xml
• Find the application tag and modify the android:label attribute:

<application
    android:name="${applicationName}"
    android:icon="@mipmap/ic_launcher"
    android:label="Your App Name"
    ...>
</application>

Update strings.xml:

• Open: android/app/src/main/res/values/strings.xml
• Update the app_name string:

<string name="app_name">Your New App Name</string>

iOS

Update Info.plist:

• Go to: ios/Runner/Info.plist
• Locate the key for CFBundleName and change its value:

<key>CFBundleName</key>
<string>Your New App Name</string>

Update Display Name in Xcode:

• Open your project in Xcode: ios/Runner.xcworkspace
• Select the Runner target, click the General tab.
• Find the Display Name field and update it to your desired app name.

Android

Replace Default Icons:

• Create your custom app icons in various densities. Navigate to: android/app/src/main/res/
• Replace ic_launcher.png in each of these folders with your custom icon:
• mipmap-mdpi (48x48 px)
• mipmap-hdpi (72x72 px)
• mipmap-xhdpi (96x96 px)
• mipmap-xxhdpi (144x144 px)
• mipmap-xxxhdpi (192x192 px)

Update Icon Reference in AndroidManifest.xml:

• Open: android/app/src/main/AndroidManifest.xml
• Ensure the android:icon points to your custom icon:

<application
    android:icon="@mipmap/ic_launcher"
    ...>
</application>

iOS

Replace AppIcon Set:

• Prepare your custom icons in iOS-specific sizes and formats.
• Replace the contents of: ios/Runner/Assets.xcassets/AppIcon.appiconset/
• Ensure your icon set follows Apple's size and naming requirements.

1. Install Firebase CLI Tools

npm install -g firebase-tools

2. Authenticate Firebase CLI

firebase login

• A browser window will open to complete authentication with your Google account.

3. Create a Firebase Project

firebase projects:create

OR

• Create one via the Firebase Console.
• Enter a name and press Continue, then click Create Project.
• Add your app in Firebase:

$ dart pub global activate flutterfire_cli
$ flutterfire configure --project=YOUR_PROJECT_ID

4. Initialize Firebase in Your Flutter App

• Open Android Studio and go to the Terminal tab. Run:

dart pub global activate flutterfire_cli

flutterfire configure --project=YOUR_PROJECT_ID

• The CLI will ask which platforms to configure. Pick the platforms appropriate for the project you are inside:

? Which platforms should your configuration support?
  (*) android      <-- Customer / Partner / Worker apps
  (*) ios          <-- Customer / Partner / Worker apps
  ( ) macos
  (*) web          <-- Admin Panel only
  ( ) windows

• If prompted "firebase_options.dart already exists. Do you want to override it?", type yes.
• Setup is complete when you see:

Firebase configuration file lib/firebase_options.dart generated successfully
with the following Firebase apps:

Platform  Firebase App Id
android   1:XXXXXXXXX:android:XXXXXXXXX
ios       1:XXXXXXXXX:ios:XXXXXXXXX

1. Create a Firebase Project

• Go to the Firebase Console.
• Click "Add project" and follow the guided steps.
• After setup, you'll be redirected to the Firebase project dashboard.

2. Add Your Flutter App to Firebase

Android Setup:

• Click on the Android icon to register an Android app.
• Enter your Android package name (found in android/app/src/main/AndroidManifest.xml).
• Download the google-services.json file.
• Place it in: android/app/

iOS Setup:

• Click on the iOS icon to register your iOS app.
• Enter your iOS bundle ID (found in Xcode project settings).
• Download the GoogleService-Info.plist file.
• In Xcode:
• Open ios/Runner.xcworkspace.
• Drag and drop GoogleService-Info.plist into the Runner project (check "Copy items if needed").

3. Add Firebase Packages

• Add the necessary Firebase packages to pubspec.yaml:

dependencies:
  firebase_core: ^latest
  firebase_auth: ^latest
  cloud_firestore: ^latest

flutter pub get

4. Configure DefaultFirebaseOptions

• Use the FlutterFire CLI to auto-generate the configuration file:

flutterfire configure

• This creates lib/firebase_options.dart with platform-specific configurations.

5. Initialize Firebase in main.dart

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp(
    options: DefaultFirebaseOptions.currentPlatform,
  );
  runApp(MyApp());
}

1. Generate a Google Maps API Key

• Go to the Google Cloud Console.
• Create a new project or select an existing one.
• Enable the following APIs:
• Maps SDK for Android
• Maps SDK for iOS
• Maps JavaScript API
• Places API
• Geocoding API
• Directions API
• Go to APIs & Services > Credentials.
• Click "Create Credentials" > "API key".
• Copy the generated API key.

2. Add API Key - Android

• Open: android/app/src/main/AndroidManifest.xml
• Inside the <application> tag, add:

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

3. Add API Key - iOS

• Open: ios/Runner/AppDelegate.swift
• In the application(_:didFinishLaunchingWithOptions:) method, add:

import GoogleMaps
GMSServices.provideAPIKey("YOUR_API_KEY")

SHA keys are required for Firebase services like Google Sign-In and Phone Authentication on Android.

1. Generate SHA Keys

For Windows (Debug Keystore):

keytool -list -v -keystore "%USERPROFILE%\.android\debug.keystore" -alias androiddebugkey -storepass android -keypass android

For macOS/Linux (Debug Keystore):

keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android

• Look for the SHA1 and SHA256 values in the output and copy them.

2. Add SHA Keys to Firebase Console

• Open the Firebase Console and select your project.
• Click the gear icon (⚙) next to "Project Overview" and select "Project settings".
• Go to the "General" tab (first tab at the top).
• Scroll down to the "Your apps" section. Find your Android app.
• Under your Android app, you will see a section listing existing SHA certificate fingerprints (SHA-1 and SHA-256).
• Click the "Add Fingerprint" button.
• A dialog will appear with a "Certificate fingerprint" input field and toggle buttons for SHA1 and SHA256.
• Paste your SHA-1 key, select SHA1, and click Save.
• Repeat for the SHA-256 key: click "Add Fingerprint" again, paste the SHA-256 key, select SHA256, and click Save.

1. Generate APK (for direct installation)

flutter clean

flutter pub get

flutter build apk --release

• The release APK will be generated at:

build/app/outputs/flutter-apk/app-release.apk

2. Generate AAB (for Google Play Store)

flutter clean

flutter pub get

flutter build appbundle --release

• The release AAB file will be generated at:

build/app/outputs/bundle/release/app-release.aab

Using Command-Line Interface (CLI)

Open Terminal and navigate to your project:

cd path/to/your_flutter_project

Run the Flutter App:

flutter run

• This builds and runs your app on a connected device or emulator.

Using Android Studio

• Launch Android Studio and open your Flutter project.
• Click the green Run button in the toolbar.
• Choose your emulator or physical device from the device dropdown.
• Android Studio will build and launch your app automatically.

Using Visual Studio Code

• Launch VS Code and use File > Open Folder to open your Flutter project.
• Press Ctrl + Shift + P (or Cmd + Shift + P on macOS) to open the Command Palette.
• Search for and select Flutter: Run.
• Choose your emulator or connected device from the list.

1. Get the FCM Sender ID

• Open the Firebase Console.
• Click the gear icon (⚙) next to "Project Overview" → "Project settings".
• Click the "Cloud Messaging" tab at the top.
• Under "Firebase Cloud Messaging API (V1)" (should show Enabled), you will see a "Sender ID" field.
• Copy the Sender ID value (a numeric string). This single value goes into the FCM Server Key field in the Admin Panel — the apps read it from Firestore as both notification_server_key and senderId.

2. Get the Web Client ID (for Google Sign-In)

• In the Firebase Console left sidebar, go to Authentication.
• Click the "Sign-in method" tab.
• Find "Google" in the providers list and click the edit (pencil) icon.
• In the Google provider settings, expand the "Web SDK configuration" section. You will see two fields:
• Web client ID — copy this value
• Web client secret — not needed
• This Web client ID goes into the Google Client ID field in the Admin Panel and is read by the mobile apps from Firestore as googleClientId.

3. Get the Firebase Service Account JSON File

• Go to Project Settings (gear icon) → "Service accounts" tab.
• You will see the Firebase Admin SDK section with a code snippet.
• Click the Generate new private key button at the bottom.
• A JSON file will be downloaded automatically. Keep this file safe — you will upload it to the Admin Panel, which stores it in Firebase Storage and saves the download URL on the settings doc as jsonFileURL.

4. Add All Keys in the Admin Panel

• Open your Admin Panel (the deployed web app).
• In the left sidebar, expand Settings and click "Notification Settings".
• Fill the three fields below and click Save.

• All three values are written to the single Firestore document settings/constant, so the customer / partner / worker apps need only one read at startup to pick up every notification + login setting.

HandyHive ships with a standalone public marketing site that lives in the landing_page/ folder at the repo root (sibling of admin_panel/). Every piece of copy and imagery is editable from the admin panel under Content → Landing Page and is rendered from Firestore at runtime — no redeploy needed when content changes.

Folder Structure

HandyHive/
  admin_panel/                 Flutter web admin (the "Landing Page" editor lives here)
  landing_page/                Plain HTML/CSS/JS marketing site (this section)
    index.html                 Markup skeleton with data-bind attributes
    styles.css                 Theme tokens (purple #AD5CFF) + responsive layout
    config.js                  Firebase Web config (edit this for your project)
    app.js                     Listens to settings/landing_page and renders the page
    README.md                  Quick start notes

1. Update Firebase Credentials

• Open landing_page/config.js in your editor.
• Replace the window.HH_FIREBASE_CONFIG values with your own project's Web SDK credentials (same project that the admin panel and mobile apps use):

// landing_page/config.js
window.HH_FIREBASE_CONFIG = {
  apiKey: "YOUR_API_KEY",
  authDomain: "YOUR_AUTH_DOMAIN",
  projectId: "YOUR_PROJECT_ID",
  storageBucket: "YOUR_STORAGE_BUCKET",
  messagingSenderId: "YOUR_MESSAGING_SENDER_ID",
  appId: "YOUR_APP_ID",
  measurementId: "YOUR_MEASUREMENT_ID",
};

• Save the file. That's the only file you need to change — everything else is loaded dynamically from Firestore.
• Note: The page uses the Firebase compat SDK via plain <script> tags. This is intentional so it works when served over plain HTTP and does not need a build step.
• Firebase web API keys are not secret — they identify the project, not the user. Real access control is enforced by Firestore security rules.

2. Get Firebase Credentials

• Go to the Firebase Console.
• Select your project → click the gear icon (⚙) next to "Project Overview".
• Select "Project settings" → "General" tab → scroll to "Your apps".
• Under Web apps, copy the firebaseConfig object.
• Paste the values into landing_page/config.js and save.

3. Firestore Security Rule

The landing page reads settings/landing_page without authentication, so that document needs to be publicly readable. Add this rule to your firestore.rules (write access stays admin-only):

match /databases/{database}/documents {
  match /settings/landing_page {
    allow read: if true;                       // public can read
    allow write: if request.auth != null;      // only authenticated admins write
  }
}

4. Edit Content from Admin Panel

Sign in to the admin panel and navigate to Content → Landing Page. The editor is split into nine sections:

• Brand — brand name, tagline, site title (browser tab), logo (image upload), favicon (image upload).
• Hero — headline, subheadline, primary CTA label + URL, secondary CTA label + URL, hero background image (image upload — gradient illustration is used if empty).
• Features — repeatable list. Each row picks an icon from the built-in set (bolt, shield, price, clock, star, heart, check, home, phone, chat, tool) plus title and description.
• How it works — repeatable numbered steps with step number, title and description.
• Stats — repeatable KPI strip (up to 4 looks best). Each item has a value (e.g. 50k+) and a label.
• Testimonials — repeatable. Each row has name, role, quote and an optional avatar image (initials are shown when no avatar is uploaded).
• App download — section title, subtitle, Play Store URL, App Store URL, optional preview image (replaces the built-in phone mock-up).
• FAQ — repeatable Q&A pairs rendered as an accordion.
• Footer — tagline, copyright, social URLs (Twitter / X, Facebook, Instagram, LinkedIn). Empty social URLs are hidden.

Click Save. Because the landing page subscribes to Firestore with onSnapshot, any open browser tab updates live — visitors do not even need to reload.

5. Image Uploads

The Logo, Favicon, Hero background, App preview, and Testimonial avatars are all real image pickers. Picking a file uploads it to Firebase Storage and stores the resulting download URL on the Firestore document. Files land in these folders:

• landing/logo/
• landing/favicon/
• landing/hero/
• landing/app-preview/
• landing/testimonials/

Make sure your storage.rules allows authenticated admins to write to these paths.

6. Running Locally

The landing_page/ folder is a plain static site — no build step.

1. Double-click index.html — the browser opens via file://. The page renders with its built-in default copy if the browser blocks file:// network requests.
2. Serve it over HTTP (recommended — required for Firebase to load):

   cd landing_page
   python3 -m http.server 8080
   # or
   npx serve .

   Then open http://localhost:8080/.

Open DevTools → Console. Any errors from the Firestore listener appear tagged [LandingPage] — use them to debug missing fields or permission denied errors.

7. Deploying to Production

Deploy the folder to any static host:

Option A — Firebase Hosting (recommended)

npm install -g firebase-tools
cd landing_page
firebase login
firebase init hosting
# - Use an existing project → your HandyHive Firebase project
# - Public directory: .  (this current folder)
# - Configure as SPA? → No
# - Set up automatic builds? → No
# - Overwrite index.html? → No

firebase deploy --only hosting

You'll receive a live URL like https://your-project.web.app.

Option B — Any other static host

Upload the whole landing_page/ folder to Netlify, Vercel, GitHub Pages, AWS S3 + CloudFront, or your own server. No build step required.

8. Troubleshooting

Page shows the default copy instead of my admin-panel content

• Confirm landing_page/config.js contains your own Firebase project values (not the placeholders).
• Open the admin panel → Content → Landing Page, fill in any field and click Save at least once so the settings/landing_page document exists.
• Confirm your firestore.rules allow public reads on that document (see step 3).
• Hard-refresh with Ctrl + Shift + R (or Cmd + Shift + R) to bypass any cached HTML.

Image uploads show "Upload failed"

• The admin panel's toast displays the specific Firebase Storage error code (e.g. storage/unauthorized) — use it to pinpoint the cause.
• Make sure you are still signed in to the admin panel; expired sessions cause uploads to fail.
• Verify storage.rules permits the landing/… paths for authenticated users.

Logo or favicon doesn't update on the live site

• The browser caches favicons aggressively — close the tab and reopen, or do a hard refresh.
• The admin panel's Site title field controls the browser-tab title; leave it blank to fall back to "Brand — Tagline".

Play Store / App Store buttons go nowhere

• Both buttons are always rendered for layout consistency. When the corresponding URL is empty they render in a disabled state with a "Coming soon" tooltip.
• Paste the full URL (with or without https:// — the page auto-prefixes it) under Content → Landing Page → App download and save.

Here are solutions to common issues you might encounter during setup.

Flutter Issues

"flutter" is not recognized as a command

• Ensure Flutter is added to your system PATH. Restart your terminal after making changes.
• On Windows, verify via System Properties > Environment Variables.
• On macOS/Linux, check your .zshrc or .bashrc file.

flutter doctor shows issues

• Run flutter doctor -v for detailed output.
• Install missing components as indicated by the output.
• Accept Android licenses with: flutter doctor --android-licenses

Firebase Issues

Firebase CLI not found

• Install globally: npm install -g firebase-tools
• Verify with: firebase --version

Permission denied during firebase deploy

• Ensure you're logged in: firebase login
• Check that you have Editor or Owner role in the Firebase project.

Cloud Functions deployment fails

• Check you're on the Blaze plan (Cloud Functions require it).
• Run npm install inside the functions/ directory.
• Ensure Node.js version matches Firebase's requirements (check engines in functions/package.json).

Google Maps Issues

Map shows grey/blank

• Verify your API key is correct and not restricted to a different app.
• Ensure the required Google Maps APIs are enabled in the Google Cloud Console.
• Check that billing is enabled on your Google Cloud project.

Build Issues

Build fails with Gradle errors

• Run flutter clean followed by flutter pub get.
• Check that your minSdkVersion in android/app/build.gradle is compatible with all dependencies.

iOS build fails

• Run cd ios && pod install && cd .. to reinstall iOS dependencies.
• Open ios/Runner.xcworkspace in Xcode and check for signing/provisioning issues.

Q: Do I need a Mac to build the iOS app?

Yes. Xcode is required for building iOS apps, and Xcode only runs on macOS. You can develop and test the Android and Web versions on Windows or Linux.

Q: Which Firebase plan do I need?

The Blaze plan (pay-as-you-go) is recommended. Cloud Functions, phone authentication, and some other features are not available on the free Spark plan. The Blaze plan still includes a free usage tier.

Q: Can I use my own backend instead of Firebase?

HandyHive is designed to work with Firebase. Using a different backend would require significant modifications to the codebase.

Q: How do I update the app after making changes?

After making code changes, rebuild the app using the appropriate build commands (flutter build apk, flutter build web, etc.) and redeploy.

Q: The app crashes on startup. What should I check?

• Ensure google-services.json (Android) and GoogleService-Info.plist (iOS) are correctly placed.
• Verify Firebase is properly initialized in main.dart.
• Check the console logs for error messages using flutter run --verbose.

Q: How do I contact support?

• Email: info@elaynetech.com
• WhatsApp: +91 99046 97433