storehop

Storehop

A native Android shopping-list app for people who shop at more than one store. One master list of items is tagged across multiple stores; each store gets its own per-aisle shopping view, and checking an item off at one store cascades — buying mozzarella at Lidl drops it from the Aldi and Pingo Doce lists too, so a single shopping trip satisfies the need.

The app ships with a starter set of stores and categories. Anything not on that list (a regional chain, a one-off shop, a category for a specific household) is added or renamed by the user.

Status

Android v0.8.0 (Play Closed testing) introduces a one-time $7.99 Premium IAP that gates household-invite creation and CSV export. The app stays Free to install; everything you’d want from v0.7.x — cloud sync, cross-store cascade, joining + using a shared household someone else invited you to — is still free. The inviter-pays model means whoever pays once can generate invites; invitees join + use the shared household unconditionally. Two paths grandfather users into a silent LegacyUser entitlement (functionally equivalent to Premium): a Firebase account creationTimestamp predating the v0.8 release date OR a match against the explicit PREMIUM_VIP_EMAILS allowlist in EntitlementRepository.kt. The dev account, Mike, Amanda, and Mom are in that allowlist so they keep free Premium permanently. See the v0.8.0 entry in CHANGELOG for the full breakdown, including the in-line .1–.4 patches (VIP allowlist, vc bumps, Mom added, and the v0.8.0.4 fix for a pull-before-push race where local soft-deletes were being resurrected by the next pull).

Android v0.7.1 shipped a lossless sideload-APK → Play migration path: user preferences (theme, language, sort modes, hide-checked-off) cloud-sync to /userPrefs/{uid} via Firestore, and Settings → Data has a “Force sync now” button so beta testers can drain every pending write before uninstalling. Full runbook at docs/v0.7.1-migration.md.

Android v0.7.0 shipped multi-user household sharing on top of the existing single-user feature set: invite-code generate (8-char Crockford base32, 24h TTL, single-use) + join + leave, household-scoped data for every entity (items, stores, categories, xref, store-category-order, purchase-records), and a cross-store cascade that now extends across household members by design (Amanda buying milk at Aldi drops Mike’s “milk needed at Lidl” entry). Statistics deliberately stay per-user so Mike sees what HE bought, not the household combined. Existing v0.5–v0.6 features all carry over: anonymous-first onboarding with optional Google Sign-In, two-way Firestore + Storage cloud sync (push and pull), Shop and Items tabs with item photos, share-list-as-text, theme + language picker (English, European Portuguese, Spanish, Italian), drag-reorder stores (long-press on any tile), per-store aisle ordering, cross-store check-off cascade, Manage Categories, hide / show checked-off items toggle, QuickAdd autocomplete against the master Items library, in-app update prompt via Play Core, CSV import / export of items and categories, and a Statistics screen with a 12-week trend chart. See docs/play-store-submission.md for the Play Console listing answers and docs/privacy-policy.md for the privacy policy hosted at the Play listing’s required URL.

iOS port (in ios/ — SwiftUI + GRDB + Firebase iOS SDK, mirrors the Android architecture 1:1): now at v0.8.1 in main, fully caught up to the Android branch. v0.8.1 brings the bulk store-tag flow over (long-press an Items-list row → contextual toolbar → “Tag to stores…” sheet → apply across multiple items in one transaction). Android’s v0.8.1 architectural xref-join fix is a no-op on iOS because GRDB has no equivalent of Room’s leaky @Junction — every iOS join query has filtered tombstones in SQL since day one.

Beyond Android parity, the iOS branch is now App Store-ready code-side: the AppIcon ships (1024×1024 sage flatten of the shared design/shophop-icon-512.png source), light + dark mode both render the actual brand palette (a Hex-the-Asset-Catalog-namespace fix that was silently failing before — the app was painting with iOS system defaults). Full E2E suite of 13 XCUITest cases + a DesignSystemTourTest visual-regression artifact that walks every major screen in both appearances. 187 unit + 13 UI tests green.

TestFlight ship is gated on the Apple-side config bundle: real GoogleService-Info.plist, DEVELOPMENT_TEAM in project.yml, PrivacyInfo.xcprivacy manifest, App Store Connect premium_lifetime IAP setup, and a 2-device manual smoke. Full walkthrough at docs/ios-app-store-submission.md.

Tech stack

