Design an Instagram-Style Feed

Offset pagination (page=2&size=20) drifts when new posts are inserted between page fetches — the user sees duplicates or skipped posts. A cursor anchors to a specific post ID or timestamp, so even with concurrent inserts the next page starts from the exact item after the cursor. The trade-off: you can't jump to an arbitrary page, but feeds scroll linearly so this is fine.

PagingSource is the UI-facing source of truth — it reads from Room and emits pages. It knows nothing about the network. RemoteMediator is a boundary-event bridge: it reacts when PagingSource needs data that isn't in Room (APPEND boundary reached), hits the API, writes results into Room, and lets PagingSource naturally pick up the change via Room's reactive invalidation. This separation keeps PagingSource simple (pure Room queries) while RemoteMediator handles the complex network-to-Room sync logic.

The Paging engine tracks unconsumed items ahead. When that count drops below prefetchDistance (default equals pageSize), it triggers an APPEND load. Configure with PagingConfig(pageSize=20, prefetchDistance=5) — the next API call fires when the user is 5 items from the end, giving enough lead time before they scroll there.

An optimistic update applies the expected change immediately without waiting for server confirmation. For likes, this means flipping isLiked and incrementing likeCount in Room the instant the user taps — the heart animation plays with zero latency. The API call runs in the background. On success: no-op. On failure: roll back Room and show a snackbar. This is critical because users expect instant feedback on social interactions — any perceptible delay kills the UX.

The RemoteMediator pattern gives offline support essentially for free: Room is the SSoT. When offline, RemoteMediator.load() throws an IOException and returns MediatorResult.Error, but PagingSource still reads from Room — the user sees the cached feed. Show a "Viewing offline" banner by observing a ConnectivityManager.NetworkCallback. Offline likes are queued via action_queue + WorkManager with a CONNECTED constraint — they sync automatically when connectivity returns.

Paging 3 automatically de-duplicates: it only runs one APPEND at a time, queueing subsequent requests. Additionally: use distinctUntilChanged() on the PagingData Flow to prevent identical pages causing re-emission; Room's PagingSource only emits on actual data changes; DiffUtil in PagingDataAdapter ensures only changed items re-bind. The net result: zero redundant API calls regardless of scroll speed.

Use a single ExoPlayer instance shared across all items — creating one per ViewHolder is prohibitively expensive. Attach a RecyclerView.OnScrollListener that on scroll settle finds the video ViewHolder with the largest visible area (≥50% visible). Detach the player from the old ViewHolder (playerView.player = null, player.stop()), then attach to the new one (playerView.player = player, set MediaItem, prepare(), play()). Release the player in Fragment.onDestroyView() to avoid AudioFocus and codec leaks.

PagingDataAdapter uses a DiffUtil.ItemCallback you provide. When a new page arrives, DiffUtil computes the minimum change set (inserts, removes, moves, changes) on a background thread. Only changed ViewHolders re-bind. When the user likes a post and likeCount changes, only that one item re-binds — the rest stay untouched. This means appending 20 new items animates a smooth insertion at the bottom without any visible jitter on the currently visible items.

Use a LoadStateAdapter attached via adapter.withLoadStateFooter(loadStateAdapter). It automatically shows a spinner while APPEND is loading, a Retry button on error, and hides itself when there's no active load. When RemoteMediator returns MediatorResult.Success(endOfPaginationReached=true), Paging 3 stops triggering APPEND and the footer disappears cleanly.

PagingData Flow lives in the ViewModel — it survives rotation. The Fragment re-subscribes to the same Flow; no API call is re-issued. RecyclerView's LinearLayoutManager saves and restores scroll position automatically via onSaveInstanceState(). Videos: the shared ExoPlayer re-attaches to the newly created PlayerView after the ViewHolder re-binds. Net result: the user sees the same scroll position with zero data fetch on rotation.

A nested horizontal RecyclerView for stories treats the stories row as a single ViewHolder that never properly recycles. It also causes nested scroll conflicts, poor memory usage, and breaks Paging 3's ability to manage a unified list. ConcatAdapter merges StoriesAdapter and PagingDataAdapter into one flat RecyclerView. Stories are item type 0, posts are item type 1. The RecycledViewPool is shared so ViewHolders recycle correctly across the entire merged list.

