Introduction

The DayOneMart Customer App is a cross-platform mobile application built with Flutter for Android and iOS. It provides customers with a complete shopping experience — browsing products, placing orders, real-time tracking, live chat, wallet management, loyalty points, and more.

The app connects exclusively to the OneMart Admin & Web backend via the REST API at /api/v1/customer/*. Real-time features (chat, notifications) are powered by Firebase Cloud Messaging.

Technology Stack

Architecture Overview

The app follows a feature-first clean architecture pattern:

• 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
• Repository pattern — data sources are abstracted behind repository interfaces

App Features

Prerequisites

Development Machine Requirements

External Services Required

• Firebase Project — push notifications, analytics, crashlytics
• Google Maps API Key — maps, geocoding, place autocomplete
• Facebook App — Facebook social login (optional)
• Apple Developer Account — Sign in with Apple and iOS distribution
• Backend URL — a running OneMart Admin & Web instance

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_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
│       ├── instance_names.dart     ← GetIt named instance keys
│       └── styles.dart             ← Reusable TextStyles
│
├── core/
│   ├── data/                       ← Base network client, interceptors, enums
│   ├── dependency_injection/       ← GetIt setup + injectable module
│   └── helper/                     ← Utility helpers (notifications, extensions)
│
├── features/                       ← Feature-first modules
│   ├── splash/
│   ├── onboarding/
│   ├── login/                      ← Auth BLoC, repo, screens
│   ├── home/
│   ├── dashboard/
│   ├── category/
│   ├── menu/
│   ├── search/
│   ├── cart/
│   ├── checkout/
│   ├── offers/
│   ├── order/
│   ├── payment/
│   ├── wallet/
│   ├── loyalty_point/
│   ├── referral/
│   ├── wishlist/
│   ├── review/
│   ├── notification/
│   ├── chat/
│   ├── account/
│   ├── address/
│   ├── settings/
│   ├── about_us/
│   ├── contact_us/
│   ├── faq/
│   ├── privacy_policy/
│   ├── terms_and_condition/
│   ├── refund_policy/
│   ├── common_condition/
│   ├── html/
│   ├── webview/
│   └── file_viewer/
│
└── 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
└── json/                           ← Lottie animation JSON files

Feature Module Structure

Each feature follows the same internal layout:

features/order/
├── data/
│   ├── datasource/         ← Remote data source (API calls)
│   ├── model/              ← Freezed + JSON serializable DTOs
│   └── repository/         ← Repository implementation
├── domain/
│   ├── entity/             ← Clean domain entities
│   └── repository/         ← Repository abstract interface
└── presentation/
    ├── bloc/               ← BLoC / Cubit + States + Events
    ├── screen/             ← Full-screen widgets
    └── widget/             ← Reusable widgets for this feature

Quick Start

Setup Checklist

• Flutter SDK installed and flutter doctor passes
• Android Studio / Xcode configured with emulator/simulator
• Firebase project created and both Android + iOS apps registered
• Google Maps API key obtained and enabled for Maps SDK, Geocoding, Places APIs
• Backend (Admin & Web) is deployed and accessible
• Facebook App ID and client token ready (if enabling Facebook login)

Clone and Install Dependencies

# Get all pub packages
flutter pub get

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

Run the App

# List connected devices
flutter devices

# Run on a specific device (debug mode)
flutter run -d <device-id>

# Run in release mode (closer to production)
flutter run --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';
  // All endpoint paths are defined as constants below...
}

App Module

The app supports multiple business modules. The default is set in lib/config/util/app_constants.dart:

// lib/config/util/app_constants.dart
static const AppModule defaultModule = AppModule.grocery;

Change this enum value to match your business type if needed.

App Name & Bundle ID

Firebase Setup

Step 1 — Create a Firebase Project

1. Go to the Firebase Console and create a new project (or use an existing one shared with the backend).
2. Register Android app — use the package name from android/app/build.gradle (default: com.dayonesoft.onemartcustomer). Download google-services.json and place it at android/app/google-services.json.
3. Register iOS app — use the bundle ID from Xcode. Download GoogleService-Info.plist and add it to Xcode at ios/Runner/GoogleService-Info.plist.

Step 2 — Generate firebase_options.dart (Recommended)

Use the FlutterFire CLI for a clean, automated setup:

# Install FlutterFire CLI
dart pub global activate flutterfire_cli

# Configure — follow the interactive prompts
flutterfire configure

This generates/updates lib/firebase_options.dart automatically.

Step 3 — Enable Firebase Services

In the Firebase Console, enable the following services:

• Cloud Messaging (FCM) — required for push notifications
• Crashlytics — automatic crash reporting
• Analytics — usage analytics
• Authentication — enable Google, Facebook, and Apple sign-in providers

FCM Topics

The app subscribes to the following FCM topics on launch:

customer-group    // All customer-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
• Places API
• Geocoding API
• Directions API

Step 2 — Add API Key to secrets.xml (Android)

Copy the template and fill in your key:

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

<!-- android/app/src/main/res/values/secrets.xml -->
<resources>
  <string name="google_maps_api_key">YOUR_GOOGLE_MAPS_API_KEY</string>
  <string name="facebook_app_id">YOUR_FACEBOOK_APP_ID</string>
  <string name="fb_login_protocol_scheme">fbYOUR_FACEBOOK_APP_ID</string>
  <string name="facebook_client_token">YOUR_FACEBOOK_CLIENT_TOKEN</string>
</resources>

Step 3 — Add API Key for iOS

In ios/Runner/AppDelegate.swift, the Maps key is read from the Info.plist. Add it to ios/Runner/Info.plist:

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

Social Auth Setup

Google Sign-In

• Enable Google as a sign-in provider in your Firebase project
• The google-services.json / GoogleService-Info.plist files include the required OAuth client IDs automatically
• No additional native code changes required

Facebook Login

1. Create a Facebook App at developers.facebook.com. Add "Facebook Login" as a product. Note the App ID and client token.
2. Add credentials to secrets.xml (Android) as shown in the Google Maps section above.
3. iOS: Add FacebookAppID, FacebookClientToken, and FacebookDisplayName keys to ios/Runner/Info.plist. Also add the URL scheme fb{YOUR_APP_ID} to the CFBundleURLSchemes array.

Sign in with Apple

• Requires an Apple Developer Account
• Enable "Sign in with Apple" capability in your App ID on developer.apple.com
• Enable the Apple sign-in provider in Firebase Authentication
• In Xcode: open ios/Runner.xcworkspace → Signing & Capabilities → add "Sign in with Apple"
• Sign in with Apple is iOS-only; it is conditionally hidden on Android

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 — Debug Build

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

Android — Release APK

flutter build apk --release
# 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

Android — Signing

The app is already configured to automatically sign release builds when you provide a key.properties file.

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
   

iOS — Debug

flutter build ios --debug --simulator

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.

Code Generation (after model changes)

# One-time build
dart run build_runner build --delete-conflicting-outputs

# Watch mode (during development)
dart run build_runner watch --delete-conflicting-outputs

Secure Storage

Auth tokens are stored securely via flutter_secure_storage (Android Keystore / iOS Keychain) instead of SharedPreferences.

Android

• minSdkVersion must be 23 or higher — already configured in android/app/build.gradle.kts
• AndroidManifest.xml sets android:allowBackup="false" and android:fullBackupContent="false" to prevent decryption errors after auto-restore

iOS

• iOS deployment target must be 12.0 or higher (already satisfied by the current Podfile)
• The Keychain Sharing capability is enabled via ios/Runner/Runner.entitlements
• If you regenerate the Xcode project, re-add it: Xcode → Runner target → Signing & Capabilities → + Capability → Keychain Sharing

Crash Reporting

The app uses Firebase Crashlytics for crash reporting in production builds.

Setup

• Enable Crashlytics in the Firebase Console for the project configured by flutterfire configure
• Android symbols are uploaded automatically by the Crashlytics Gradle plugin (already wired in android/app/build.gradle.kts)
• iOS dSYMs upload via the standard Crashlytics run-script build phase in Xcode
• When building with --obfuscate --split-debug-info, upload the symbols to Firebase for deobfuscated crash reports

API Integration

All API endpoints consumed by the app are declared as constants in lib/config/util/app_constants.dart. The base URL is prepended at runtime by the core HTTP client in lib/core/data/.

Authentication Flow

POST /api/v1/customer/auth/check-user-exists  ← Check if user exists
POST /api/v1/customer/auth/login              ← Email/phone + password
POST /api/v1/customer/auth/send-login-otp     ← Request login OTP
POST /api/v1/customer/auth/verify-login-otp   ← Verify OTP → returns JWT
POST /api/v1/customer/auth/forgot-password     ← Initiate password reset
POST /api/v1/customer/auth/verify-otp          ← Verify reset OTP
POST /api/v1/customer/auth/reset-password      ← Set new password
POST /api/v1/customer/auth/google             ← Google ID token
POST /api/v1/customer/auth/facebook           ← Facebook access token
POST /api/v1/customer/auth/apple              ← Apple identity token
POST /api/v1/customer/auth/refresh            ← Refresh JWT
POST /api/v1/customer/auth/logout

Request Headers

Authorization: Bearer {jwt_token}
Accept: application/json
Content-Type: application/json
X-localization: en         ← Current language code (en, ar, hi, es, bn)

Core Endpoints Summary

Troubleshooting

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 in android/app/
• 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 for Android / iOS is 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 google-services.json and GoogleService-Info.plist are up to date
• Ensure FCM is enabled in your Firebase project
• Check that the FCM Server Key is configured in the Admin Panel under Settings → Firebase Setup
• On iOS, push notifications require a physical device and a valid APNs certificate/key in Firebase
• Test FCM delivery directly from the Firebase Console → Cloud Messaging

Network / API Errors

• Confirm baseUrl in app_constants.dart is correct and includes the protocol (https://)
• For Android emulator accessing a local server: use 10.0.2.2 instead of localhost
• Verify the backend server is running and accessible from the device's network
• Check for CORS errors on the backend if using a web build

Localization Not Updating

flutter gen-l10n
flutter clean
flutter pub get

facebook_auth Login Fails on iOS

• Ensure FacebookAppID and the fb{APP_ID} URL scheme are added to Info.plist
• Enable Facebook Login product in your Facebook App dashboard
• Add your iOS bundle ID to the Facebook App's settings

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/. Update color seeds, typography, and component themes there. All UI components reference the theme via Flutter's Theme.of(context) — changes propagate automatically.

App Icon

# Replace the source image:
# android: android/app/src/main/res/mipmap-*/ic_launcher.png
# ios: ios/Runner/Assets.xcassets/AppIcon.appiconset/

# Or use flutter_launcher_icons package:
dart pub global activate flutter_launcher_icons
flutter_launcher_icons

Splash Screen

Update the native splash assets:

• Android: android/app/src/main/res/drawable/launch_background.xml
• iOS: ios/Runner/Assets.xcassets/LaunchImage.imageset/
• Or use the flutter_native_splash package for a code-driven approach

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/model/ 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.

Updating Lottie Animations

Replace or add .json files in assets/json/. Reference them via the generated Assets class in lib/config/util/assets.gen.dart (regenerated automatically by flutter_gen on next build).

Need help? Contact contact@6amtech.com or visit our website for support.