Field Notes

Offline-first Flutter app for capturing field notes with text, photos, and geolocation.

Features

• Create, edit, and delete notes
• Photo capture (camera or gallery)
• Automatic geolocation
• Map visualization
• Search by title/content
• Server sync (offline-first)
• JWT authentication

Architecture

Clean Architecture with 3 layers:

lib/
├── core/                 # Shared infrastructure
│   ├── database/         # Drift (SQLite)
│   ├── network/          # Dio + interceptors
│   └── errors/           # Failures and exceptions
├── features/
│   ├── auth/             # Authentication
│   ├── notes/            # Notes (CRUD)
│   ├── sync/             # Synchronization
│   └── map/              # Map visualization
├── routing/              # GoRouter
└── shared/               # Shared widgets

Stack

Category	Technology
State	Riverpod 3 + code generation
Local DB	Drift (SQLite)
Entities	Freezed
Network	Dio
Routing	GoRouter
Maps	flutter_map + OpenStreetMap
Photos	image_picker

Requirements

• Flutter 3.24+
• Dart 3.5+

Setup

# Full setup (dependencies + code generation)
make setup

# Or manually:
flutter pub get
dart run build_runner build --delete-conflicting-outputs

Makefile

Command	Description
make setup	Install dependencies and generate code
make run	Run in debug mode (dev)
make run-prod	Run in debug mode (prod)
make build-runner	Generate code (Riverpod, Freezed, Drift)
make watch	Generate code in watch mode
make analyze	Run flutter analyze
make test	Run tests
make apk	Build debug APK
make apk-release	Build release APK
make bundle	Build App Bundle (Play Store)
make clean	Clean build
make ci	CI pipeline (get + build + analyze + test)

Environment Variables

Variable	Description	Default
API_BASE_URL	API base URL	http://localhost:8080

Pass via --dart-define:

# Development
flutter run --dart-define=API_BASE_URL=http://localhost:8080

# Production
flutter build apk --release --dart-define=API_BASE_URL=https://api.fieldnotes.com

Offline-First Strategy

1. UUID as clientId - Notes created offline have unique IDs
2. SyncStatus - Each note has status: pending, synced, conflict
3. Last Write Wins - Conflicts resolved by most recent timestamp
4. Soft delete - Deletions are marked and synced

Build

# Android
flutter build apk --release

# iOS
flutter build ios --release