data

Imported from katsugtgz/shollu-android (app/src/main/java/com/ebsoft/shollu/data/AGENTS.md). Install upstream with npx skills add katsugtgz/shollu-android --skill data. Copyright stays with the author.

data/ — persistence, calculation caching, city seed, clock seam

OVERVIEW

Room DB + DataStore prefs + repositories (prayer calc cache, city seed) + pure domain models; no DI — classes are concrete, seams are constructor params (AppClock, SholluPreferences).

WHERE TO LOOK

• Seeding / preset defaults → db/SholluDatabase.kt (defaultPresets(), seedPlan(), ensureDefaultPresets())
• Reminder schedule encoding (days/hour-minute ranges, type enum) → db/entity/ReminderEntity.kt
• Enum↔String persistence fallbacks → db/Converters.kt
• City listing/search SQL ordering → db/dao/CityDao.kt; reminder list order → db/dao/ReminderDao.kt
• Every pref key + safe default → preferences/SholluPreferences.kt (companion)
• Prayer-time caching / midnight rollover → repository/PrayerRepository.kt, repository/AppClock.kt
• City table bootstrap (raw JSON + fallback list) → repository/CityRepository.kt
• Polar validity / next-prayer math → model/PrayerTimes.kt; method angles → model/CalculationMethod.kt
• APK self-update files → update/AppUpdater.kt, update/UpdatePolicy.kt, update/GitHubReleaseClient.kt, update/PreferenceUpdateStore.kt, update/ApkUpdateInstaller.kt, update/ApkVerifier.kt, update/UpdateModule.kt

CONVENTIONS

• SholluDatabase.seedPlan(seededMarker, existing, catalogGeneration) is the pure idempotency core; ensureDefaultPresets() is the impure wrapper (mutex + marker + generation). Change seeding logic in seedPlan, not the wrapper.
• Seeded-once marker is SholluPreferences.DEFAULT_PRESETS_SEEDED; catalog gen is PRESET_CATALOG_GENERATION. Missing gen on a seeded install = generation 1 (four-row catalog) so generation 2 (Ayyamul Bidh + malam-sebelumnya) can still insert. After generation 2, user-deleted rows stay gone. Empty table + seeded marker never inserts. Failed table read → abort, marker/gen unchanged.
• ReminderEntity validates in init {} via require(): timeHour 0..23, timeMinute 0..59, preWarningMinutes >= 0. Constructing with bad values throws — copy-with-edit pattern is the only safe mutation.
• ReminderType (5 presets + CUSTOM) and DaysOfWeek live in ReminderEntity.kt, not separate files. DaysOfWeek is a value object over rawValue: String — "*" (everyday), "ONCE", or CSV "1,4" (1=Mon…7=Sun; out-of-range dropped in daysSet).
• model/Reminder.kt is typealias Reminder = ReminderEntity — one shape everywhere, no mapper.
• Type converters never throw: null/blank/unknown → CUSTOM / "*" (via fromString companions).
• CityDao.getAllCities() orders country = 'Indonesia' DESC, name ASC — Indonesia-first is SQL, not UI. City search is client-side: filterCities in ui/screens/settings/LocationPickerDialog.kt ANDs whitespace-split terms against name and province (Locale.ROOT, case-insensitive); there is no SQL LIKE path.
• ReminderDao.getAllReminders() orders by timeHour, timeMinute — UI timeline depends on this order.
• SholluPreferences: every read is safeDataStore.mapDistinct { prefs[KEY] ?: default } (map + distinctUntilChanged). DataStore emits the full snapshot on any key write; without distinct, unrelated toggles retrigger every mapped Flow. Defaults: Jakarta (-6.2088, 106.8456, elev 8.0, tz 7.0), KEMENAG_RI, asr STANDARD, ihtiyat 2, hijri 0, pre-prayer 10, iqomah 10, theme EMERALD, lang INDONESIAN, per-prayer offsets 0. Enum reads wrap valueOf in try/catch → default enum.
• IOException on DataStore read → emit(emptyPreferences()) (defaults surface); other exceptions rethrow. Corruption → ReplaceFileCorruptionHandler resets to empty.
• SELECTED_CITY_IS_GPS: true only when city came from GPS; stored tz is a DST snapshot re-derived on ACTION_TIMEZONE_CHANGED. updateCity(city, isGps=false) — picking from the fixed list clears it.
• PrayerRepository cache is access-order LinkedHashMap<PrayerCalculationKey, PrayerTimes> guarded by cacheLock (not concurrent; mutate only under the lock); key = date + full city (lat/lon/elev/tz) + method + juristic + ihtiyat + offsets map. Any new calc input MUST join the key or stale results leak. Cap is MAX_CALCULATION_CACHE (400): removeEldestEntry drops the least-recently-accessed key on insert over cap — never wipe the whole map. Hits go through get so they refresh LRU order. clearCache() takes the same lock (tests).
• calculateForDateSync() = runBlocking(Dispatchers.IO); any exception → hardcoded Jakarta/KEMENAG_RI/ihtiyat-2 fallback. Never call from a coroutine (blocks a thread).
• CityRepository.initializeCitiesIfNeeded() seeds from R.raw.cities (Gson → List<CityEntity>) when count==0; parse failure/empty → 14 hardcoded cities (12 Indonesia + Makkah + Madinah). Returns Result<Unit>. This class has NO interface — unlike Prayer/Reminder repos.
• AppClock seam + internal datePulseFlow(clock, pollIntervalMillis): wakes at midnight+50ms, capped at one poll interval (30s default) so wall-clock/timezone jumps re-emit. Value always from clock, delay only sets cadence.

