Fuel Tax Tracker

A Flutter app (Android + iOS) for logging fuel purchases per vehicle. Snap a photo of a gas receipt, it OCRs the gallons/price-per-gallon/total on-device, you confirm or correct the numbers, and it's saved alongside the receipt photo to a data file in a folder you choose.

Features

• Manage a list of vehicles (make, model, color, license plate).
• Capture a fuel receipt photo per vehicle and OCR it on-device with Google ML Kit — no internet connection or API key required.
• Review/edit the parsed gallons, price per gallon, and total cost before saving (OCR on printed receipts is usually good but not perfect).
• Per-vehicle fuel log with running gallons total, tap-to-zoom receipt photos, and delete.
• Settings screen to choose where receipt photos and the data file are stored (defaults to the app's own documents folder; existing data is copied over when you change it).

Project layout

lib/
  models/       Vehicle, FuelEntry — plain data classes with JSON (de)serialization
  services/
    app_state.dart        In-memory state + CRUD, backed by StorageService, exposed via Provider
    storage_service.dart  Owns the data.json file + receipts/ folder and the configurable save path
    ocr_service.dart      Thin wrapper around google_mlkit_text_recognition
    receipt_parser.dart   Regex-based extraction of gallons/price/total from OCR text
  screens/      One file per screen (vehicle list, add/edit vehicle, vehicle detail,
                confirm fuel entry, receipt viewer, settings)

Data is stored as a single fuel_tax_data.json file plus a receipts/ subfolder of photos, both inside whatever directory Settings points at.

Running it

flutter pub get
flutter run            # with a device/emulator connected or a simulator booted

To build release artifacts:

flutter build apk --release      # Android
flutter build ios --release      # iOS (requires a full Xcode install + signing setup)

This was scaffolded and verified with Flutter 3.44.9. flutter analyze and flutter test are clean, and flutter build apk --debug has been confirmed to produce a working APK.

Permissions

• Camera: NSCameraUsageDescription (iOS, ios/Runner/Info.plist) and android.permission.CAMERA (Android, AndroidManifest.xml) are already set up for receipt capture.
• Storage: no explicit storage permission is declared. The default save location is inside the app's own sandbox (no permission needed). If you point Settings at a location outside the sandbox, the OS-native folder picker (via file_picker) is what grants access — see the caveat below.

Known caveats / things to revisit

• file_picker is pinned to 10.3.10, not the latest release. Versions 11.0.0–11.0.3 skip applying the Kotlin Gradle plugin when they detect AGP 9+ (assuming AGP's built-in Kotlin support handles it), but that isn't actually wired up for library modules in this Flutter/AGP combination yet, so the plugin's own Kotlin sources never get compiled and the build fails with cannot find symbol: FilePickerPlugin. 10.3.11 fixes that but is retracted on pub.dev, hence 10.3.10. Worth revisiting this pin next time you bump dependencies — check the package's CHANGELOG for when this is properly resolved upstream.
• iOS folder picking and app restarts: file_picker's directory picker on iOS uses UIDocumentPickerViewController, which hands back a security-scoped URL. This app does not currently persist a security-scoped bookmark for that URL, so if you pick a folder outside the app's own sandbox (e.g. an iCloud Drive folder) on iOS, continued write access after an app restart is not guaranteed. Picking the default in-sandbox location, or a folder on Android, does not have this limitation. If cross-restart external storage on iOS matters for your use case, this needs a proper bookmark implementation (NSURL bookmarkData + startAccessingSecurityScopedResource).
• Receipt parsing is best-effort regex matching on the OCR'd text (lib/services/receipt_parser.dart), tuned against common receipt phrasing ("GALLONS", "PRICE/GAL", "PPG", "TOTAL", etc.). Unusual receipt layouts may parse partially or not at all — the confirm screen always lets you fill in or correct whatever wasn't found.
• No automated tests exercise the OCR or camera capture path itself (that requires a real device/emulator with a camera); receipt_parser_test.dart covers the parsing logic against fixed OCR text.