ionic-planb-logistic-app-flutter/DEVELOPMENT.md

Development Guide - Plan B Logistics Flutter App

This guide covers building and running the Plan B Logistics Flutter app on Android devices (KM10) with local backend communication.

Prerequisites

• Flutter SDK installed and configured
• Android SDK installed (with platform-tools for adb)
• Android device (KM10) connected via USB with USB debugging enabled
• Backend API running on localhost (Mac)

Device Setup

1. Verify Device Connection

Check that your Android device is connected and recognized:

flutter devices

You should see output similar to:

KM10 (mobile) • 24117ad4 • android-arm64 • Android 13 (API 33)

Alternatively, use adb directly:

/Users/mathias/Library/Android/sdk/platform-tools/adb devices -l

2. Configure ADB Reverse Proxy

The app needs to communicate with your local backend API running on localhost:7182. Since the Android device cannot access your Mac's localhost directly, you need to set up a reverse proxy using adb.

Get Device Serial Number

First, identify your device's serial number:

/Users/mathias/Library/Android/sdk/platform-tools/adb devices

Example output:

24117ad4	device

Set Up Reverse Proxy

Forward the device's localhost:7182 to your Mac's localhost:7182:

/Users/mathias/Library/Android/sdk/platform-tools/adb -s 24117ad4 reverse tcp:7182 tcp:7182

Replace 24117ad4 with your actual device serial number.

Verify Reverse Proxy

Check that the reverse proxy is active:

/Users/mathias/Library/Android/sdk/platform-tools/adb -s 24117ad4 reverse --list

Expected output:

tcp:7182 tcp:7182

Test Backend Connectivity (Optional)

From the device shell, test if the backend is accessible:

/Users/mathias/Library/Android/sdk/platform-tools/adb -s 24117ad4 shell "curl -k https://localhost:7182/api/query/simpleDeliveryRouteQueryItems -X POST -H 'Content-Type: application/json' -d '{}' -m 5 2>&1 | head -10"

Building and Running

1. Install Dependencies

flutter pub get

2. Run on Connected Device

Run the app on the KM10 device in debug mode:

flutter run -d KM10

Or using the device serial number:

flutter run -d 24117ad4

3. Hot Reload and Restart

While the app is running:

• Hot Reload (r): Reload changed code without restarting
• Hot Restart (R): Restart the entire app
• Quit (q): Stop the app

4. Build Release APK

To build a release APK:

flutter build apk --release

The APK will be located at:

build/app/outputs/flutter-apk/app-release.apk

Development Workflow

Full Development Session

# 1. Check device connection
flutter devices

# 2. Set up ADB reverse proxy (do this once per device connection)
/Users/mathias/Library/Android/sdk/platform-tools/adb -s 24117ad4 reverse tcp:7182 tcp:7182

# 3. Verify reverse proxy
/Users/mathias/Library/Android/sdk/platform-tools/adb -s 24117ad4 reverse --list

# 4. Run the app
flutter run -d KM10

If Backend Connection Fails

If the app cannot connect to the backend API:

1. Verify backend is running on Mac:

   curl https://localhost:7182/api/query/simpleDeliveryRouteQueryItems \
     -X POST \
     -H 'Content-Type: application/json' \
     -d '{}'
   

2. Check ADB reverse proxy is active:

   /Users/mathias/Library/Android/sdk/platform-tools/adb -s 24117ad4 reverse --list
   

3. Re-establish reverse proxy if needed:

   /Users/mathias/Library/Android/sdk/platform-tools/adb -s 24117ad4 reverse --remove-all
   /Users/mathias/Library/Android/sdk/platform-tools/adb -s 24117ad4 reverse tcp:7182 tcp:7182
   

4. Check device logs for errors:

   /Users/mathias/Library/Android/sdk/platform-tools/adb -s 24117ad4 logcat -s flutter:I -d -t 100
   

API Configuration

The app is configured to use the following API endpoints:

• Query Base URL: https://localhost:7182/api/query
• Command Base URL: https://localhost:7182/api/command

These are configured in lib/api/openapi_config.dart.

Common Commands Reference

Device Management

# List all connected devices
flutter devices

# List devices with adb
/Users/mathias/Library/Android/sdk/platform-tools/adb devices -l

# Get device info
/Users/mathias/Library/Android/sdk/platform-tools/adb -s 24117ad4 shell getprop

ADB Reverse Proxy

# Set up reverse proxy for port 7182
/Users/mathias/Library/Android/sdk/platform-tools/adb -s <DEVICE_ID> reverse tcp:7182 tcp:7182

# List all reverse proxies
/Users/mathias/Library/Android/sdk/platform-tools/adb -s <DEVICE_ID> reverse --list

# Remove specific reverse proxy
/Users/mathias/Library/Android/sdk/platform-tools/adb -s <DEVICE_ID> reverse --remove tcp:7182

# Remove all reverse proxies
/Users/mathias/Library/Android/sdk/platform-tools/adb -s <DEVICE_ID> reverse --remove-all

Logging

# View Flutter logs (last 100 lines)
/Users/mathias/Library/Android/sdk/platform-tools/adb -s 24117ad4 logcat -s flutter:I -d -t 100

# View Flutter logs in real-time
/Users/mathias/Library/Android/sdk/platform-tools/adb -s 24117ad4 logcat -s flutter:I -v time

# View all logs (last 300 lines)
/Users/mathias/Library/Android/sdk/platform-tools/adb -s 24117ad4 logcat -d -t 300

Build Commands

# Debug build (default)
flutter build apk --debug

# Release build
flutter build apk --release

# Profile build (for performance testing)
flutter build apk --profile

# Install APK directly
flutter install -d KM10

Troubleshooting

Device Not Found

If flutter devices doesn't show your device:

1. Check USB debugging is enabled on the device
2. Check device is authorized (check device screen for prompt)
3. Restart adb server:

   /Users/mathias/Library/Android/sdk/platform-tools/adb kill-server
   /Users/mathias/Library/Android/sdk/platform-tools/adb start-server
   

App Crashes on Startup

1. Check logs:

   /Users/mathias/Library/Android/sdk/platform-tools/adb -s 24117ad4 logcat -d | grep -i error
   

2. Clear app data:

   /Users/mathias/Library/Android/sdk/platform-tools/adb -s 24117ad4 shell pm clear com.goutezplanb.planb_logistic
   

3. Uninstall and reinstall:

   /Users/mathias/Library/Android/sdk/platform-tools/adb -s 24117ad4 uninstall com.goutezplanb.planb_logistic
   flutter run -d KM10
   

Backend Connection Issues

1. Verify reverse proxy is active
2. Check backend API is running
3. Check SSL certificate issues (app uses https://localhost:7182)
4. Review network logs in the Flutter output

Additional Resources

• Flutter Documentation: https://docs.flutter.dev
• Android Debug Bridge (adb): https://developer.android.com/studio/command-line/adb
• Project-specific guidelines: See CLAUDE.md for code standards and architecture