APK self-update

Done when check, cache, and install all hold:

• Check: AppUpdater.check() from MainActivity LaunchedEffect only. Play-installed copies stay Quiet. Tests inject ReleaseFetcher + UpdateStore fakes.
• Throttle: stamp last-check on failed fetch without rewriting the APK cache. A throttled check still prompts from cache.
• Snooze: Nanti stores tag + expiry (now + 24h). Same tag re-prompts after expiry; a newer tag prompts immediately.
• Digest: persist tag+url+size even with blank digest. Verify digest at install (ApkVerifier).
• Gson DTOs in GitHubReleaseClient need @SerializedName on every JSON field plus the ProGuard keep rules — R8 rename otherwise drops assets and release APKs never prompt.
• InstallResult.Started dismisses the Compose dialog; system PackageInstaller UI owns confirmation after that. ApkUpdateInstaller single-flights downloads and abandons uncommitted sessions.

ANTI-PATTERNS

• Don't reseed by checking table emptiness alone — user deleting all presets would get them back. Marker decides.
• Don't bypass seedMutex by calling DAO inserts directly during startup; onCreate callback and app-start path race.
• Don't read DataStore via context.dataStore.data directly — skips the IOException recovery; use safeDataStore flows.
• Don't add a prayer-calculation input without extending PrayerCalculationKey.
• Don't schedule on a PrayerTimes whose isSubuhValid/isIsyaValid is false — times are clamped placeholders at high latitude.
• Don't reorder CityDao/ReminderDao ORDER BY casually; UI order and "next reminder" logic assume them.

NOTES

• DB is version 1, fallbackToDestructiveMigration() (no migrations written; a schema bump wipes user reminders — prefs survive in DataStore).
• defaultPresets() seeds 6 rows: Al-Kahfi, Dhuha, two SENIN_KAMIS (sahur 03:30 Mon/Thu + malam sebelumnya 20:00 Sun/Wed), AYYAMUL_BIDH (Hijri 13–15 via nextPresetInstant + user hijriAdjustment), TAHAJJUD enabled (Subuh−45). Catalog generation 2 upgrades seeded v1 installs; unseeded non-empty tables are never treated as a gen-2 upgrade.
• All six ship isEnabled = true and must be seeded before ReminderAlarmScheduler arms alarms.
• PrayerTimes.getNextPrayerTarget(now, tomorrow) is the single next-prayer selector (polar-aware). Pass the real next-day instance for the correct post-Isya rollover time — omitting it reuses today's schedule for tomorrow's dawn.
• CalculationMethod: 10 methods; UMM_AL_QURA + QATAR use ishaIntervalMin=90 with ishaAngle=0; defaultIhtiyatMin is per-method (KEMENAG_RI 2, MUIS 1, rest 0).