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

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:

Quick Start

Setup Checklist

• Flutter SDK installed and flutter doctor passes
• Android Studio / Xcode configured with emulator/simulator
• Firebase project created with Android + iOS apps registered (package: com.dayonesoft.onemartdeliveryman)
• Google Maps API key obtained and enabled for Maps SDK + Directions API
• Backend (Admin & Web) is deployed and accessible

Install and Run

# 1. Get all pub packages
flutter pub get

# 2. Generate code (freezed models, injectable DI, asset refs)
dart run build_runner build --delete-conflicting-outputs

# 3. Generate localization files
flutter gen-l10n

# 4. Run the app
flutter run

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'

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
   

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.

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

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? Contact contact@6amtech.com or visit our website for support.