Design an Offline-First News App

Regular caching is a fallback — the app tries the network first and falls back to cache only on failure. Offline-first inverts this: the local database is always the source of truth. The UI always reads from Room regardless of connectivity. The network only exists to keep the local database updated. This guarantees the app works identically whether or not internet is available — there's no code path that fails without network. It also means instant cold starts (Room read is <1 ms vs network which is 200 ms+).

WorkManager is the correct modern solution because: (1) it survives process death — work is persisted to a SQLite database and re-scheduled on boot; (2) it respects Doze mode and battery restrictions — work deferred appropriately without killing battery; (3) it supports constraints (Wi-Fi only, battery not low) declaratively; (4) it handles retries with backoff automatically. AlarmManager fires at an exact time but doesn't handle process death or battery policy. Raw Services are killed by the system on Android 8+. WorkManager handles all edge cases that require hundreds of lines of custom code with the older APIs.

Run an eviction query inside every sync transaction: DELETE FROM articles WHERE syncedAt < :cutoff AND isBookmarked = 0. The cutoff is typically now - 48 hours. Doing this inside the same transaction as the upsert is crucial — it's atomic: either both succeed or neither does, preventing partial states where old articles persist alongside failed new insertions. Bookmarked articles are explicitly excluded so user-saved content survives eviction. For images, Coil's DiskLruCache handles eviction automatically via LRU once it reaches the configured size cap.

An ETag is a hash of the response content that the server includes in the response header (ETag: "abc123"). The client stores it. On the next request, it sends If-None-Match: "abc123". If the content hasn't changed, the server returns 304 Not Modified with an empty body — only headers, zero bytes of content transferred. This is massive for a periodic sync that fires every 4 hours: if news is slow on a Sunday morning, all syncs cost near-zero data. The client only pays the full data cost when content actually changes.

Room DAO methods that return Flow are reactive. Room uses SQLite's change notification mechanism — any write to the articles table triggers an invalidation, which causes the active Flow to re-emit. The Fragment's collectLatest picks this up and the RecyclerView updates via DiffUtil. There is no polling, no manual refresh call from the Fragment. The sync worker writes to Room (from a background thread), and the UI thread receives the update through the coroutine Flow pipeline automatically. This is the elegance of Room + Kotlin Flow.

The server's article data (title, body, imageUrl, publishedAt) should always win — use @Insert(onConflict = OnConflictStrategy.REPLACE). But local flags (isRead, isBookmarked) are client-only state that must be preserved. Strategy: before upserting, read existing local flags; after mapping the server response to an entity, merge the local flags back in. Or better: use @Update / @Query to update only the server-driven columns, leaving isRead and isBookmarked untouched. A clean pattern: separate the entity into a ArticleContent table (server-owned) and ArticleUserState table (client-owned), joined by article ID.

enqueueUniquePeriodicWork ensures only one instance of the periodic sync exists by name. ExistingPeriodicWorkPolicy.KEEP means: if a work request with this name already exists, do nothing — keep the existing schedule. REPLACE would cancel the existing one and restart the interval, potentially causing extra syncs or losing the existing schedule. Using KEEP with a call in Application.onCreate() means the sync is safely registered on every app launch, but the actual periodic schedule only runs once and is never duplicated.

