DriverVault/Phone App/README.md

Car Control — Phone App (Flutter)

A Flutter client for the Car Control maintenance tracker. Talks only to the API Server (same contract and auth as the web app — a PocketBase token relayed by the server, not a JWT the server mints). 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), a share sheet (owner only), quick odometer update, edit car, and delete car (type-to-confirm; cascades). Actions are gated by the caller's access level (read-only vs write vs owner). Tabs, in the web app's order:
  • Service history — date/odometer plus which parts were changed, with the next-due date/km derived by the server.
  • Technical check history — the mandatory roadworthiness inspections (przegląd techniczny, MOT, TÜV). Result, cost, station, and the certificate's valid-until, which overrides the car's interval when present. A failed check derives no next date.
  • Maintenance — workshop visits and repairs outside the routine schedule: type/status, workshop, parts used, labour + parts cost, invoice number and a warranty-until badge.
  • Fuel — refills with a summary panel (average / best / worst consumption, cost per km, price per litre). Consumption is measured between full tanks, so partial fills roll into the next full one and a flagged missed fill leaves its window uncomputed rather than reporting a fictional figure.
  • Documents — insurance, registration, road tax and the rest, with a renewal badge driven by the server's expiry assessment.
  • Parts catalog — the per-car parts list.
  • Reminders — date- and/or odometer-triggered, one-off or recurring, with a Mark done action. Reminders the server derived from a document or service record are shown read-only.
• Attachments — one optional file per service record, technical check, workshop visit, refill, document and part (PDF or image, up to 10MB). Picked with file_picker, fetched back through the API Server — never a public URL — and opened with the phone's own viewer via open_filex.
• Settings — account (name / email verification / password), appearance (theme + dark mode, language, region, date format, currency, font size), profile (avatar via image_picker, bio), Security (biometric toggle), and the account-deletion state machine. Auth relays PocketBase's own stateless tokens, so there is no per-device session list to show or revoke.
• 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.

Language, region & currency

Language and region are two pickers over the one stored BCP-47 tag (en-US), so the pair can be mixed — English in Poland, say. Currency is display-only: nothing is converted, so changing it reinterprets existing amounts rather than recalculating them. All three lists mirror the API's (validCurrencies and the locale pattern in internal/api/me.go), with two deliberate differences from the web app:

• Luxembourgish (lb) and Romansh (rm) are not offered. intl ships no date/number symbols for them and throws rather than falling back, which would take out every date on screen. The browser has full ICU data behind it and has no such limit, so the web app can list them.
• Labels are hand-kept (endonyms for languages, English for regions and currencies) because Dart has no Intl.DisplayNames.

Because the server only validates a locale's shape (^[a-z]{2}-[A-Z]{2}$), a tag the phone cannot render can still arrive from the web. format.dart resolves through a supported-language check and falls back to en-US instead of throwing; test/models_format_test.dart covers it.

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 token 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