DriverVault/Phone App

Car Control — Phone App (Flutter)

A Flutter client for the Car Control maintenance tracker. Talks only to the API Server (same contract and JWT auth as the web app). At full feature parity with the web app (data export/import is the only deliberate omission).

Project name carcontrol_phone, package id com.carcontrole.carcontrol_phone. Android is the supported target — the older Flutter-web build path is deprecated.

Features

• Login — email/password against /api/auth/login, password show/hide, and a collapsible Server settings section to override the API base URL on-device.
• Biometric / face sign-in + app lock — see the dedicated section below.
• Dashboard — car list with next-due status badges (date + km, worst-of), a "shared" chip on cars owned by someone else, pull-to-refresh, Add car FAB, Settings gear, and an admin action (admins only).
• Car detail — all spec fields (incl. VIN and transmission / differential / brake / coolant specs), tabs for Service history and Parts catalog, edit car, add/edit/delete service records and parts, a share sheet (owner only), quick odometer update, and delete car (type-to-confirm; cascades). Actions are gated by the caller's access level (read-only vs write vs owner).
• Settings — account (name / email verification / password), appearance (theme + dark mode, locale, date format, font size), profile (avatar via image_picker, bio), Security (biometric toggle), active sessions with remote logout, and the account-deletion state machine.
• Admin — user management screen (list / create / role / reset password / delete), gated by the admin role.

Sharing/ownership: Car.access drives isOwner / canWrite / isReadOnly getters that gate the UI, mirroring the server's access checks.

Biometric / face sign-in & app lock

Fingerprint and face-recognition sign-in via local_auth, with credentials kept in Android Keystore–backed secure storage (flutter_secure_storage).

• After a successful password login the app offers to enable biometric login; the entered (known-good) credentials are stored securely.
• The login screen then shows "Sign in with face recognition / fingerprint" buttons (labels reflect the enrolled biometric kinds) and auto-prompts once. On success the stored credentials are replayed against the normal login API, so each biometric sign-in mints a fresh session. Stale credentials (e.g. after a password change) auto-disable biometric login.
• App lock — the JWT persists, so a valid session normally restores silently. When biometric login is enabled the app instead starts locked (and re-locks when backgrounded) and shows a lock screen requiring a biometric unlock. A 30-second grace period means quick app-switches don't re-lock; a full app close (process kill) always locks on next launch. "Use password instead" on the lock screen logs out and returns to the login form.
• Manage it under Settings → Security (enabling re-confirms the password).

Android host requirements (already configured, don't revert): MainActivity extends FlutterFragmentActivity (required by local_auth), and AndroidManifest.xml declares android.permission.USE_BIOMETRIC.

Configure the API endpoint

The app talks to kDefaultApiBase (see lib/config.dart), default http://localhost:8080/api. Override at build time with --dart-define, or at runtime from the login screen's Server settings (persisted as cc_server_url).

Run & build

flutter pub get

# run on a connected device against a LAN server
flutter run -d <device> --dart-define=API_BASE=http://10.2.1.101:8080/api

# build a debug APK for a real phone on the LAN
flutter build apk --debug --dart-define=API_BASE=http://10.2.1.101:8080/api
adb install -r build/app/outputs/flutter-apk/app-debug.apk
adb shell monkey -p com.carcontrole.carcontrol_phone -c android.intent.category.LAUNCHER 1

Notes:

• android/gradle.properties sets kotlin.incremental=false — required because the project lives on drive E: while Gradle/Kotlin caches are on C: (the incremental compiler can't compute cross-root relative paths on Windows).
• AndroidManifest.xml sets android:usesCleartextTraffic="true" because the API base is a plain-HTTP LAN URL.
• The API Server must be running and reachable at the configured URL.

Structure

lib/
├── config.dart        # default API base URL (kDefaultApiBase)
├── models.dart        # Car (+ access getters), ServiceRecord, Part, AuthUser, UserProfile, Session
├── api.dart           # ApiClient — the only thing that calls the API Server
├── auth.dart          # AuthService (token persistence, app-lock flag, ChangeNotifier)
├── biometric.dart     # BiometricAuth — local_auth + secure storage; biometricAuth singleton
├── app_settings.dart  # AppSettings (theme/locale/date/font), persisted; drives MaterialApp
├── format.dart        # date/km formatting + next-service status (worst-of date/km)
├── main.dart          # app root; routes Login / Lock / Dashboard; lifecycle-based re-lock
└── screens/
    ├── login_screen.dart      dashboard_screen.dart   car_detail_screen.dart
    ├── car_form_sheet.dart     settings_screen.dart    admin_users_screen.dart
    └── lock_screen.dart