• Kotlin 2.1, Jetpack Compose, Material 3 (BOM 2024.12.01)
• Single-activity Compose Navigation; Hilt for DI
• Room 2.6 (KSP) for local persistence; sync-ready schema
• Firebase: Authentication (anonymous + Google via Credential Manager), Firestore push + pull sync, Storage for item photos
• Coil for image loading; DataStore Preferences for theme + locale state
• Min SDK 26, target and compile SDK 35
• Gradle 9.5, Android Gradle Plugin 8.10
• Languages: English, European Portuguese (pt-PT), Spanish (es), and Italian (it) via the per-app locale API on Android 13+, AppCompat backport on 8.0–12. All ~180 strings translated; native-speaker review pending before any public Play promotion of es / it.

Building

Open the project in Android Studio and let it sync. From the command line, the standard tasks are:

./gradlew :app:assembleDebug         build the debug APK
./gradlew :app:installDebug          install on a connected device
./gradlew :app:testDebugUnitTest     run the unit-test suite
./gradlew :app:bundleRelease         build the signed release AAB

Release signing reads keystore.properties at the repo root (gitignored; see app/build.gradle.kts for the expected keys). When that file is absent the release task succeeds but the AAB is left unsigned, so CI and fresh checkouts can still run assembleDebug and the unit tests.

The unit-test suite uses Robolectric and runs without an emulator.

Project layout

app/src/main/
    java/com/storehop/app/
        auth/             Google Sign-In, FirebaseAuth session provider
        data/
            dao/          Room DAOs
            db/           Database, migrations, seeder, JSON-backed seeds
            entity/       Sync-ready entities (UUID PKs, soft delete)
            prefs/        DataStore-backed user preferences
            repository/   Repository interfaces and implementations
            storage/      Firebase Storage uploader for item photos
            util/         IdGenerator, UserSessionProvider
        di/               Hilt modules (App, Database, Firebase, Prefs, Repo)
        sync/             Push side of the Firestore sync engine + DTOs
        ui/
            auth/         Sign-in screen
            items/        Items master list, Add/Edit form
            nav/          Compose Navigation routes
            settings/     Account, theme, language picker
            shop/         Store picker, Shop-at-Store, share-as-text
            theme/        Material 3 theme
            util/         CategoryLabel localization helper
        MainActivity.kt
        StorehopApplication.kt
    assets/seed/          stores.json, categories.json, store_categories.json
    res/
        values/           English strings, theme colors, launcher icon
        values-pt-rPT/    European Portuguese strings

Data layer

Every entity carries id (UUID), createdAt, updatedAt, deletedAt (soft-delete tombstone), userId, and pendingSync. This shape supports offline edits, deterministic merging across devices, and the push-side Firestore sync engine in sync/. Per-store need state lives on item_store_xref.isNeeded; the default check-off cascades across every tagged store (one trip clears the list everywhere), and the manual markNeededAtStore path leaves a per-store override hook for later if we ever want to expose it. The Room schema is exported to app/schemas/ and tracked in version control so migrations are reviewable.

Seeded stores and categories use stable string IDs (for example store_lidl, cat_produce) rather than generated UUIDs so the seed pack remains stable across devices and across reseeds.

Roadmap

