01 - Getting Started

Everything you need to clone the repo, install dependencies, and run the app locally for the first time.

Prerequisites

Verify Flutter is installed:

# Windows
C:\flutter\bin\flutter doctor

# Expected output includes:
# [✓] Flutter (Channel stable, 3.x.x)
# [✓] Chrome - develop for the web
# [✓] Android toolchain (if you want Android builds)

Step 1 - Clone the Repo

git clone <repo-url> D:\MO_Project\ekyc
cd D:\MO_Project\ekyc\flutter_app

Step 2 - Install Dependencies

C:\flutter\bin\flutter pub get

This downloads all packages listed in pubspec.yaml: http, shared_preferences, lottie, flutter_svg, google_fonts, razorpay_flutter, webview_flutter, image_picker, and more.

Step 3 - Start the Backend

The Flutter app talks to the .NET 8 backend. You must start the backend first, or the app will fail at Stage 0 (session init).

cd D:\MO_Project\ekyc\backend\src\MO.Ekyc.Api
dotnet run

# Listens on http://localhost:5000
# Swagger: http://localhost:5000/swagger
# Hangfire: http://localhost:5000/hangfire

Step 4 - Run the Flutter App on Web

Web is the fastest way to iterate. No emulator, no plugin issues.

cd D:\MO_Project\ekyc\flutter_app
C:\flutter\bin\flutter run -d chrome --web-port 8080

The app opens at http://localhost:8080. You should see Stage 0 (arrival) briefly, then Stage 1 (registration).

Step 5 - Environment Flag

The app reads an ENV flag at build time to select the backend URL. Default is dev.

static const _env = String.fromEnvironment('ENV', defaultValue: 'dev');

static String get baseUrl {
  switch (_env) {
    case 'prod': return 'https://ekyc.motilaloswal.com';
    case 'uat':  return 'https://ekycuat.motilaloswaluat.com';
    default:    return 'http://localhost:5000';
  }
}

Running on Android

# List available devices
C:\flutter\bin\flutter devices

# Run on emulator/device
C:\flutter\bin\flutter run

# Build release APK
C:\flutter\bin\flutter build apk --release --dart-define=ENV=prod

# Build App Bundle for Play Store
C:\flutter\bin\flutter build appbundle --release --dart-define=ENV=prod

Running on iOS (macOS only)

# Install CocoaPods dependencies first
cd ios
pod install
cd ..

# Run on simulator
flutter run -d ios

# Build IPA for TestFlight
flutter build ipa --release --dart-define=ENV=prod

Troubleshooting

`flutter pub get` fails

• Check internet connection
• Clear cache: flutter clean && flutter pub get
• Delete pubspec.lock and retry

App shows "No internet connection" at Stage 0

• Backend is not running - start it with dotnet run
• Backend URL is wrong - check ApiConfig.baseUrl
• CORS blocked - check backend/src/MO.Ekyc.Api/appsettings.json Cors.AllowedOrigins

Port 8080 already in use

• Use a different port: flutter run -d chrome --web-port 8081
• Or kill the existing process: netstat -ano | findstr :8080 then taskkill /PID <pid> /F

Stuck at Stage 0 loading spinner

See 10 - Debugging for a full checklist.