After RemoteMediator inserts the next page's posts into Room, fire headless Coil requests with memoryCachePolicy=DISABLED and diskCachePolicy=ENABLED. This downloads and decodes images into disk cache without occupying memory. When RecyclerView binds those ViewHolders, Coil hits disk cache (~30ms) instead of network. Gate behind Wi-Fi using NetworkCapabilities.hasTransport(TRANSPORT_WIFI) — never prefetch on cellular.

Call adapter.refresh() from the SwipeRefreshLayout listener. Paging 3 re-triggers RemoteMediator.load(REFRESH), which atomically clears old Room data and inserts fresh posts. Bind the SwipeRefreshLayout's isRefreshing to adapter.loadStateFlow.map { it.refresh is LoadState.Loading }.distinctUntilChanged(). Handle LoadState.Error to show a Snackbar with a Retry. The spinner auto-hides on NotLoading.

On FCM data push (new posts available): check layoutManager.findFirstCompletelyVisibleItemPosition() == 0. If at the top, auto-call adapter.refresh(). Otherwise, show a floating "New Posts ↑" chip above the RecyclerView (a separate View, not a list item). On chip tap: smoothScrollToPosition(0), then call adapter.refresh() inside the scroll listener once position 0 is reached. The chip being outside the list means it has zero impact on DiffUtil or Paging's item accounting.

Before RemoteMediator writes fresh posts to Room on REFRESH, it queries action_queue for all pending LIKE/UNLIKE post IDs. When mapping the API response to PostEntity, for any post in the pending set, it overrides the server's isLiked and likeCount values with the local optimistic state. This way, even if the server returns isLiked=false for a pending like, the UI shows the heart filled until WorkManager successfully syncs.

Override onTrimMemory(level) in your Application class. Priority order for release: (1) TRIM_MEMORY_UI_HIDDEN → trim Coil's memory cache to 50%. (2) TRIM_MEMORY_MODERATE → clear Coil memory cache fully; trim ExoPlayer's buffer (player.setPlaybackParameters to reduce buffering). (3) TRIM_MEMORY_COMPLETE → release ExoPlayer entirely (player.release()), clear any in-memory bitmap pools. Room and disk caches are never evicted here — they survive. On the next foreground event, recreate ExoPlayer lazily.

Use a sealed class FeedItem with subtypes: ImagePost, VideoPost, CarouselPost, AdPost. In PagingDataAdapter override getItemViewType() returning distinct integers per type. Create separate ViewHolder classes with different layouts in onCreateViewHolder(). Room stores all types in one posts table with a mediaType column. Ads come from the API with mediaType=AD — they have a different layout (no like/comment row, "Sponsored" label) and are inserted at server-defined positions in the response.

Coil automatically cancels requests bound via imageView.load(url) when the ImageView is detached (which happens on recycle). If using the ImageLoader manually, store the Disposable in the ViewHolder and call disposable.dispose() in Adapter.onViewRecycled(holder). For Glide, binding to the Fragment lifecycle via Glide.with(fragment) handles cancellation automatically when the Fragment is stopped or destroyed.

Use an in-memory Room database (Room.inMemoryDatabaseBuilder) and a fake API implementation that returns controlled responses. Call mediator.load(LoadType.REFRESH, pagingState) directly and assert: (1) MediatorResult.Success returned; (2) Room posts table contains expected entities; (3) remote_keys table has the correct cursor. Test error path: fake API throws IOException, assert MediatorResult.Error and Room is unchanged. Test the action_queue merge: pre-populate queue with a pending LIKE, verify the entity written to Room has isLiked=true even when API returns isLiked=false.

The server handles ranking — the client's job is to: (1) Send implicit engagement signals (view time per post, scroll speed, re-views) to a telemetry endpoint. Batch these in memory and flush every 30 seconds or on app background. (2) Receive a ranking experiment assignment via the API response header (X-Feed-Experiment: rankv2) or a remote config SDK call. (3) Store the assignment in DataStore and include it in every feed API request header so the server serves the appropriate ranked feed. The client never runs ranking itself — it provides signal inputs and receives the ranked output.