A deliberately small source tree

The app is around 2,800 lines of Dart plus a focused Kotlin layer. lib/ is organized by technical layer; there are no feature folders because there is one feature.

sms_gateway/
├─ pubspec.yaml              dependencies, launcher icons, assets
├─ pubspec.lock
├─ analysis_options.yaml     flutter_lints
├─ assets/
│  └─ icons/                 app_icon.png, adaptive foreground, logo.svg
├─ lib/
│  ├─ main.dart              bootstrap, Firebase init, auth gate, routes
│  ├─ core/
│  │  ├─ gateway_config.dart compiled-in API base URL
│  │  └─ app_logger.dart     ring-buffer logger + payload redaction
│  ├─ providers/
│  │  └─ gateway_provider.dart  the whole device state machine (461 lines)
│  ├─ screens/
│  │  ├─ splash_screen.dart  neutral boot screen
│  │  ├─ login_screen.dart   admin sign-in form
│  │  └─ home_screen.dart    dashboard: status, queue, service, log
│  ├─ services/
│  │  ├─ api_client.dart     device API (Dio) + token storage
│  │  ├─ admin_session.dart  admin sign-in + device registration
│  │  ├─ device_bridge.dart  single MethodChannel to Kotlin
│  │  ├─ device_identity.dart SIM-accurate device name and id
│  │  └─ fcm_service.dart    Firebase wake listeners
│  ├─ theme/
│  │  └─ app_theme.dart      Material 3 dark theme
│  └─ widgets/               AppCard, PrimaryButton
└─ android/
   └─ app/src/main/kotlin/com/mono/sms_gateway/
      ├─ MainActivity.kt      Flutter entry, hosts the channel handler
      ├─ GatewayNative.kt     MethodChannel: send, SIM, service control
      ├─ GatewayService.kt    data-sync foreground service
      ├─ GatewaySync.kt       authenticated queue pass (native)
      ├─ GatewaySyncWorker.kt WorkManager wrapper for background passes
      ├─ GatewayMessagingService.kt  FCM entry, schedules native sync
      ├─ SmsReceiver.kt       manifest inbound-SMS receiver
      ├─ SmsResultReceiver.kt per-message send result callback
      ├─ BootReceiver.kt      re-arms after reboot / app update
      ├─ RestartReceiver.kt   restart when the app is swiped away
      └─ GatewayEvents.kt     shared event plumbing

Three screens, one job

The class count comes from public classes named *Screen in lib/screens/. Dashboard cards, pills, and dialogs are internal widgets of home_screen.dart, not additional screens.

Dashboard cards on the home screen

App-bar menu

