Repository and runtime

• Local reference reviewed: ips-lacpass-app.
• Required tooling: Flutter SDK >= 3.32.1, Dart SDK >= 3.8.1, Android Studio or Xcode, and a device or emulator.
• For Android, Java 17 is required.
• Use flutter doctor before setup to confirm the local environment is ready.

flutter doctor
cp .env.sample .env
flutter pub get
flutter gen-l10n
flutter run

Mobile app environment checklist

• API_ENDPOINT points to the IPS Lacpass backend. For Android emulator local backend access, use http://10.0.2.2:9081.
• KEYCLOAK_ENDPOINT points to Keycloak. For Android emulator local Keycloak access, use http://10.0.2.2:9083.
• KEYCLOAK_REALM, KEYCLOAK_CLIENT_ID, and KEYCLOAK_REFRESH_TOKEN_KEY must match the backend Keycloak setup.
• USE_HTTP=1 allows non-HTTPS endpoints for local/domainless testing. Do not use HTTP in production.
• DEBUG_MODE=1 enables backend request inspection in the app.
• IPS_EXP_DAYS controls how long fetched IPS bundles remain in device storage; VHL_EXPIRATION_DAYS controls generated QR expiry.
• SHOW_WALLET=1 enables wallet UI; USE_MULTIPLE_NODES=1 enables multiple-node behavior when configured.

Participant-facing features to verify

• Login and sign-up through OAuth/Keycloak.
• Load IPS from national backend and display it in the IPS viewer.
• Select IPS resources and generate VHL QR.
• Display/share QR code.
• List ICVP records and generate per-immunization QR.
• Medication Overview tab and per-medication QR generation.
• Scan QR flows are present in the app; verify them against the backend and validator services during country setup.

Customization points

• Replace assets/icon/logo.png with a 512x512 PNG, then run dart run flutter_launcher_icons.
• Replace assets/image/landing_bg.png to customize the landing screen.
• Use Material Theme Builder and replace lib/styles/color_theme.dart for theme changes.
• Add locales under lib/l10n with app_<locale>.arb, run flutter gen-l10n, then register the language in lib/models/language_type.dart.
• Update country options and validation regexes in lib/constants.dart.

dart run flutter_launcher_icons
flutter gen-l10n

Test and build commands

• The repository includes mocked integration fixtures, so basic tests do not require the backend.
• Patrol Android tests can be run on an emulator/device for UI flows.
• Use the artifact wrapper when investigating flaky Android Patrol failures; artifacts are stored under build/patrol_artifacts/<timestamp>/.

flutter analyze
flutter test integration_test/test_bundle.dart
flutter pub global activate patrol_cli
patrol test --target integration_test/test_bundle.dart
patrol test
./scripts/run_patrol_with_artifacts.sh
flutter build apk
flutter build apk --release
flutter build ios
flutter build ipa --release

curl -X POST "${APP_BACKEND_URL}/qr/fetch" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d '{"data":"${QR_CONTENT}","pass_code":"0000"}'

curl -X GET "${APP_BACKEND_URL}/ips/icvp?bundleId=${BUNDLE_ID}&immunizationId=${IMMUNIZATION_ID}" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

curl -X POST "${APP_BACKEND_URL}/wallet/generate-link" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d '{"claims":{"1":"XCL","6":1798675199,"-260":{"-6":{"dob":"1905-08-23","n":"Aulo Agerio","ndt":"NI","nid":"16337361-9","s":"male","v":{"dt":"2017-12-11","vls":"2017-12-11"}}}},"credentialType":"ICVP"}'