Quick Start Guide

Prerequisites

Before you begin, ensure you have the following installed:

Flutter SDK

Flutter SDK 2.2.0 or higher

Dart SDK

Dart SDK (included with Flutter)

Android Studio / Xcode

For Android or iOS development

Git

Version control system

You’ll also need a Firebase project and Mapbox account. We’ll set these up in the following steps.

Installation

Clone the Repository

Clone the Trackmart source code to your local machine:

git clone https://github.com/yourusername/trackmart.git
cd trackmart

Replace yourusername with the actual repository owner.

Install Dependencies

Install all required Flutter packages:

flutter pub get

This will install key dependencies including:

firebase_auth - User authentication
cloud_firestore - Database operations
firebase_database - Real-time data sync
geolocator - Location services
flutter_map - Map rendering
dio - HTTP networking

Configure Firebase

Create Firebase Project

Go to Firebase Console
Click “Add project” and follow the setup wizard
Enable the following services:
- Authentication (Email and Phone)
- Cloud Firestore
- Realtime Database
- Cloud Messaging

Add Firebase to Your App

Android
iOS

Download google-services.json from Firebase Console
Place it in android/app/
Verify android/build.gradle includes:

android/build.gradle

dependencies {
    classpath 'com.google.gms:google-services:4.3.3'
}

Verify android/app/build.gradle includes:

android/app/build.gradle

apply plugin: 'com.google.gms.google-services'

Download GoogleService-Info.plist from Firebase Console
Place it in ios/Runner/
Open ios/Runner.xcworkspace in Xcode
Right-click on Runner and select “Add Files to Runner”
Select GoogleService-Info.plist

Configure Firestore Security Rules

firestore.rules

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /users/{userId} {
      allow read, write: if request.auth != null;
    }
    match /buyers/{buyerId} {
      allow read, write: if request.auth != null;
    }
    match /drivers/{driverId} {
      allow read: if request.auth != null;
      allow write: if request.auth.uid == driverId;
    }
  }
}

Configure Mapbox

Get Mapbox Access Token

Create an account at Mapbox
Navigate to your Access Tokens page
Copy your default public token

Update Map Configuration

Open lib/map.dart and replace the Mapbox access token:

lib/map.dart

// Line 71 - Replace with your public token
var url = 'https://api.mapbox.com/directions/v5/mapbox/driving/'
          '${dlong},${dlat};${widget.ulong},${widget.ulat}'
          '?access_token=YOUR_PUBLIC_TOKEN_HERE';

// Line 139 - Replace with your secret token
'accessToken': 'YOUR_SECRET_TOKEN_HERE',

The code currently has hardcoded tokens. In production, use environment variables or secure configuration management.

Enable Location Permissions

Android
iOS

Add to android/app/src/main/AndroidManifest.xml:

AndroidManifest.xml

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.INTERNET" />

Add to ios/Runner/Info.plist:

Info.plist

<key>NSLocationWhenInUseUsageDescription</key>
<string>This app needs access to location for delivery tracking</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>This app needs access to location for real-time tracking</string>

Run the App

Connect your device or start an emulator, then run:

flutter run

For a release build:

flutter run --release

Use flutter devices to see all available devices and emulators.

First Run: Create Your Account

When you first launch Trackmart, you’ll see the welcome screen:

Authentication Options

Trackmart supports two authentication methods:

Phone Number
Email

The default authentication method using SMS verification.

lib/login_page.dart

Future<void> verifyPhone() async {
  await fAuth.verifyPhoneNumber(
    phoneNumber: this._countryCode + this.phoneNo,
    codeAutoRetrievalTimeout: autoRetrieve,
    codeSent: smsCodeSent,
    timeout: const Duration(seconds: 15),
    verificationCompleted: verifiedSuccess,
    verificationFailed: veriFailed
  );
}

Steps:

Select your country code (default: +254 for Kenya)
Enter your phone number
Choose a password
For new users: Enter your name and agree to terms
Tap “Sign up” or “Login”
Enter the SMS verification code sent to your phone

Alternative authentication using email and password.

lib/login_page.dart

Future<void> verifyEmail() async {
  if (login) {
    FirebaseUser user = await fAuth.signInWithEmailAndPassword(
      email: email, 
      password: _pin
    );
    if (user.isEmailVerified) {
      await saveUserDetails(user);
      widget.onSignedIn(user);
    } else {
      await user.sendEmailVerification();
      showMessageDialog(
        'Email is not verified, check $email for verification link'
      );
    }
  }
}

Steps:

Tap “Use Email instead”
Enter your email address
Choose a password
For new users: Enter your name and agree to terms
Tap “Sign up”
Check your email for verification link
Return to app and tap “Log in”

The app creates user profiles in both Firebase Realtime Database and Firestore for optimal performance.

Place Your First Order

After authentication, you’ll land on the home screen with three tabs:

Navigate to Request Tab

The middle tab is the “Request” tab where you create orders.

lib/home_page.dart

TabController _tabController;

@override
void initState() {
  super.initState();
  _tabController = TabController(
    vsync: this, 
    length: 3, 
    initialIndex: 1  // Starts on Request tab
  );
}

Select a Driver

You have two options to find drivers:

Option 1: Search by Name/Number

Type a driver’s name or phone number in the search field:

lib/home_page.dart

TextField(
  decoration: InputDecoration(
    labelText: 'Enter merchant\'s name or number:',
  ),
  onChanged: (value) {
    setState(() {
      _nameText = value;
    });
  },
)