• v0.1 Data layer schema and theme foundation; placeholder MainActivity.
• v0.2 Shop, Items, Add/Edit, item photos, share-list-as-text.
• v0.3 Anonymous-first auth, Google Sign-In, Firestore + Storage push sync, per-store need state, drag-reorder stores, settings (theme + language), undo + haptics, Play Store submission.
• v0.4.0 Pull-side Firestore sync (cold-launch rehydrate before push jobs run) and a Settings cloud-sync banner with Retry action.
• v0.5.0 Manage Categories screen (add / rename / soft-delete / undo) from the Items overflow menu, and per-store Edit Aisles drag-reorder for category order in Shop-at-Store. Settings → bottom-nav routing fix so Items / Shop tabs land deterministically.
• v0.5.1 Cross-store check-off cascade with full Undo (one shopping trip clears the item from every tagged store); first-letter auto-cap on item / brand / store / category name fields; custom user-added categories appear in a store’s Edit Aisles as soon as they’re tagged.
• v0.5.2 CSV import / export of items and categories from Settings → Data, with a non-destructive import (duplicates skipped) and a snackbar + Undo. Words-level Title Case auto-cap on name fields. “Discard changes? / Keep editing” confirmation on the item-edit back arrow.
• v0.5.3 Categories-import snackbar correctly counts skipped duplicates (was always reporting “Skipped 0 duplicates” even when the skip itself was working).
• v0.5.4 Settings → Data: the four import / export buttons stack vertically at full card width instead of squeezing into a 2x2 grid with mismatched button heights.
• v0.5.5 Renaming a category or store no longer fails when a long- deleted row is still holding the target name. Schema v6 drops the UNIQUE(userId, name) index that was counting tombstones, with an alive-collision-only guard at the application layer and a clear inline error on the rename dialog when the collision is with an existing row.
• v0.5.6 The “Critical items needed” banner on the Shop screen now routes you to the right store first instead of listing every priority item by name — collapsed view shows the count plus the single store covering the most criticals; tap to expand a per-store breakdown.
• v0.5.7 Hide / show checked-off items toggle in the Shop-at-Store top bar; QuickAdd autocomplete against the master Items library (with name-match dedupe to fix duplicate-creation on existing items); in-app update prompt via Play Core (no more Play Store visits between iterations); custom undo bar with × button and swipe-to-dismiss; long-press anywhere on a store tile to reorder (drag-handle icon retired); Statistics → Activity card simplified to all-time + trend chart only.
• v0.5.8 Spanish (Castilian) and Italian language support. Settings → Language picker now offers four locales: English, European Portuguese, Spanish, Italian. First-pass translations are machine-quality; native-speaker review pending before any public Play Store promotion.
• v0.5.9 [yanked] Tried AppCompatDelegate-only locale apply path to fix Italian / Portuguese not applying on Pixel; that regression broke Spanish too (no language switched at all). Reverted in 0.5.10.
• v0.5.10 Reverted v0.5.9’s locale-apply path. Spanish + English working again under the in-app picker. Italian and Portuguese-not-applying on Pixel under per-app locale is a separate issue still being investigated.
• v0.5.11 Found the actual root cause: AAB language splits. Play Store was stripping non-preinstalled locale resource packs from on-device installs (Pixel ships es-* data preinstalled but not Italian or Portuguese, so those splits weren’t delivered even though they were in the AAB). Disabled the language split via bundle { language { enableSplit = false } } so the base APK always carries every locale.
• v0.5.12 Items list deleted-item undo prompt now uses the shared UndoBar (× close, swipe, 3s auto-dismiss). Replaces the Material3 SnackbarHost that had the same indefinite- duration issue we already fixed on the Shop screens.
• v0.5.13 Same UndoBar migration on Manage Categories’ deleted-category undo prompt.
• v0.5.14 Edit-aisles screen drag UX: removed the drag-handle icon; long-press anywhere on a category tile starts the drag. Plus AppUpdateController logs at INFO/WARN now so the in-app-update flow’s state is visible in Logcat.
• v0.5.15 iOS catches up to Android: shared UndoBar component on iOS ItemsListView + ManageCategoriesView (× close, swipe, 3s auto-dismiss). iOS marketing version bumped from 0.5.1 to 0.5.15. iOS Edit aisles intentionally keeps the platform-idiomatic .onMove + EditButton pattern.
• v0.6.10 iOS parity catch-up (iOS-only; Android unchanged). Three long-standing gaps closed: the StorePicker banner now has the same “Most at ()" routing hint + per-store breakdown Android shipped in v0.5.6; Items / Shop-at-Store / Store Picker now have empty-state illustrations (SF Symbol + title + body) matching Android v0.6.8; the OnSurfaceVariant + Secondary palette colours were darkened to fix a WCAG AA contrast failure (4.20:1 → 5.30:1) the Android theme audit caught in v0.6.8.
• v0.6.9 Fix Mike-reported Store Picker over-counting criticals (banner said “10 critical needed” with 5 per store; in- store correctly said “1”). Root cause: v0.6.7’s picker partition treated isStaple && !purchasedThisSession rows as “needed”, which over-included priority staples the user had marked purchased. Reverted the partition to isNeeded-only (matches Mike’s mental model: marked-purchased = off the list, even for staples). In-store view unchanged (still surfaces struck-through staples for convenience). The “auto-renew staples at session” idea is now flagged as opt-in only, not a default.
• v0.6.8 UX polish bundle: empty-state illustrations on Items / Shop-at-Store / Store Picker (large Material Symbols icon + split title/body, replacing the old flat-text empty states); Settings reorganised into Account / Display / Data / About section headers + a new About card with version, privacy policy, and source-code links; dark-theme contrast audit fixed one WCAG AA failure (onSurfaceVariant on surfaceVariant was 4.20:1 in light mode, now 5.30:1 — every other pair already passed). iOS gets the matching About section; iOS empty-state icons defer.
• v0.6.7 Fix Mike-reported critical-items display bug across the Store Picker and Shop-at-Store screens. Two intersecting bugs: the in-store banner was flagging priority items already checked off this session (or carried over as staples from prior trips) as still-critical, and the picker was silently hiding priority staples that the user checked off last week. Both fixed; iOS already had the Bug A filter, mirrored the Bug B SQL + partition change. The deeper auto-renew-staples-at-session fix stays a separate v0.7+ item per project memory.
• v0.6.6 Follow-up fix: drag now actually commits on Manage Categories. v0.6.5 unblocked the drag gesture but the drop was a visual no-op – the row snapped back to its original spot. Root cause was a remember(categories) key on the optimistic-local list state that raced the post-drop LaunchedEffect re-sync and clobbered the new order before the DB write landed. Normalised to the StorePicker / EditAisleOrder pattern.
• v0.6.5 Fix Mike-reported gesture conflict on Manage Categories: trying to drag a row was triggering bulk-select instead. The v0.6.4 long-press-to-enter-selection handler covered the whole Card, so the drag-handle’s own long-press race was losing. Scoped the selection gesture to just the checkbox + text region; the drag handle and overflow-menu button now live outside that tap target.
• v0.6.4 Manage Categories: drag-to-reorder + bulk select to delete + multi-add. Schema migration v6 → v7 adds a displayOrder column to categories; the backfill dense-ranks by name so the existing list order is preserved on first open. iOS uses the platform-idiomatic EditButton for selection + drag. 424 → 440 unit tests.
• v0.6.3 Fix Mike-reported regression: the in-app update sheet shows twice on tap. Root cause was a race window in the v0.5.7 guard where Play’s bottom-sheet dismiss happens before installStatus transitions out of UNKNOWN, so the next onResume re-prompted. Added a per-activity session flag in AppUpdateController.
• v0.6.2 Two more Mike-asks bundled. In-store critical-items banner shortened (“5 critical items at this store” → “5 critical items”) so it stops wrapping to two lines. Items list search placeholder collapsed to “Search anything”, and the filter now also matches against category name – typing “frozen” surfaces every item in the Frozen category. Both changes ship to Android + iOS in this release; Android tests pin the new search match (422 unit tests green, 99.9% line coverage maintained).
• v0.6.1 Two more Mike-asks bundled. Inline “+ New category” entry in the item edit screen’s category picker (one less round trip to Manage Categories), and a +/− button on each row of the master Items list (tap + to mark the item needed at every tagged store, − to clear from every tagged store — the cross-store cascade design keeps both branches consistent with the Shop tab). Both ports landed on Android and iOS in the same release. Tests: 360 → 366 unit tests on Android plus three new GRDB-backed iOS tests.
• v0.6.0 Mike’s UX feedback bundle: × clear-search button on both the in-store search and the master Items search; long-press an item in a store’s list to jump straight to its edit form (great for tagging “this store also carries X” without leaving the store view); collapsing/expanding in-store critical-items banner so a long list of criticals doesn’t push the screen off the fold; new Alphabetic ↔ Category sort toggles in the top app bars on both the Shop-at-Store screen and the Items list, with the choice persisted independently per screen. Search prompt on the Items list shortened from “Search items by name or brand” → “Search by name or brand” (was wrapping on Mike’s Pixel). Android-only release; iOS parity to follow on the Mac side.
• v0.7.0 Multi-user account sharing ✅ shipped (Android, Play Closed Testing). Mike-asked: “allowing multiple people to access one account is probably a good one. I could see allowing Amanda to access my list and add items and check off items.” New household abstraction sits between user and entity: every item / store / category / xref / SCO / purchase-record carries a householdId access scope. Settings → Household provides invite-code generate (8-char Crockford base32, 24h TTL, single-use) + join-with-code + leave-household. Cross-store cascade extends to households by design — Amanda buying milk at Aldi drops Mike’s “milk needed at Lidl” entry. Statistics deliberately stay per-user: Mike sees what HE bought, not Mike + Amanda combined. iOS Phase 5 mirror — schema v8, HouseholdRepository / View / ViewModel, household-scoped DAOs, sync DTOs + paths, parity unit tests — is on main; iOS marketing version stays at v0.6.10 until a Mac xcodebuild test + 2-device smoke run, then bumps to 0.7.0. See CHANGELOG for the deferred-to-v0.7.x list (real-time addSnapshotListener, per-field merge, member roles, multiple households per user, activity log, etc.).
• v0.7+ Polish follow-ups and a v2 home-screen widget that actually does something useful. An opt-in “auto-renew staples at session start” toggle in Settings (was a default-on TODO pre-v0.6.9; re-classified to opt-in after Mike’s evidence showed users expect “marked purchased = stays off the list” — auto-renewal would surprise them). v0.7.0 household follow-ups: real-time addSnapshotListener updates so Amanda’s checks appear on Mike’s device without a refresh, per-field conflict merging instead of last-write-wins, cloud-side membership lookup for second-device sign-in, and member roles for households that need it.