Architecture

Appmint Mobile is a single Flutter codebase (appmint_go/appmint_mobile, package appmint_mobile) built on Provider + ChangeNotifier, one HTTP client that carries the platform's two-token auth, and a thick services layer per module. There is no offline store and no navigation framework — screens are pushed with MaterialPageRoute, and the four bottom tabs live in an IndexedStack.

Boot sequence

lib/main.dart runs, in order:

1. Firebase, Android only. Firebase.initializeApp is guarded by Platform.isAndroid. iOS deliberately skips it: inbound-call wake-ups use PushKit/APNs through twilio_voice, and initializing Firebase without config throws [core/not-initialized]. A top-level _firebaseMessagingBackgroundHandler (@pragma('vm:entry-point')) exists only as a no-op safety net for Twilio's FCM data messages.

2. Client info. clientInfoService.initialize() snapshots device, OS, app version and locale once; the HTTP client attaches it to heartbeats, presence and chat connects.

3. Scanner. scannerService.ensureInitialized() wires the three scan inputs (camera, HID keyboard-wedge, BLE serial).

4. Environment. EnvironmentConfig.setEnvironment(kReleaseMode ? production : development). A debug build always talks to the development endpoint; there is no runtime switch. See Environment.

5. runApp(AppmintApp()).

Providers

AppmintApp is a MultiProvider with thirteen ChangeNotifierProviders, registered in this order:

AuthWrapper (also in main.dart) is a Consumer<AuthProvider>: initial and loading show a spinner, unauthenticated and error show LoginScreen, and an authenticated user gets HomeScreen after a post-frame call that sets the chat owner email and connects the chat socket.

Navigation

• Bottom tabs — lib/screens/home/home_screen.dart holds an IndexedStack of DashboardScreen, InboxScreen, CalendarScreen and MoreScreen. The bar is HaHoBottomNavigation (lib/widgets/haho_navigation.dart): Home, Inbox, a centre phone FAB that pushes PhoneScreen as a full-screen dialog, Calendar, More. A floating unread-chat pill sits top-right and jumps back to tab 0.
• App launcher — lib/config/home_apps.dart is the single source of truth. AppDescriptor(id, label, icon, color) entries are grouped into HomeAppGroups: businessmade (pos, tabs, floor, reservations, checkin, take_payment), crm (pipelines, tasks, contacts, leads, support, live_chat, sms), event (events, scan, info, stats, badge, tickets, schedule, people, manage, book) and system (devices). The tile-to-screen map lives in lib/screens/dashboard/dashboard_screen.dart. AppVisibilityProvider filters tiles and whole groups using the device-local home_hidden_groups / home_hidden_items keys.
• No drawer. The More tab is the settings hub. Several of its tiles are stubs today (Notifications, Preferences, Language, Dark Mode).

Networking

lib/services/http_client.dart (AppengineHttpClient) is the only HTTP path.

• Every request carries Authorization: Bearer <token> and a lowercase orgid header. The org id is also what the softphone reads to bind its Twilio identity user:<orgId>:<email>.
• A 401 triggers one refresh through onTokenRefresh, which AuthProvider wires to POST /profile/user/refresh; the original request is retried once. A failed refresh becomes a forced logout: storage is cleared, the navigator pops to the first route, and a six-second warning toast explains why.
• Tokens live in FlutterSecureStorage (access_token, refresh_token); the user record and settings live in SharedPreferences.

Two service styles sit on top of it:

Services layer

Theme

lib/config/haho_theme.dart is the live design system (HaHoColors, HaHoSpacing, HaHoRadius, HaHoTextStyles). AppTheme there aliases HaHoTheme, and darkTheme returns lightTheme — the More tab's Dark Mode tile has nothing behind it. A second, unused AppTheme in lib/config/theme.dart (indigo Material 3) is not imported by main.dart.

What is declared but not implemented

Reading pubspec.yaml or the root README.md gives a more generous picture than the code supports. Do not document or rely on these:

Related