The overflow menu exposes the three operator actions: Re-scan inbox (recovery pass for inbound SMS the broadcast receiver missed), Battery settings (deep-link into Android's battery-optimization screen — required on Xiaomi/Oppo/Vivo/Samsung), and Sign out (stops the service, forgets every stored credential, and returns to login).

Connection states

Toolchain and device requirements

Before the first run

• Android Studio with the SDK platforms for API 36/37, or a plain Flutter toolchain.
• A physical Android phone — emulators cannot send SMS over a SIM.
• The backend reachable from the phone's network, and an administrator account with the SMS Gateway permission.
• Your Firebase google-services.json dropped into android/app/ if you want push wake-ups.

Complete Installation & Deployment Guide

Follow this step-by-step operational guide to prepare an Android phone, compile the Flutter application with your backend endpoint, configure critical battery exemptions, and register the device as the active cellular SMS gateway for the MONO Marketplace.

1. Physical Phone Preparation & Cellular SIM Verification

   Insert your active SIM card into the Android phone. Before running any software, verify that the device is operating properly on the mobile network:

   • Disable Airplane mode and check that cellular signal bars are active with your carrier name displayed.
   • Open the phone's native Messages app and manually send a standard SMS to another number to confirm outbound delivery and active SMS balance.
   • Dual-SIM Devices: If the phone has two SIM slots, go to Settings → Network & Internet → SIMs and set your desired sending SIM as the Default SIM for SMS. Android's SmsManager will dispatch messages over this primary subscription.

2. Enable Developer Options & USB Debugging

   To install and debug the application from your development workstation, enable developer access on the phone:

   • Open Android Settings → About Phone.
   • Locate Build Number and tap it repeatedly 7 times until you see the prompt: "You are now a developer!"
   • Go back to Settings → System → Developer Options (or Additional Settings on Xiaomi/Oppo).
   • Enable USB Debugging. On Xiaomi (MIUI/HyperOS) devices, also enable Install via USB and USB debugging (Security settings).
   • Connect the phone to your computer with a USB cable. On the phone screen, check "Always allow from this computer" and tap Allow.
   • Verify device detection in your workstation terminal:
   Terminal / ADB checkCopy

   adb devices
   # Output should list your device attached:
   # List of devices attached
   # 84B01248000183    device

3. Disable Android Battery Optimization (Doze Mode Whitelist)

   CRITICAL REQUIREMENT: Android aggressive power management will freeze background workers and kill foreground services if battery optimization is active. You must exempt MonoSMS from battery restrictions so it can continuously monitor incoming SMS and wake up for queue passes.

   Xiaomi / Redmi / POCO (MIUI & HyperOS)

   1. Open Settings → Apps → Manage Apps → MonoSMS.
   2. Tap Autostart → Toggle ON.
   3. Tap Battery Saver → Select No restrictions.
   4. Open Recent Apps → Long press MonoSMS card → Tap the Lock icon.

   Samsung Galaxy (One UI)

   1. Open Settings → Apps → MonoSMS → Battery.
   2. Change selection from Optimized to Unrestricted.
   3. Go to Settings → Battery & device care → Battery → Background usage limits → Add MonoSMS to Never sleeping apps.

   Oppo / Realme / OnePlus (ColorOS / OxygenOS)

   1. Open App Info → Battery Usage.
   2. Enable Allow background activity and Allow auto-launch.
   3. Pin the app in the recent tasks overview.

   In-App Shortcut

   The MonoSMS dashboard provides a direct deep link into the system battery optimization screen via the Battery settings menu item in the top overflow menu.

4. Clone Repository & Configure Backend Endpoint

   Clone or navigate to the sms_gateway project directory and install dependencies:

   Workspace setupCopy

   cd /path/to/mono/sms_gateway
   flutter pub get

   Specify the target marketplace API endpoint using the compiled constant GATEWAY_API_URL:

   • Via Build Flag: Pass --dart-define=GATEWAY_API_URL=https://your-domain.com/api/v1 at runtime or compilation.
   • Via Source File: Alternatively, edit lib/core/gateway_config.dart directly to change the fallback default URL:
   lib/core/gateway_config.dartCopy

   class GatewayApiConfig {
     static const String baseUrl = String.fromEnvironment(
       'GATEWAY_API_URL',
       defaultValue: 'https://your-domain.com/api/v1', // <-- Set your backend URL here
     );
   }

   Local Network / LAN Testing: When deploying or testing against your backend server (e.g. https://example.com/api/v1), the Android Manifest already includes android:usesCleartextTraffic="true", allowing unencrypted HTTP connections over Wi-Fi without SSL handshakes.

5. Set Up Firebase Cloud Messaging (FCM) Wake Channel (Optional but Recommended)

   FCM provides instantaneous wake signals to the phone whenever the marketplace puts a new SMS into the queue. The payload carries only a wake trigger (type: sms_queue_available); the message content and recipient are pulled securely from the database queue.

   1. Go to Firebase Console and open or create your project.
   2. Add an Android App with package name com.mono.sms_gateway.
   3. Download google-services.json and place it inside sms_gateway/android/app/google-services.json.
   4. In your marketplace backend admin settings (Admin → Settings → SMS Settings), ensure your Firebase Server Key / Credentials are configured.

   Works Without Firebase: If you do not configure Firebase, MonoSMS automatically runs its built-in 15-minute fallback poll and the server-side scheduled recovery worker (sms-gateway:recover), so SMS processing continues without push notifications.

6. Build and Install the Application

   Deploy MonoSMS directly onto the connected Android device:

   Development debug runCopy

   # Run directly on the attached phone
   flutter run --dart-define=GATEWAY_API_URL=https://your-domain.com/api/v1

   To compile a standalone Release APK for production deployment:

   Release APK buildCopy

   # Build standalone release APK
   flutter build apk --release --dart-define=GATEWAY_API_URL=https://your-domain.com/api/v1
   
   # Install the built APK onto the phone via ADB
   adb install -r build/app/outputs/flutter-apk/app-release.apk

   You can also copy the resulting app-release.apk to phone storage via USB cable or download it from your server browser, then tap to install.

7. Grant Android Telephony & Notification Permissions

   When the app opens for the first time, Android will prompt for necessary telephony and service permissions:

   Permission Dialog	Setting	Operational Purpose
   Send and view SMS messages?	Allow	Enables SmsManager to transmit outgoing queue messages over the cellular SIM.
   Make and manage phone calls?	Allow	Enables READ_PHONE_STATE to monitor carrier name, SIM status, and signal strength.
   Send notifications? (Android 13+)	Allow	Keeps the ongoing foreground service notification visible in the status bar.

   If any permission was accidentally dismissed, open Settings → Apps → MonoSMS → Permissions and ensure both SMS and Phone are set to Allowed.

8. Admin Sign-In & Device Pairing Handshake

   Upon launch, the application's Auth Gate detects that no device token is stored and displays the Sign In screen:

   • Enter your marketplace Admin Email and Password (the user must have the sms.gateway.manage permission).
   • The hardware identity (Manufacturer and Model, e.g. Samsung Galaxy S22) is automatically derived from the device.
   • Tap Sign In & Register Device.

   What Happens Behind the Scenes:

   Pairing authentication sequenceCopy

   1. Phone → POST /admin/auth/login (email, password, deviceName, deviceId)
   2. Backend validates admin credentials & sms.gateway.manage permission
   3. Phone → POST /admin/auth/register-device (bearer admin token)
   4. Backend creates SmsGatewayDevice record and issues a scoped deviceToken
   5. Phone stores deviceToken in encrypted hardware storage (FlutterSecureStorage)
   6. Phone discards admin password and session from active memory
   7. Dashboard status immediately updates to ONLINE with green pulse indicator

9. Verify in Admin Panel & Send a Live Test SMS

   Confirm that the phone is actively connected and test delivery through your carrier SIM:

   1. In your web browser, navigate to the Marketplace Admin Panel → Admin → SMS Gateway.
   2. Verify that your phone appears in the devices list with its correct device name, carrier, battery percentage, and a live green Connected indicator.
   3. Ensure the device status toggle is set to Active.
   4. Navigate to Admin → Settings → SMS Settings.
   5. Under SMS Provider, select Self-Hosted Gateway and save.
   6. Locate the Send Test SMS card, enter your personal mobile phone number, type a message (e.g. "Hello from Mono SMS Gateway!"), and click Send Test SMS.
   7. Within seconds, watch the phone: the ongoing foreground service will receive the wake signal, claim the message, send it through the SIM card, and report sent back to the server.

Direct dependencies, exactly as declared

Every dependency is pinned in pubspec.yaml; pubspec.lock freezes the resolved versions. The list is intentionally short.

One compile-time constant, nothing else

There is no settings screen for the server and no .env file. The base URL is compiled into the binary:

lib/core/gateway_config.dart
──────────────────────────────
static const String baseUrl = String.fromEnvironment(
  'GATEWAY_API_URL',
  defaultValue: 'https://monomarket.site/api/v1',
);

Theme & Brand Customization Guide

The MonoSMS gateway interface is built on Flutter's Material 3 styling engine. All colors, surfaces, borders, and component themes are centralized in lib/theme/app_theme.dart. Use this guide to rebrand the app, customize the color palette, switch between light and dark themes, update the launcher icon, and change application branding.

Theme Architecture Overview

The styling system separates color tokens from widget styling. AppColors defines the raw color constants, and buildAppTheme() maps them into Flutter's ThemeData:

class AppColors {
  static const primary = Color(0xFF111111);     // Primary brand accent & button fills
  static const accent = Color(0xFF059669);      // Connection state & active switches (Emerald)
  static const background = Color(0xFFF7F7F8);  // Scaffold background
  static const surface = Color(0xFFFFFFFF);     // Card backgrounds, dialogs, inputs
  static const surfaceAlt = Color(0xFFF4F4F5);  // Subtle secondary containers
  static const border = Color(0xFFE4E4E7);      // Card borders, input outlines, dividers
  static const textDark = Color(0xFF18181B);    // Headings, primary text
  static const textMedium = Color(0xFF52525B);  // Body text, secondary labels
  static const textLight = Color(0xFFA1A1AA);   // Placeholder hints, faint timestamps
  static const danger = Color(0xFFDC2626);      // Errors, disconnects, failures
  static const warning = Color(0xFFB45309);     // Retry notices, battery warnings
}

Ready-to-Use Theme Presets

To switch themes, replace the constants in AppColors in lib/theme/app_theme.dart with any of the curated presets below:

class AppColors {
  static const primary = Color(0xFF18284D);    // MONO Deep Navy
  static const accent = Color(0xFF059669);     // Emerald green
  static const background = Color(0xFFF8FAFC); // Clean light slate
  static const surface = Color(0xFFFFFFFF);    // Pure white cards
  static const surfaceAlt = Color(0xFFF1F5F9); // Subtle slate
  static const border = Color(0xFFE2E8F0);     // Clean hairline borders
  static const textDark = Color(0xFF0F172A);   // Deep slate heading
  static const textMedium = Color(0xFF334155); // Slate body
  static const textLight = Color(0xFF64748B);  // Slate muted
  static const danger = Color(0xFFDC2626);
  static const warning = Color(0xFFD97706);
}

class AppColors {
  static const primary = Color(0xFF38BDF8);    // Vivid sky blue
  static const accent = Color(0xFF10B981);     // Neon emerald
  static const background = Color(0xFF090D16); // Deep AMOLED night
  static const surface = Color(0xFF111827);    // Dark slate cards
  static const surfaceAlt = Color(0xFF1F2937); // Raised container
  static const border = Color(0xFF374151);     // Dark hairline border
  static const textDark = Color(0xFFF9FAFB);   // High-contrast white
  static const textMedium = Color(0xFF9CA3AF); // Soft gray body
  static const textLight = Color(0xFF6B7280);  // Dark muted
  static const danger = Color(0xFFEF4444);
  static const warning = Color(0xFFF59E0B);
}

Customizing Component Styles in buildAppTheme()

You can adjust border curves, typography, input fields, and button shapes by modifying the ThemeData object in lib/theme/app_theme.dart:

Updating the App Launcher Icon

The application icon is automatically generated for Android adaptive launcher icons using flutter_launcher_icons:

1. Prepare your new square icon graphic (recommended dimensions: 1024 × 1024 px PNG).
2. Save the main icon to sms_gateway/assets/icons/app_icon.png.
3. Optionally, save the transparent foreground layer to sms_gateway/assets/icons/app_icon_foreground.png.
4. Review the configuration in pubspec.yaml:

flutter_launcher_icons:
  android: "ic_launcher"
  ios: false
  image_path: "assets/icons/app_icon.png"
  adaptive_icon_background: "#18284D" # Set your brand background color
  adaptive_icon_foreground: "assets/icons/app_icon_foreground.png"

Run the generator command in your terminal to build all Android mipmap resolutions:

dart run flutter_launcher_icons

Changing App Name & Launcher Label

To rebrand the name shown under the app icon on the phone home screen and in Android settings:

• Android Launcher Label: Open sms_gateway/android/app/src/main/AndroidManifest.xml and update:
  android/app/src/main/AndroidManifest.xmlCopy

  <application
      android:label="YourBrand SMS"
      android:icon="@mipmap/ic_launcher">

• Flutter App Window Title: Open sms_gateway/lib/main.dart and update:
  lib/main.dartCopy

  return MaterialApp(
    title: 'YourBrand SMS', // <-- Change from 'MonoSMS'
    debugShowCheckedModeBanner: false,
    theme: buildAppTheme(),
    ...
  );

Build commands and release notes

# debug run on a connected phone
flutter run --dart-define=GATEWAY_API_URL=https://your-store.com/api/v1

# release APK (the gateway ships as a sideloaded APK, not Play Store)
flutter build apk --release --dart-define=GATEWAY_API_URL=https://your-store.com/api/v1

# regenerate launcher icons after changing assets/icons/
dart run flutter_launcher_icons

Pairing: from admin credentials to a device token

Paring is the only privileged moment in the device's life. It uses the administrator's account once, then immediately narrows down to a device-scoped credential.

Device identity is automatic

DeviceIdentity derives both values from the hardware: on Android the id is <androidId>-<model> and the name is a de-duplicated <manufacturer> <model> (so stock devices read “Pixel 8”, not “Google Pixel 8”). On iOS it uses identifierForVendor. If identity is unavailable the app still works, reporting unknown-device / “SMS Gateway”.

Signing out

signOutCleanup() cancels both timers, disposes FCM listeners, stops the foreground service, deletes the device token (secure storage) and native credentials, and returns the app to notConfigured. The backend-side device row survives so the admin can revoke or re-issue its token from the panel.

The device API surface

After pairing, every call carries the device token as a bearer token, enforced by the backend's AuthenticateSmsGateway middleware — an admin token or customer token is rejected on these routes. Responses use the platform envelope { success, data, error }; GatewayResult.fromBody parses exactly that shape.

Client behavior details

• Token handling: the token is read from secure storage once at startup; init() never re-reads over a freshly signed-in token.
• Error surfacing: Dio errors are translated into human messages — 401 becomes “The device token was rejected. Sign in again.”, a missing connection becomes “Could not reach the server.”
• Log redaction: the request interceptor logs method and path, and passes bodies through AppLogger.redact, which masks sensitive keys with *** — a queued message can carry a one-time code.
• Failure isolation: every call returns a GatewayResult rather than throwing; UI state never depends on exceptions.

The send pipeline: queue is the source of truth

FCM pushes are wake signals only — their data never contains an SMS body or recipient. Delivery is pulled, always, from the queue:

Backend                    Device (MonoSMS)                Android
────────────────────────   ─────────────────────────────   ──────────────
Order placed / OTP due
  └─ sms_messages row (pending)
      └─ FCM push {type: sms_queue_available}  ──▶  wake
                                                  ├─ foreground: DeviceBridge.runNativeSync()
                                                  └─ background: GatewayMessagingService → WorkManager
POST /sms-gateway/sms/claim  ◀──────────────   authenticated queue pass
  reclaim claims older than 5 min
  lockForUpdate pending rows (≤ limit)
  mark processing, stamp claimed_at
messages[{id, to, body, kind}] ──────────────▶  for each: SmsManager send
                                                     │  SmsResultReceiver
POST /sms-gateway/sms/{id}/report ◀──────────  sent  |  failed + error
  status = sent / failed

Triggers, in order of importance

Queue guarantees

• Single claimer: the claim transaction locks rows and stamps claimed_at, so two gateway devices can never send the same message.
• No silent loss: a claim that never reports back is returned to pending after 5 minutes (CLAIM_TIMEOUT_MINUTES) and re-offered.
• Bounded retries: each row carries attempts and max_attempts; a message that exhausts them is parked as failed with “Retry limit reached.” instead of looping forever.
• Honest accounting: the send result comes from Android's SmsResultReceiver, not from the absence of an exception; failures report the carrier's reason string.

Timers while the app is alive

Once paired, the provider runs a 5-minute heartbeat (which also re-uploads the FCM token after rotation) and the 15-minute fallback poll. Both are cancelled on sign-out. The foreground service takes over durability when the app is backgrounded or swiped away.

Inbound SMS: capture, forward, deduplicate

Inbound messages (customer replies, carrier notices) flow the opposite way — from Android into the backend's sms_inbound_messages table.

Android permissions and platform components

The Kotlin layer exists to keep the gateway alive and to dial the radio. Everything is registered in the manifest so it works without the UI.

Manifest components

Battery optimization

Android may freeze the gateway on aggressive OEM skins. The dashboard reads the exemption state and offers a one-tap deep link into the battery settings screen (openBatterySettings). Exempting the app is expected procedure on Xiaomi, Oppo, Vivo, and Samsung.

Firebase is a doorbell, not a courier

Push payloads carry a single datum: type: sms_queue_available. No SMS body, no recipient, ever. If Firebase is unavailable the app still works — the fallback poll and backend recovery nudge cover the difference.

Setting up your own Firebase project

1. Create a Firebase project and add an Android app with package com.mono.sms_gateway.
2. Download google-services.json into android/app/.
3. Enable Cloud Messaging (no APNs key needed unless you also ship iOS).
4. Build and pair — the first heartbeat uploads the FCM token, and the admin panel shows the device as Connected.

What the administrator sees on the other side

The marketplace admin panel has a dedicated Admin → SMS Gateway page (guarded by the sms.gateway.manage permission) that manages the devices this app creates.

Scheduled hygiene on the server

The sms-gateway:recover command runs on the managed scheduler. Each pass reclaims claims older than five minutes, parks retry-exhausted messages as failed, and wakes the active device for up to twenty still-pending messages. Combined with the device's own timers, no message depends on a single lucky push.

Security and privacy posture

Extending the gateway safely

The architecture has one rule that keeps it safe to extend: the backend decides, the device dials. New features should preserve that split.

Where things live

Known limitations, checked against source

Troubleshooting quick reference

Carrier SMS charges apply to every message this app sends. Keep the gateway phone charged, topped up, and exempt from battery optimization, and it will quietly drain the queue.