02 / Architecture

A layered Flutter customer app

Use the existing boundaries when extending the app. Providers own mutable state; repositories make API calls; services wrap shared infrastructure; screens compose workflows; widgets keep presentation reusable.

mono_customer/
├─ lib/main.dart              app bootstrap + 22 providers
├─ lib/core/                  cache, logger, translations, push, auth, legal
├─ lib/models/                address, cart, chat, checkout, home, product, user...
├─ lib/providers/             20 stateful feature providers
├─ lib/repositories/          26 API/data repositories
├─ lib/services/              API, endpoint registry, Ably chat, checkout links
├─ lib/screens/               47 public *Screen classes
├─ lib/theme/                 app colors and theme
├─ lib/widgets/               63 shared widgets
├─ test/                      22 test files
├─ android/ · ios/ · web/ · linux/ · macos/ · windows/
└─ gui-test-screenshots/      desktop/web folders, not mobile build targets

03 / Product surface

Customer screens and real workflows

The screen layer has 47 public *Screen files under lib/screens/. The wider project has six additional screen-class declarations under lib/widgets/—five checkout result states and HostedWalletTopupWebViewScreen—for 53 project-wide declarations. Internal widgets, cards, tabs, dialogs, and controllers are not additional public screen files. The main shell is persistent and state-preserving.

Open capture ↗

Open capture ↗

Open capture ↗

Open capture ↗

Open capture ↗

Open capture ↗

04 / Start here

Requirements and installation

Run this as a mobile Flutter project. Desktop and web folders exist in the repository, but seven source files import dart:io, so web is not a verified customer-mobile target. The local toolchain is upgraded to Flutter 3.47.7 and Dart 3.13.5.

flutter pub get
flutter run

05 / Packages

Direct dependencies from the customer lockfile

pubspec.lock contains 198 locked packages: 30 direct main, 3 direct dev/SDK, and 165 transitive. All major core packages have been verified and upgraded for Flutter 3.47.7 & Dart 3.13.5.

Dev / SDK: flutter, flutter_localizations, flutter_test, flutter_lints ^6.0.0, and flutter_launcher_icons ^0.14.4. No payment SDK, maps/geolocation, Firebase Analytics, native splash package, support-ticket package, rich-text editor, or commercial UI suite is declared.

06 / Networking

Dio, API client configuration, and unprefixed endpoints

The active compiled default is https://example.com/api/v1, a private LAN cleartext development URL—not a production URL. ApiClient applies a 15-second connect timeout, 60-second receive timeout, JSON headers, Bearer token, X-Locale, Accept-Language, and relative media URL resolution.

ApiClient → api_endpoints.dart → repositories → providers

07 / Session

Environment, token migration, and auth boundaries

