Introduction

The DayOneMart Deliveryman App is a dedicated Flutter mobile application for delivery personnel. It enables deliverymen to receive and manage assigned orders, navigate to delivery locations via Google Maps, update order statuses in real-time, communicate with admin via live chat, and manage their account — all from a single app on Android and iOS.

The app connects to the OneMart Admin & Web backend exclusively via the REST API at /api/v1/delivery-man/*. Push notifications are delivered through Firebase Cloud Messaging.

Technology Stack

Architecture Overview

The deliveryman app follows the same feature-first clean architecture pattern as the customer app:

• Feature modules — each feature is self-contained under lib/features/<feature>/
• BLoC pattern — UI is decoupled from business logic via Blocs and Cubits
• GetIt / Injectable — dependency injection with code-generated service locator
• Freezed — immutable data classes and sealed union states
• GoRouter — declarative navigation with deep-link support and fade transitions
• Repository pattern — data sources abstracted behind repository interfaces

App Features

Key Screens (Annotated)

Capture these core screens on a device or emulator and annotate the numbered areas below with arrows or callouts before resubmission. Save each image with the exact file name shown.

1 2 3 4

Key areas of this screen

1. Greeting & See Orders — a summary of how many orders are waiting, with a shortcut to the order list; the bell shows new notifications.
2. Delivery KPI cards — Pending, Ongoing, Completed, and Cancelled delivery counts.
3. Recent orders — the latest assigned orders with status, amount, payment type, and View Details.
4. Bottom navigation — Home, Orders, Chatting, and Account tabs.

1 2 3 4

Key areas of this screen

1. Status filter tabs — switch between On the Way, Ready to Handover, Confirmed, and Delivered.
2. Order card header — order number, item count, and date/time.
3. Amount & View Details — the order total and the button that opens the full order (customer, address, items, and status actions).
4. Bottom navigation — Home, Orders, Chatting, and Account tabs.

Prerequisites

Development Machine Requirements

External Services Required

• Firebase Project — push notifications (FCM), analytics, crashlytics
• Google Maps API Key — map display, directions, delivery navigation
• Backend URL — a running OneMart Admin & Web instance with the deliveryman API enabled

Flutter Environment Check

flutter doctor -v

Resolve all errors before proceeding. Warnings for unneeded platforms (e.g. Linux, Windows) can be ignored if you only target Android/iOS.

Project Structure

lib/
├── main.dart                       ← App entry point + Firebase init
├── firebase_options.dart           ← Generated by FlutterFire CLI
│
├── config/
│   ├── route/
│   │   └── route_config.dart       ← GoRouter route definitions
│   ├── theme/                      ← App theme (colors, typography)
│   └── util/
│       ├── app_constants.dart      ← API base URL + all endpoints
│       ├── assets.gen.dart         ← Generated asset references
│       ├── dimensions.dart         ← Spacing / size constants
│       └── styles.dart             ← Reusable TextStyles
│
├── core/
│   ├── data/
│   │   └── api/                    ← Base HTTP client, interceptors
│   ├── model/
│   │   └── response/              ← Generic response wrappers
│   ├── dependency_injection/       ← GetIt setup + injectable config
│   ├── helper/                     ← Notification helper, extensions, utils
│   └── catcher_logs/               ← Catcher_2 error reporting config
│
├── features/                       ← Feature-first modules
│   ├── splash/                     ← Splash screen + connectivity check
│   ├── login/                      ← Auth (login, OTP, forgot password, set password)
│   ├── home/                       ← Home screen + dashboard BLoC
│   ├── dashboard/                  ← Bottom nav shell + tab management
│   ├── order/                      ← Order list, details, delivery location, cancel, result
│   ├── chat/                       ← Chat list, conversations, message sending
│   ├── account/                    ← Profile, edit profile, change password, delete account
│   ├── notification/               ← Notification list + management
│   ├── settings/                   ← Settings screen, language, theme, password setup
│   ├── contact_us/                 ← Contact support form
│   ├── terms_and_condition/        ← Terms of service viewer
│   ├── file_viewer/                ← Image/media file viewer
│   ├── html/                       ← Generic HTML content renderer
│   └── common/                     ← Shared widgets, theme BLoC
│
├── l10n/
│   ├── arb/                        ← ARB localization source files
│   │   ├── app_en.arb
│   │   ├── app_es.arb
│   │   ├── app_ar.arb
│   │   ├── app_hi.arb
│   │   └── app_bn.arb
│   └── gen/                        ← Generated localization classes
│       └── app_localizations.dart
│
assets/
├── images/                         ← PNG / JPG images
│   ├── svg/                        ← SVG icons
│   │   └── flags/                  ← Country flag SVGs
│   └── gif/                        ← Animated GIFs

Feature Module Structure

Each feature follows the same internal layout:

features/order/
├── data/
│   ├── models/             ← Freezed + JSON serializable DTOs
│   └── repositories/       ← Repository implementation (API calls)
├── domain/
│   └── services/           ← Domain service / repository interface
└── presentation/
    ├── bloc/               ← BLoC / Cubit + States + Events
    │   ├── order/          ← Order list & detail BLoC
    │   └── order_delivery_location/  ← Map tracking BLoC
    ├── screens/            ← Full-screen widgets
    ├── widgets/            ← Reusable widgets for this feature
    └── utils/              ← Feature-specific utilities

Navigation Structure

The app uses a ShellRoute for the main dashboard with a bottom navigation bar housing four tabs:

Installation Guide (Step-by-Step)

Follow these steps in order to go from the downloaded ZIP to the app running on a device. Steps 6–7 point to their own detailed sections further down this page.

Before You Start — Checklist

• Flutter SDK installed and flutter doctor passes
• Android Studio / Xcode configured with emulator/simulator
• Firebase project created (you will register the apps in Step 6; default package: com.dayonesoft.onemartdeliveryman)
• Google Maps API key obtained and enabled for Maps SDK + Directions API
• Backend (Admin & Web) is deployed and accessible — install it first

1. Extract the project Unzip the package and open the Delivery Man App folder in your editor (VS Code / Android Studio). All commands below are run from this folder.
2. Verify your Flutter environment

   flutter doctor -v
   

   Fix any reported errors (missing Android SDK, unaccepted licenses, no Xcode) before continuing.
3. Install dependencies

   flutter pub get
   

4. Generate code The project relies on code generation — it will not compile without this step:

   dart run build_runner build --delete-conflicting-outputs
   flutter gen-l10n
   

5. Point the app at your backend Open lib/config/util/app_constants.dart and set baseUrl to your deployed Admin & Web instance (always https:// in production). Also set your currency symbol — see Configuration.
6. Connect Firebase Register the Android and iOS apps in your Firebase project, then place google-services.json in android/app/ and GoogleService-Info.plist in ios/Runner/ (or run flutterfire configure). Full walkthrough: Firebase Setup.
7. Add your Google Maps API key Copy secrets.xml.example to android/app/src/main/res/values/secrets.xml and fill in the key; add the iOS key to Info.plist. Full walkthrough: Google Maps Setup.
8. Run the app

   flutter devices                  # list connected devices
   flutter run -d <device-id>      # debug build on a device
   

   Log in with a deliveryman account created in the Admin Panel (Users → Deliverymen → Create New), assign that deliveryman a test order, and confirm it appears on the app dashboard.
9. Rebrand and release Rename the app, set your bundle ID, icon, splash, and colors using the Branding & Customization Guide, then produce store builds following Build & Release.

Configuration

API Base URL

Open lib/config/util/app_constants.dart and update the baseUrl to point to your deployed OneMart Admin & Web instance:

// lib/config/util/app_constants.dart

class AppConstants {
  static const String baseUrl = 'https://yourdomain.com';
  // ...
}

App Name & Bundle ID

Currency Symbol

The default currency symbol is configured in app_constants.dart:

static String currencySymbol = "৳";           // Change to your currency
static String currencySymbolPosition = 'left'; // 'left' or 'right'

Annotate on the Settings screen

1. Language selector — switch the app's display language.
2. Set up password — for accounts created via OTP login.
3. Permission toggles — notification, location, and microphone access.
4. Theme toggle — dark / light mode preference.

Firebase Setup

1. Create or select your Firebase project Go to the Firebase Console. You can reuse the same Firebase project used for the Admin & Web backend and Customer App.
2. Register Android app Use the package name com.dayonesoft.onemartdeliveryman. Download google-services.json and place it at:

   android/app/google-services.json
   

3. Register iOS app Use the bundle ID com.dayonesoft.onemartdeliveryman. Download GoogleService-Info.plist and add it to Xcode at:

   ios/Runner/GoogleService-Info.plist
   

4. Generate firebase_options.dart

   # Install FlutterFire CLI (if not already installed)
   dart pub global activate flutterfire_cli
   
   # Login to Firebase
   firebase login
   
   # Generate firebase_options.dart
   flutterfire configure
   

   This creates/updates lib/firebase_options.dart automatically.
5. Enable Firebase services In the Firebase Console, enable:

   • Cloud Messaging (FCM) — required for push notifications
   • Crashlytics — automatic crash reporting
   • Analytics — usage analytics

FCM Topics

The app subscribes to the following FCM topics on launch:

deliveryman-group    // All deliveryman-specific broadcast messages
all-general          // Platform-wide announcements

Google Maps Setup

Step 1 — Enable APIs in Google Cloud Console

• Maps SDK for Android
• Maps SDK for iOS
• Directions API (for delivery route navigation)
• Geocoding API

Step 2 — Configure Android (secrets.xml)

Copy the template and fill in your Google Maps API key:

cp secrets.xml.example android/app/src/main/res/values/secrets.xml

<!-- android/app/src/main/res/values/secrets.xml -->
<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="google_maps_api_key">YOUR_GOOGLE_MAPS_API_KEY</string>
</resources>

Step 3 — Configure iOS

Add the Google Maps API key to ios/Runner/Info.plist:

<key>GoogleMapsApiKey</key>
<string>YOUR_GOOGLE_MAPS_API_KEY</string>

Location Permissions

The app uses geolocator, location, and permission_handler to request and manage location permissions. On first launch, the user is prompted to grant location access, which is required for delivery navigation. The required permission entries are already included in the AndroidManifest.xml and Info.plist.

Localization

The app supports 5 languages out of the box:

Localization Config

The localization configuration is defined in l10n.yaml:

arb-dir: lib/l10n/arb
template-arb-file: app_en.arb
output-localization-file: app_localizations.dart
output-dir: lib/l10n/gen
nullable-getter: false

Adding a New Language

1. Create a new ARB file, e.g. lib/l10n/arb/app_fr.arb. Copy the structure from app_en.arb and translate all strings.
2. Add the language to the languages list in app_constants.dart:

   LanguageModel(code: 'fr', name: 'French', nativeName: 'Français'),
   

3. Regenerate localization files:

   flutter gen-l10n
   

Mobile App Build Requirements

A store-ready build of the deliveryman app requires platform-specific code signing on both Android and iOS. This section covers Android keystore generation and iOS code signing from start to finish. Set these up once — the signing material is reused for every future release and update.

Android — Keystore Generation

Google Play requires every release build to be digitally signed with a keystore you own. Generate one with the JDK's keytool utility:

keytool -genkey -v \
  -keystore upload-keystore.jks \
  -keyalg RSA -keysize 2048 -validity 10000 \
  -alias upload

You will be prompted for a keystore password, a key password, and your organisation details. This produces an upload-keystore.jks file. Move it into the Android app module (for example android/app/upload-keystore.jks), then create android/key.properties so Gradle can locate and use it:

# android/key.properties
storePassword=<your-store-password>
keyPassword=<your-key-password>
keyAlias=upload
storeFile=upload-keystore.jks

The Android app module is already configured to read key.properties and apply the release signing config automatically, so no Gradle edits are required. Once the file is in place, flutter build appbundle --release produces a signed, upload-ready bundle.

iOS — Code Signing

iOS builds must be signed with credentials issued by Apple. A paid Apple Developer Program membership is required before you can create a distributable build.

1. Register an App ID (Bundle Identifier) In the Apple Developer portal → Certificates, Identifiers & Profiles → Identifiers, register a unique bundle ID (e.g. com.yourcompany.onemartdeliveryman) and enable the Push Notifications capability.
2. Create a Distribution certificate Under Certificates, create an Apple Distribution certificate and install it into your Mac's login Keychain. This identity signs release builds.
3. Create a provisioning profile Create an App Store distribution provisioning profile that links your App ID to the distribution certificate, then download and double-click it to install.
4. Configure signing in Xcode Open ios/Runner.xcworkspace → select the Runner target → Signing & Capabilities. Set your Team and the Bundle Identifier to match the App ID above. Automatically manage signing is recommended for most users.
5. Create the app record in App Store Connect In App Store Connect, create a new app using the same bundle ID so you can upload builds to TestFlight and the App Store.

Build & Release

Android — Signing Setup

1. Create a release keystore:

   keytool -genkey -v -keystore android/app/upload-keystore.jks \
     -keyalg RSA -keysize 2048 -validity 10000 -alias upload
   

2. Create android/key.properties:

   storePassword=<your-store-password>
   keyPassword=<your-key-password>
   keyAlias=upload
   storeFile=upload-keystore.jks
   

Android — Debug APK

flutter build apk --debug
# Output: build/app/outputs/flutter-apk/app-debug.apk

Android — Release APK

flutter build apk --release --obfuscate --split-debug-info=build/app/outputs/symbols
# Output: build/app/outputs/flutter-apk/app-release.apk

Android — App Bundle (Google Play)

flutter build appbundle --release --obfuscate --split-debug-info=build/app/outputs/symbols
# Output: build/app/outputs/bundle/release/app-release.aab

iOS — Release (App Store)

flutter build ipa --release --obfuscate --split-debug-info=build/ios/symbols

Then open build/ios/ipa in Xcode Organizer or use Transporter to upload to App Store Connect.

Publishing to Google Play — Step by Step

With the signed .aab from the previous section, here is the complete path from build to a live Google Play listing:

1. Create a Google Play developer account Register at play.google.com/console (one-time $25 fee). Identity verification can take a day or two for new accounts.
2. Create the app In the Play Console: All apps → Create app. Enter the app name, default language, select App (not Game) and Free, and accept the declarations.
3. Complete the "Set up your app" checklist On the app's Dashboard, work through every task before your first release: privacy policy URL, App access (provide a working demo deliveryman login so Google's reviewers can sign in), Ads declaration, Content rating, Target audience, and the Data safety form — declare that the app collects the rider's location, name, email, and phone number for delivery operations.
4. Build the signed bundle Confirm android/key.properties is in place, then run flutter build appbundle --release. The signed bundle is written to build/app/outputs/bundle/release/app-release.aab.
5. Test with an Internal testing release first Go to Testing → Internal testing → Create new release, upload the .aab, add your email as a tester, and install the app on a real device via the opt-in link. Verify rider login, going online, receiving an assigned order, status updates, and map navigation against your live backend before going public.
6. Roll out to Production Once the internal build works, go to Production → Create new release (or promote the internal release), add release notes, review, and Start rollout.

Publishing to the App Store — Step by Step

1. Prerequisites Complete the iOS code-signing setup above: Apple Developer membership, App ID, signing configured in Xcode, and the app record created in App Store Connect.
2. Build the signed archive Run flutter build ipa --release. The signed .ipa is written to build/ios/ipa/.
3. Upload the build Open Apple's free Transporter app (Mac App Store), sign in with your Apple ID, drag the .ipa in, and click Deliver. (Alternative: open the archive in Xcode Organizer and click Distribute App.)
4. Wait for processing, then test via TestFlight In App Store Connect the build appears under TestFlight after 15–60 minutes of processing. Install it on a real device with the TestFlight app and verify rider login, order flow, and push notifications.
5. Complete the App Store listing In App Store Connect fill in: screenshots for the required device sizes, description, keywords, support URL, privacy policy URL, and the App Privacy questionnaire (declare location, contact info, and identifiers collected for delivery operations).
6. Submit for review Select the build, add review notes with a working demo deliveryman account (Apple rejects apps it cannot log in to), and submit. Reviews typically complete within 24–48 hours.

Versioning App Updates

The app version lives in pubspec.yaml:

# pubspec.yaml
version: 3.0.0+30
#        │     └─ build number → Android versionCode / iOS build number
#        └─────── display version → Android versionName / iOS version

Every upload to Google Play or App Store Connect must have a higher build number (the part after +) than the previous upload. Bump it, rebuild, and re-upload — e.g. 3.0.0+30 → 3.0.1+31.

Common Build & Signing Errors

API Integration

All API endpoints are declared in lib/config/util/app_constants.dart. The HTTP client in lib/core/data/api/ prepends the baseUrl and handles JWT token attachment, refresh, and error handling automatically.

Authentication Flow

POST /api/v1/delivery-man/auth/login               ← Email/phone + password
POST /api/v1/delivery-man/auth/send-login-otp       ← Request login OTP
POST /api/v1/delivery-man/auth/verify-login-otp     ← Verify OTP → returns JWT
POST /api/v1/delivery-man/auth/forgot-password       ← Initiate password reset
POST /api/v1/delivery-man/auth/verify-otp            ← Verify reset OTP
POST /api/v1/delivery-man/auth/reset-password        ← Set new password
POST /api/v1/delivery-man/auth/refresh               ← Refresh JWT token
POST /api/v1/delivery-man/auth/logout                ← Invalidate session

Core Endpoints

Request Headers

Authorization: Bearer {jwt_token}
Accept: application/json
Content-Type: application/json
X-localization: en         ← Current language code

Troubleshooting

"google-services.json not found"

Ensure you have downloaded the file from Firebase Console and placed it at:

android/app/google-services.json

"Cannot resolve symbol '@string/google_maps_api_key'"

Create secrets.xml from the template:

cp secrets.xml.example android/app/src/main/res/values/secrets.xml
# Then edit secrets.xml and add your real API key

Firebase Initialization Failed

dart pub global activate flutterfire_cli
flutterfire configure

Build Runner Conflicts

dart run build_runner clean
dart run build_runner build --delete-conflicting-outputs

Gradle Build Failures (Android)

• Run flutter clean && flutter pub get and try again
• Ensure JAVA_HOME points to JDK 17
• Check that google-services.json is present
• Invalidate Android Studio caches: File → Invalidate Caches

CocoaPods Issues (iOS)

cd ios
pod deintegrate
pod install --repo-update
cd ..
flutter build ios

Google Maps Not Showing

• Verify the API key in secrets.xml (Android) and Info.plist (iOS)
• Ensure Maps SDK + Directions API are enabled in Google Cloud Console
• Check that billing is enabled on the Google Cloud project
• On Android, check logcat for "API key not valid" errors

Push Notifications Not Received

• Verify Firebase config files are up to date
• Ensure FCM Server Key is configured in Admin Panel under Settings → Firebase Setup
• On iOS: push notifications require a physical device and a valid APNs key in Firebase
• Test FCM delivery directly from Firebase Console → Cloud Messaging

Location Permission Denied

• On Android: check AndroidManifest.xml has ACCESS_FINE_LOCATION and ACCESS_COARSE_LOCATION
• On iOS: check Info.plist has NSLocationWhenInUseUsageDescription and NSLocationAlwaysUsageDescription
• If the user denied permission, guide them to Settings → App → Permissions

General Reset

flutter clean
flutter pub get
dart run build_runner build --delete-conflicting-outputs
flutter gen-l10n
flutter run

FAQ & Environment-Specific Issues

Common environment-specific hurdles when setting up and building the Flutter app.

API requests time out or fail to connect

• Confirm baseUrl in app_constants.dart is correct and starts with https://.
• Ensure the backend is reachable from the device's network and that any firewall or cloud security group permits inbound traffic on the API port.
• Android emulator reaching a server on your own machine must use 10.0.2.2 instead of localhost; the iOS simulator can use localhost.
• Android 9+ and iOS block plaintext HTTP by default — always serve the API over HTTPS.

Gradle / Android build fails on a fresh machine

• Point JAVA_HOME at JDK 17 — newer or older JDKs commonly break the Android Gradle Plugin.
• Run flutter clean && flutter pub get, then rebuild.
• Behind a proxy or firewall, configure it in ~/.gradle/gradle.properties so Gradle can download dependencies.

CocoaPods / iOS build fails

cd ios
pod repo update
pod install --repo-update
cd ..
flutter build ios

On Apple Silicon, if pods fail to install, retry under Rosetta: arch -x86_64 pod install.

build_runner or code generation errors

dart run build_runner clean
dart run build_runner build --delete-conflicting-outputs
flutter gen-l10n

Location, Firebase, or Maps features do nothing at runtime

• Verify google-services.json (Android) and GoogleService-Info.plist (iOS) are present and match your Firebase project.
• Ensure Maps SDK + Directions API are enabled and that billing is active on the Google Cloud project — the map renders blank without it.
• Grant location permission when prompted; if previously denied, re-enable it in the OS Settings → App → Permissions screen.

Customization

App Theme & Colors

The global theme is defined in lib/config/theme/. The app supports both light and dark themes with a ThemeBLoC in features/common/. Update color values and typography in the theme files — changes propagate automatically via Flutter's Theme.of(context).

App Icon

# Replace the icon images:
# Android: android/app/src/main/res/mipmap-*/ic_launcher.png
# iOS: ios/Runner/Assets.xcassets/AppIcon.appiconset/

# Or use the flutter_launcher_icons package for automated generation

Adding a New Feature

1. Create the feature folder under lib/features/<feature_name>/ with data/, domain/, and presentation/ sub-directories.
2. Define Freezed models in data/models/ and run dart run build_runner build.
3. Create the BLoC/Cubit in presentation/bloc/ and register it with GetIt using the @injectable annotation.
4. Add routes in lib/config/route/route_config.dart. If the screen should be a dashboard tab, nest it inside the ShellRoute.

Modifying the Dashboard Tabs

The bottom navigation is managed by DashboardScreen in lib/features/dashboard/presentation/screens/dashboard_screen.dart. The four tabs (Home, Orders, Chat, Account) are defined as ShellRoute children in route_config.dart. To add or remove a tab, update both the ShellRoute routes list and the BottomNavigationBar items.

Need help? Reach us via the item’s Support tab on CodeCanyon or dayonesoft.com or visit our website for support.