On SwipeRefreshLayout swipe: (1) Call triggerImmediateSync() which enqueues a OneTimeWorkRequest with ExistingWorkPolicy.REPLACE (so multiple swipes don't stack up); (2) Observe the WorkInfo state from WorkManager: when State.RUNNING, show the spinner; when SUCCEEDED or FAILED, hide it. Do not hide the spinner when Room emits new data — hide it when the WorkManager job completes. This handles the case where the sync ran but found no new articles (304 response) — the spinner correctly stops even though Room didn't emit.

Use Room's FTS4 or FTS5 virtual table. Annotate a data class with @Fts4(contentEntity = ArticleEntity::class). Room creates a shadow FTS table and SQLite triggers to keep it in sync with articles. Query with: SELECT * FROM articles JOIN articlesFts ON articles.rowid = articlesFts.rowid WHERE articlesFts MATCH :query. FTS uses an inverted index, so "climate change" searches the index rather than scanning every row. It supports prefix matching (clim*), boolean operators, and near-word matching. In the ViewModel, debounce the search input by 300 ms to avoid hitting Room on every keystroke.

The server sends an FCM data message (not a notification message) when breaking news hits. FirebaseMessagingService.onMessageReceived() receives it even when the app is in the background or killed. It enqueues an expedited OneTimeWorkRequest. The worker syncs the relevant article, saves it to Room, then uses NotificationManager to build and show a push notification with the headline and a PendingIntent deep-linking to the article. Using data messages instead of notification messages gives full control over notification content and timing — the notification fires only after the article is saved locally, so tapping it always works offline.

Wrap ConnectivityManager.registerDefaultNetworkCallback in a callbackFlow: the onAvailable callback emits true and onLost emits false. Expose this as a StateFlow<Boolean> in the ViewModel. The Fragment observes it and animates a banner view (using TransitionManager.beginDelayedTransition) in/out. When the network returns, trigger an immediate sync automatically — the user doesn't need to pull-to-refresh. Use distinctUntilChanged() on the Flow so rapid toggle/untoggle events don't cause banner flicker.

Use WorkManager's TestListenableWorkerBuilder: val worker = TestListenableWorkerBuilder<NewsSyncWorker>(context).build(). Use an in-memory Room database and a mock Retrofit API (returns pre-built responses). Call worker.doWork() (suspending). Assert: (1) Worker returned Result.success(); (2) Room contains the expected articles; (3) sync_metadata.etag was updated; (4) Old articles were evicted. For the 304 case: mock API to return an empty body with 304 status, assert Room is unchanged. For retry: mock a network exception, assert Result.retry() on attempt 1 and Result.failure() on attempt 4.

Delete-all then insert destroys local state (isRead, isBookmarked) for every sync. It also causes a momentary empty state between delete and insert completion — the UI briefly shows nothing. Upsert (OnConflictStrategy.REPLACE) merges server data into existing rows. For new articles, it inserts; for existing ones, it updates only server-owned fields. Combined with separate columns for client state or a @Query that preserves local flags, this maintains both freshness and local user state without gaps in the UI.

Set Constraints.setRequiredNetworkType(NetworkType.UNMETERED) on the PeriodicWorkRequest. UNMETERED matches Wi-Fi and Ethernet — any connection without data caps. The periodic sync (every 4 h) and image pre-caching can transfer several MB. Running this on cellular would burn the user's data plan silently. However, the on-demand pull-to-refresh sync uses NetworkType.CONNECTED so it works on any network — the user explicitly requested it. FCM-triggered breaking news also uses CONNECTED since the user expects timely breaking news even on cellular.

Add a staleness computed property to the UI model: val isStale = (now - syncedAt) > 6.hours. Map this in the ViewModel when converting ArticleEntity to ArticleUiModel. In the article card ViewHolder, show a small "🕐 6h ago" chip in a muted colour when isStale == true. Alternatively, dim the card slightly or show a yellow border. This gives the user transparency about data freshness without blocking them from reading. The staleness threshold should be a configurable constant, not a magic number.

On first launch, Room is empty. The ViewModel exposes a uiState that can be Loading | Success(articles) | Empty. The Fragment shows a loading shimmer (skeleton UI) while the first sync runs. The sync is triggered immediately on first launch as a high-priority OneTimeWorkRequest with CONNECTED constraint. Once the worker writes articles to Room, the Flow emits and the shimmer is replaced by the feed. If there's no network on first launch, the Fragment shows an "No articles yet — check your connection" empty state with a retry button, which triggers the immediate sync.

The sync_metadata table has one row per category with its own lastSyncAt and etag. The sync worker iterates over all enabled categories in the user's preferences. This allows per-category sync policies: Sports could sync every 30 minutes during a cricket match (detected via server flag in the response), while Opinion syncs once a day. The categories table also stores the user's subscription state — unsubscribed categories are skipped entirely in the sync loop, saving bandwidth. The user changing their category subscriptions in Settings triggers an immediate OneTimeWorkRequest for newly subscribed categories.

Track these metrics in analytics: (1) Offline read rate: % of article opens that happened with no connectivity — a high number validates the investment. (2) Cold start to first article: P50/P95 time from app open to first article visible — should be <300 ms. (3) Sync success rate: % of WorkManager syncs that return SUCCESS vs RETRY/FAILURE. (4) 304 rate: % of sync API calls that return 304 — high is good (efficient). (5) Eviction loss: track when a user tries to open a bookmarked article that was accidentally evicted — this indicates a bug in the eviction exemption logic.

Add a readProgressPercent: Int column to ArticleEntity (0–100). As the user scrolls through the article body, a RecyclerView.OnScrollListener computes the scroll percentage and updates the ViewModel. Debounce writes to Room by 2 seconds to avoid constant DB writes. On article open, the ViewModel loads the stored readProgressPercent and scrolls the RecyclerView to that position. Show a reading progress bar at the bottom of the article card in the feed. Mark isRead = true once readProgressPercent >= 80. This entirely client-side feature requires no server changes and works completely offline.

Room requires a migration strategy whenever the schema version changes. Options: (1) Manual migration: val MIGRATION_1_2 = object : Migration(1, 2) { override fun migrate(db: SupportSQLiteDatabase) { db.execSQL("ALTER TABLE articles ADD COLUMN readProgressPercent INTEGER NOT NULL DEFAULT 0") }} — add this to databaseBuilder.addMigrations(MIGRATION_1_2). (2) Destructive migration: .fallbackToDestructiveMigration() — wipes and recreates all tables. Only acceptable in development or if the data is purely a cache (users won't lose bookmarks with this approach — use option 1 in production). Always write a migration test using MigrationTestHelper to verify the schema transition doesn't corrupt existing data.