Flutter App Initial Local Setup

Environment Configuration

Per-environment configuration is managed via .env files in assets/env/.

Dev Environment (`.env.dev`)

For local development, configure assets/env/.env.dev.

Important: For Android Emulator, use localhost combined with adb reverse. This ensures the app behaves exactly like the host environment, avoiding redirect mismatch issues with Supabase Auth.

Run the following command to forward ports:

adb reverse tcp:3000 tcp:3000
adb reverse tcp:54321 tcp:54321

You can skip this step if you are running the app via VS Code’s "Flutter: Dev (Local)" launch configuration, as it automatically runs these commands for you.

assets/env/.env.dev

# Supabase Configuration
# Use localhost (requires adb reverse)
SUPABASE_URL=http://localhost:54321
SUPABASE_ANON_KEY=<your-local-anon-key>

# Stripe
STRIPE_PUBLISHABLE_KEY=<your-stripe-publishable-key>

# Web Dashboard URL
# Used by "Manage Subscription" button to open the web dashboard
# Use localhost (requires adb reverse)
WEB_DASHBOARD_URL=http://localhost:3000/dashboard

Running the App

After the Android product flavor split, every flutter run and flutter build invocation must pass both --flavor <env> and -t lib/main_<env>.dart.

flutter run --flavor dev -t lib/main_dev.dart

Loads .env.dev and runs against the peppercheck-dev Firebase project.

First-time setup

Download your Firebase config files before the first build:

./scripts/setup/register-firebase-apps.sh dev

This writes peppercheck_flutter/android/app/src/dev/google-services.json and peppercheck_flutter/ios/Runner/Firebase/GoogleService-Info-Dev.plist (both gitignored). Operators with access to staging or production secrets may also run the script with staging or production; otherwise those flavors are built only in CI.

Building APKs / AABs

flutter build apk --debug --flavor dev -t lib/main_dev.dart
flutter build apk --release --flavor staging -t lib/main_staging.dart
flutter build appbundle --release --flavor production -t lib/main_production.dart

The three flavor APKs install side-by-side on the same device — packages are dev.cloveclove.peppercheck.dev, dev.cloveclove.peppercheck.staging, and dev.cloveclove.peppercheck respectively.