Secure storage reads api_base_url when present, but the app has no setter or settings UI for it. Fresh installs use the compiled default URL (https://example.com/api/v1). Secure token storage uses api_token; a legacy auth_token value is migrated once from SharedPreferences. There is no refresh-token implementation.

08 / Presentation

Customer identity, theme, and localization

The customer mark is a black/white shopping-bag “M” with a yellow dot, distinct from other app identities. Splash copy is MONO., Everything You Need, One Store, Preparing your store…, and Powered by Mono.

CUSTOMER BRAND ASSET Use the customer mark consistently.

Copy from mono_app/assets/logo.png and assets/icons/. The bundled wishlist.svg exists but is not directly referenced by current Dart code.

09 / Platform services

Android-only FCM startup, chat-only Ably

Unlike a lazy-after-login design, customer main() initializes Firebase before runApp. Runtime push initialization is Android-only: !kIsWeb && defaultTargetPlatform == TargetPlatform.android.

Set up your own Firebase project, step by step

The package ships with a working google-services.json so the app runs immediately, but it points at a shared Firebase project. Create your own before you publish — it takes about ten minutes and needs only a free Google account.

1. Create the project

   Open console.firebase.google.com and click Add project. Name it something like mono-customer and disable Google Analytics unless you want it. The project finishes creating once you confirm the analytics choice.

2. Add the Android app

   On the project overview click the Android icon. The package name must match your applicationId character for character, so enter com.mono.customer.app until you rename it. Add a nickname and download google-services.json.

3. Place the config file

   Copy it to android/app/google-services.json, replacing the bundled one. Both the filename and the folder are required — a wrong path still builds but throws DefaultFirebaseApp is not initialized at runtime.

4. Enable Cloud Messaging

   In the left sidebar open Build → Cloud Messaging. The Send test message button confirms delivery works. No other FCM setup is needed.

5. Leave the channel to the app

   The app creates high_importance_channel (“Messages and Updates”) at runtime. Do not create a matching channel in the console; the app owns it and a duplicate is ignored.

6. Rebuild, do not hot reload

   Changing the config file needs a full rebuild. Stop the app and run flutter run -d <device> again, adding flutter clean first if the old configuration looks cached.

10 / iOS

iOS 13.0 exists; Apple setup does not

The iOS target is present with deployment target 13.0, Swift 5.0, bundle ID com.mono.customer.app, and URL scheme mono. The current project is not fully configured as a production iOS client.

11 / Build loop

Build and run from the customer project

Start with a reachable API, an authenticated or guest-capable session, and the correct platform configuration. A clean clone may need Gradle wrapper setup because wrapper artifacts are locally present but ignored/not tracked.

Change the application ID before you publish

Both platforms ship with the identifier com.mono.customer.app, a real reverse-domain identifier that builds fine. Google Play and the App Store each require the identifier to belong to the account publishing the app, so replace it with your own before your first upload — for example com.yourcompany.mono.customer.

Renaming the Android package also means moving the Kotlin source to match: android/app/src/main/kotlin/com/mono/customer/app/MainActivity.kt becomes android/app/src/main/kotlin/com/yourcompany/mono/customer/app/MainActivity.kt, with its package line updated too. Skipping this fails the build with a Namespace error pointing at the manifest.

Android SDK levels are pinned deliberately

android/app/build.gradle.kts sets compileSdk = 37 and pins targetSdk = 36 as an explicit integer rather than flutter.targetSdkVersion, which resolves to 35 on Flutter 3.29 and newer — below the current Google Play submission requirement. The explicit number keeps uploads accepted as you upgrade Flutter. minSdk stays at maxOf(flutter.minSdkVersion, 23) because Firebase Messaging and flutter_local_notifications need a modern minimum.

12 / Readiness

What is ready, and what is not

13 / Developer path

Extend the app without breaking its architecture

Screen → Provider → Repository → ApiClient → customer endpoint
                         ↘ models / services / widgets

Worked example: add a reviews feature module

Here is the five-step shape above applied to one concrete feature, so you can copy it rather than infer it. The example adds a product-reviews view backed by GET /products/{id}/reviews.

1. Model — lib/models/product_review.dart

   A data class with fromJson that tolerates a missing optional field such as reviewer_name, so one sparse API response cannot break the whole list.

2. Endpoint — lib/services/api_endpoints.dart

   Add a static path builder alongside the existing product routes. Keep URLs out of screens and repositories.

3. Repository — lib/repositories/review_repository.dart

   Takes an ApiClient, fetches the list, maps each item into the model, and returns typed data or throws. No widget imports.

4. Provider — lib/providers/review_provider.dart

   A ChangeNotifier with reviews, isLoading, and error, exposing load(productId). Register it in the MultiProvider list in lib/main.dart only if it should survive tab changes; otherwise create it in the owning screen.

5. Screen — lib/screens/product/product_reviews_screen.dart

   A *Screen class that watches the provider and renders loading, empty, error, and populated states, reusing existing cards from lib/widgets/. Reach it from the existing product screen with Navigator.push — do not add a sixth bottom tab for it.

lib/
├─ models/product_review.dart               ← new
├─ services/api_endpoints.dart              ← add reviews path
├─ repositories/review_repository.dart      ← new
├─ providers/review_provider.dart           ← new
├─ screens/product/product_reviews_screen.dart  ← new
└─ widgets/review_tile.dart                 ← new, if reused

14 / Support

Support and release checklist

Help & Support is a server-content surface: it renders support cards, FAQs, contact channels and a contact form. About renders server content; Legal renders API-managed privacy, terms and slugs. These are client presentation flows, not proof that the backend is configured or available.