Development

Development

Cullimingo is one Flutter codebase targeting macOS and Linux (Windows later). Heavy work — decode, encode, hash, large file I/O, XMP — runs on a background isolate pool; the UI isolate only ever receives results.

Toolchain

• Flutter 3.44.x (stable, Impeller) · Dart 3.12+
• State: Riverpod 3 with codegen (@riverpod)
• Read model: drift (typed SQLite); the filesystem + XMP sidecars are the durable truth
• RAW: LibRaw via C/C++ FFI (no Rust) · thumbnails: libvips

Native dependencies

Both platforms need LibRaw and libvips for RAW/thumbnail decode:

# macOS
brew install libraw vips        # plus Xcode + CocoaPods

# Debian/Ubuntu
sudo apt install clang cmake ninja-build pkg-config libgtk-3-dev \
     liblzma-dev libstdc++-12-dev libraw-dev libvips-dev

Linux also needs libsecret-1-0 at runtime (delivery-server passwords go through the platform secret store) and udisks2/util-linux (udisksctl, lsblk) for auto-mounting a freshly inserted card on desktops that don't do it themselves — both are already present on most desktop distros.

Run

flutter pub get
dart run build_runner watch --delete-conflicting-outputs   # keep running
flutter run -d macos      # or: flutter run -d linux

Keep build_runner watch running: after editing any @riverpod, freezed, drift table or JSON model it regenerates the *.g.dart / *.freezed.dart files. Never hand-edit generated files.

Before every commit

Enforced by the lefthook git hooks:

dart format lib test && flutter analyze && flutter test

Build

flutter build macos      # or: flutter build linux

Linux release builds also need the native libs (LibRaw/libvips/libheif) bundled into the app — tool/bundle_linux.sh, then optionally tool/build_appimage.sh to package an AppImage. macOS has the equivalent tool/bundle_macos.sh. See Distribution.

The bundled GeoNames gazetteer (reverse geocoding) and IPTC Media Topics list (Subject Code autocomplete) are pre-generated into assets/; regenerate them with tool/build_gazetteer.sh / tool/build_media_topics.sh if the source data changes.

Where things live

Feature-first + layered: core/, features/<name>/{data,domain,presentation}, shared/. See ARCHITECTURE.md for the full map and BUILD_PLAN.md for the phased plan and stack rationale.