Option 2: Map View

Tap the map icon in the app bar to see nearby drivers with distances and ETAs:

lib/home_page.dart

IconButton(
  icon: Icon(Icons.map),
  onPressed: () {
    Navigator.push(
      context,
      MaterialPageRoute(
        builder: (context) => MapPage2(
          ulat: currentLat,
          ulong: currentLong,
          selectDriver: _selectDriver,
        )
      )
    );
  },
)

The map shows:

Your current location (blue pin)
Available drivers (truck icons)
Distance to each driver
Estimated time of arrival

Configure Order Details

Set your order parameters:

lib/home_page.dart

Order makeOrderNow() {
  return Order(
    destlat: currentLat,
    destlong: currentLong,
    driverId: filteredDrivers[_selected].id,
    driverName: filteredDrivers[_selected].name,
    userId: currentUserId,
    userName: currentUserName,
    quantity: double.parse(_moneyController.text),
    payment: _paymnt,  // 'Mobile money' or 'Cash'
    price: rate,
    unit: _unit,  // 'Truck' or 'Tonne'
    timestamp: DateTime.now().millisecondsSinceEpoch,
  );
}

Quantity: Use +/- buttons or type a number Unit: Choose “Truck” or “Tonne” from dropdown Payment: Select “Mobile money” or “Cash”The app automatically calculates total cost based on current rates.

Submit Request

Tap the blue “Request” button to send your order:

lib/home_page.dart

_requestDelivery(Order order, BuildContext context) async {
  String key = 'O:${DateTime.now().millisecondsSinceEpoch}';
  await databaseReference
      .child('Drivers')
      .child(order.driverId)
      .child('requests')
      .update({key: order.toMap(currentUserId)});
  
  await databaseReference
      .child('buyers')
      .child(currentUserId)
      .child('requests')
      .update({key: order.toMap(currentUserId)});
}

You’ll see a confirmation dialog with order summary. Tap “Request” to confirm.

Track Your Order

Switch to the “Orders” tab to see your order status:

Requested: Waiting for driver acceptance
In Transit: Driver is on the way
Delivered: Order completed

Tap any in-transit order to open the live map view with real-time tracking.

Testing the App

For testing, you’ll need at least two accounts: one buyer and one driver. The driver functionality is typically in a separate driver app.

Manual Testing Checklist

Phone authentication with SMS verification
Email authentication with verification link
Location permissions granted
User profile creation in Firebase
View available drivers on map
Create order with different units and payment methods
View order in Orders tab
Chat with driver
Real-time location updates

Troubleshooting

SMS Verification Not Working

Issue: Not receiving SMS codes during phone authentication.Solutions:

Verify Firebase Authentication is enabled for Phone provider
Check that your Firebase project has billing enabled (required for SMS)
Test with a Firebase test phone number in Authentication settings
Check phone number format includes country code

Map Not Loading

Issue: Map tiles not appearing or routes not calculating.Solutions:

Verify Mapbox access tokens are correct
Check internet connectivity
Ensure location permissions are granted
Check browser console for API errors

Location Permission Denied

Issue: App can’t access device location.Solutions:

Go to device Settings > Apps > Trackmart > Permissions
Enable Location permission
On iOS, check Info.plist has location usage descriptions
On Android, check AndroidManifest.xml has location permissions

Build Errors

Issue: Flutter build fails with dependency errors.Solutions:

# Clean build files
flutter clean

# Get dependencies
flutter pub get

# Run pub upgrade
flutter pub upgrade

# Rebuild
flutter run

Some packages use older versions. Consider updating pubspec.yaml with latest compatible versions.

Next Steps

Now that you have Trackmart running, explore these topics:

Firebase Configuration

Deep dive into Firebase services setup and security rules

Mapbox Setup

Advanced mapping features and customization

Push Notifications

Configure Firebase Cloud Messaging for order updates

Development Guide

Set up your development environment and start building

Get Started

Core Features

User Guides

Configuration

Prerequisites

Flutter SDK

Dart SDK

Android Studio / Xcode

Git

Installation

Create Firebase Project

Add Firebase to Your App

Configure Firestore Security Rules

Get Mapbox Access Token

Update Map Configuration

First Run: Create Your Account

Authentication Options

Place Your First Order

Testing the App

Manual Testing Checklist

Troubleshooting

Next Steps

Firebase Configuration

Mapbox Setup

Push Notifications

Development Guide

Build docs developers (and LLMs) love

Get Started

Core Features

User Guides

Configuration

​Prerequisites

Flutter SDK

Dart SDK

Android Studio / Xcode

Git

​Installation

​Create Firebase Project

​Add Firebase to Your App

​Configure Firestore Security Rules

​Get Mapbox Access Token

​Update Map Configuration

​First Run: Create Your Account

​Authentication Options

​Place Your First Order

​Testing the App

​Manual Testing Checklist

​Troubleshooting

​Next Steps

Firebase Configuration

Mapbox Setup

Push Notifications

Development Guide

Build docs developers (and LLMs) love

Prerequisites

Installation

Create Firebase Project

Add Firebase to Your App

Configure Firestore Security Rules

Get Mapbox Access Token

Update Map Configuration

First Run: Create Your Account

Authentication Options

Place Your First Order

Testing the App

Manual Testing Checklist

Troubleshooting

Next Steps