AI Trip Planner is a production-ready Flutter app that helps users plan and manage trips with an AI-assisted experience. It integrates Firebase (Auth, Firestore, Storage, Messaging), Stripe payments, Google Maps, voice input (speech_to_text), TTS, biometrics, secure storage, preferences, and localization.

• Project Overview
• Technologies Used
• Cloud Services
• Prerequisites
• Local Environment Setup
• Android Emulator Setup
• iOS Simulator Setup (macOS)
• Firebase Setup
• Running the App
• Notifications (FCM + Local)
• Payments (Stripe)
• Useful Commands
• Repository Structure
• Security & Secrets
• Documentation

• Cross-platform Flutter app: Android, iOS, Web, Desktop
• Rich features: authentication, profiles, trip planning, maps, voice, payments, notifications, theming, i18n

• Flutter 3 (Dart SDK ^3.8)
• State: provider
• Localization: easy_localization
• Storage & prefs: flutter_secure_storage, shared_preferences
• Biometrics: local_auth
• Voice: speech_to_text, flutter_tts
• Maps: google_maps_flutter
• Notifications: firebase_messaging, flutter_local_notifications
• Payments: flutter_stripe

• Firebase
  • Auth (email/password, Google Sign-In)
  • Firestore (profiles, payments history, saved trips)
  • Storage (profile images)
  • Cloud Messaging (FCM)
  • Cloud Functions (Node.js/Express) for Stripe API + webhooks
• Stripe
  • PaymentIntents
  • Saved payment methods
  • Webhooks

• Flutter SDK installed and in PATH
• Android Studio with Android SDK / Platform Tools
• For iOS (macOS): Xcode + CocoaPods
• GitHub CLI (optional) if contributing

1. Install dependencies

flutter pub get

2. Add Firebase configuration files (not committed)

• Android: android/app/google-services.json
• iOS: ios/Runner/GoogleService-Info.plist

3. (Optional) Configure Google Maps API key per platform

• Follow Google Maps Flutter setup docs to add API keys in Android/iOS configuration

# List Android emulators
flutter emulators

# Launch an emulator (replace with your AVD ID)
flutter emulators --launch emulator-5554

# Verify connected devices
flutter devices

# List simulators
xcrun simctl list devices

# Open Simulator app
open -a Simulator

# Run to a specific simulator
flutter run -d <simulator-id>

• Ensure lib/firebase_options.dart exists (via FlutterFire CLI) or initialize in FirebaseService
• Android: confirm android/app/google-services.json
• iOS: confirm ios/Runner/GoogleService-Info.plist
• Enable FCM in Firebase Console

# Get dependencies
flutter pub get

# Run on Android emulator
flutter run -d emulator-5554

# List devices and run
flutter devices
flutter run -d <device-id>

• On first launch, grant notification permissions (Android 13+ / iOS)
• Foreground: FCM messages show a local notification
• Background/terminated: tapping the push navigates by data.route (and optional data.args)

Example HTTP v1 test payload:

{
  "message": {
    "token": "DEVICE_FCM_TOKEN",
    "notification": { "title": "Trip Reminder", "body": "Your event starts soon" },
    "android": { "priority": "HIGH" },
    "data": { "route": "/new-event", "args": "{\"id\":\"123\"}" }
  }
}

• Client uses flutter_stripe
• Backend Cloud Functions exposes POST /create-payment-intent, GET /payment-methods and a webhook /stripeWebhook
• Flow: create PaymentIntent → confirm on client → webhook records results in Firestore

# Analyze & format
flutter analyze
flutter format .

# Build Android APK
flutter build apk --release

# Clean & reset deps
flutter clean && flutter pub get

• lib/ — UI screens, services, background handler
• functions/ — Cloud Functions (Stripe API + webhook)
• android/, ios/, web/, macos/, linux/, windows/ — platform runners
• assets/ — images and translations

• .gitignore excludes Firebase configs, keystores, env files, signing info, service account JSONs, runtime configs, and common key formats
• Never commit credentials; use local files and CI/CD secrets (GitHub Actions, etc.)

• For a deeper technical dive, see aitripplanner-docs.md (architecture, services, flows, payload conventions).