first commit

README.md

@@ -0,0 +1,93 @@
+# 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.