This document defines the optimal architecture for saved articles sync and display in android-phoenix, addressing parallel batch downloading, Room persistence, Kotlin coroutines state management, and Compose loading patterns across multiple cache layers.
┌─────────────────────────────────────────────────────────────────────────────┐
│ SYNC FLOW │
└─────────────────────────────────────────────────────────────────────────────┘
┌──────────────┐ ┌──────────────────┐ ┌─────────────────────────────┐
│ UI Layer │ │ SavedManager │ │ AssetSynchronizer │
│ │────▶│ │────▶│ │
│ syncCache() │ │ syncMutex.lock │ │ mutex.lock │
└──────────────┘ └────────┬─────────┘ └─────────────┬───────────────┘
│ │
▼ ▼
┌─────────────────┐ ┌───────────────────────────┐
│ _syncState = │ │ 1. ops.deleteQueuedItems │
│ Syncing │ │ 2. ops.addPendingSaves │
└─────────────────┘ │ 3. ops.removePendingUnsave│
└─────────────┬─────────────┘
│
▼
┌────────────────────────────────────────────────┐
│ GraphQLReadingListRepository │
│ downloadFromReadingList() │
│ │
│ ┌─────────────┐ ┌───────────────────────┐ │
│ │ Page 1 │───▶│ Page 2 │──┼──▶ ...
│ │ (50 items) │ │ (50 items) │ │
│ └─────────────┘ └───────────────────────┘ │
│ │
│ Handle 304 Not Modified: │
│ return (skipDelete=true, emptyList) │
└───────────────────────────┬────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ PARALLEL BATCH DOWNLOAD │
│ │
│ downloadedAssetIndexList.chunked(BATCH_SIZE=10) │
│ │
│ Semaphore(MAX_CONCURRENT_BATCHES=3) │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Batch 1 │ │ Batch 2 │ │ Batch 3 │ ... (parallel with semaphore) │
│ │ 10 items │ │ 10 items │ │ 10 items │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ ops.downloadAssets(batch) ──▶ repository.fetchListAndSave │ │
│ └─────────────────────────────────────────────────────────────┘ │
└───────────────────────────────┬─────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ DUAL PERSISTENCE │
│ │
│ ops.addAllFromReadingList(assetList, savedDates) │
│ │
│ ┌────────────────────┐ ┌────────────────────────────┐ │
│ │ Room DB │ │ FreshItemsFlow │ │
│ │ │ │ (Instant emission) │ │
│ │ savedArticleDao │ │ │ │
│ │ .insertOrReplaceAll│ │ _freshItemsFlow.emit(items)│ │
│ │ │ │ │ │
│ └─────────┬──────────┘ └─────────────┬──────────────┘ │
│ │ │ │
│ │ merge(freshFlow, roomFlow) │ │
│ │◀──────────────────────────────────┘ │
│ │ .distinctUntilChanged() │
└─────────────┼───────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ UI UPDATE │
│ │
│ getSavedArticlesFlow() merges: │
│ - freshItemsFlow (instant, bypasses Room delay) │
│ - roomFlow (source of truth, ~16ms delay) │
│ │
│ UI receives items immediately when batch completes │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐
│ LOGIN FLOW │
└─────────────────────────────────────────────────────────────────────────────┘
User Login ──▶ hasMeaningfullyChangedFlow emits
│
▼
┌─────────────────────────┐
│ ActivityGridViewModel │
│ loadingCoordinator │
│ .configureAuth() │
└───────────┬─────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ handleAuthChange() │
│ │
│ if (!isUserRegistered) reset() ──▶ Clear state │
│ else tryLoad(LoadType.FULL) ──▶ Start sync │
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ SavedManager.syncCacheSuspending() │
│ │
│ syncMutex.withLock { │
│ _syncState = Syncing │
│ assetSynchronizer.sync( │
│ onFirstBatchReady = { _syncState = Synced } │
│ ) │
│ } │
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ Room auto-emits via InvalidationTracker │
│ OR freshItemsFlow emits immediately │
│ │
│ combine(savedItemsFlow, syncState) emits new state │
│ │
│ UI: Loading ──▶ Content │
└─────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐
│ LOGOUT FLOW │
└─────────────────────────────────────────────────────────────────────────────┘
User Logout ──▶ hasMeaningfullyChangedFlow emits
│
┌─────────────┴──────────────────────────────┐
│ │
▼ ▼
┌───────────────────────────┐ ┌──────────────────────────────────┐
│ Clear ETag Cache │ │ SavedManager.deleteCache() │
│ │ │ │
│ SubauthListener clears │ │ 1. ops.deleteCache() │
│ ProgramHeadersHolder_* │ │ 2. savedArticleDao.clearAll() │
│ from SharedPreferences │ │ 3. flyWeight.deleteFile() │
│ │ │ 4. _syncState = NotSynced │
└───────────────────────────┘ └──────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐
│ 4-LAYER CACHE ARCHITECTURE │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐
│ LAYER 1: Apollo HTTP Cache (ETag/304) │
│ ══════════════════════════════════════ │
│ │
│ Purpose: Bandwidth optimization - skip download if server data unchanged │
│ │
│ Request: If-None-Match: <etag> │
│ Response: 304 Not Modified (no body) OR 200 + new data │
│ │
│ Storage: SharedPreferences (ProgramHeadersHolder_*) │
│ Cleared: SubauthListener.onLogout() │
│ │
│ ⚠️ PROBLEM: If not cleared on logout, next login gets 304 with empty cache │
│ SOLUTION: Clear ETag headers atomically with local cache │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ LAYER 2: Room Database (SQLite) │
│ ═══════════════════════════════ │
│ │
│ Purpose: Persistent storage, fast queries, auto-invalidation │
│ │
│ Table: saved_articles │
│ Columns: url (PK), uri, saved_date, title, image_url, summary, etc. │
│ │
│ Key Methods: │
│ - pagingSource(): PagingSource<Int, SavedArticleEntity> (for pagination)│
│ - getSavedArticlesFlow(limit): Flow<List<SavedArticleEntity>> (reactive) │
│ │
│ Auto-invalidation: Room's InvalidationTracker notifies Flows (~16ms delay) │
│ Cleared: savedArticleDao.clearAll() │
│ │
│ ✅ BENEFIT: Source of truth, survives process death │
│ ⚠️ CONCERN: InvalidationTracker delay causes brief "empty" flash │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ LAYER 3: FreshItemsFlow (In-Memory MutableSharedFlow) │
│ ════════════════════════════════════════════════════ │
│ │
│ Purpose: Bypass Room delay, instant UI updates on batch insert │
│ │
│ Implementation: │
│ private val _freshItemsFlow = MutableSharedFlow<List<SavedArticleEntity>>(│
│ replay = 1, │
│ extraBufferCapacity = 10 │
│ ) │
│ │
│ Emission: Called immediately after savedArticleDao.insertOrReplaceAll() │
│ │
│ Merge Pattern: │
│ merge(freshItemsFlow, roomFlow).distinctUntilChanged() │
│ │
│ ✅ BENEFIT: UI sees data instantly, no 16ms delay │
│ ✅ BENEFIT: Room still source of truth once InvalidationTracker fires │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ LAYER 4: SavedListFlyWeight (In-Memory + JSON File) │
│ ═══════════════════════════════════════════════════ │
│ │
│ Purpose: Track pending operations (add/delete queues) for offline support │
│ │
│ State: syncedItems, itemsToAdd, itemsToDelete, itemsToDeleteQueue │
│ Persistence: JSON file on disk (survives process death) │
│ Cleared: flyWeight.deleteFile() │
│ │
│ ✅ BENEFIT: Tracks operations that haven't synced to server yet │
│ ⚠️ NOTE: Being phased out - Room should be single source of truth │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐
│ CACHE INVALIDATION SEQUENCE │
└─────────────────────────────────────────────────────────────────────────────┘
On Logout - ALL LAYERS MUST CLEAR ATOMICALLY:
1. ETag Headers ──▶ SubauthListener clears SharedPreferences
2. Room Database ──▶ savedArticleDao.clearAll()
3. FreshItemsFlow ──▶ Emit empty list
4. FlyWeight ──▶ flyWeight.deleteFile()
5. SyncState ──▶ _syncState = NotSynced
If ANY layer retains data while others clear ──▶ CACHE INCOHERENCE BUG
| Component | Layer | Responsibility |
|---|---|---|
| SavedManager | Facade | Public API, sync state machine, exposes Flows |
| AssetSynchronizer | Sync Engine | Parallel batch download, progress tracking, mutex protection |
| LowLevelOperations | Operations | CRUD, bridges repositories, emits to freshItemsFlow |
| GraphQLReadingListRepository | Network | Paginated GraphQL, 304/ETag handling |
| SavedArticleDao | Persistence | Room queries, auto-invalidating Flows/PagingSource |
| SavedListFlyWeight | Queue | Pending operation tracking (legacy, being deprecated) |
┌───────────────┐
App Start ──▶│ NotSynced │◀─────────────────────┐
└───────┬───────┘ │
│ │
syncCacheSuspending() deleteCache()
│ │
▼ │
┌───────────────┐ │
│ Syncing │──────────────────────┤
└───────┬───────┘ │
│ │
onFirstBatchReady() │
│ │
▼ │
┌───────────────┐ │
│ Synced │──────────────────────┘
└───────────────┘
sealed class SavedScreenState {
data object Loading : SavedScreenState()
data class Content(val items: List<UserStoredStoryListItem>) : SavedScreenState()
data object Empty : SavedScreenState()
}
val screenState: StateFlow<SavedScreenState> = combine(
savedManager.getSavedArticlesFlow(limit),
savedManager.syncState
) { items, syncState ->
when {
items.isNotEmpty() -> SavedScreenState.Content(items.map { it.toUI() })
syncState != SavedSyncState.Synced -> SavedScreenState.Loading
else -> SavedScreenState.Empty
}
}.stateIn(viewModelScope, SharingStarted.Eagerly, SavedScreenState.Loading)Key Decisions:
- Content takes precedence - If Room has data, show it immediately regardless of sync state
- Loading only when empty AND syncing - Don't flash loading if cache exists
- Empty only when sync confirms - Never show empty until sync says "done with 0 items"
- Eagerly started - Flow subscription starts immediately to catch first emissions
// ActivityGridViewModel
val savedGridItemsFlow: StateFlow<List<ActivityGridItem>> =
savedManager.getSavedArticlesFlow(ACTIVITY_GRID_DISPLAY_LIMIT) // 24
.map { entities -> entities.map { it.toActivityGridItem() } }
.stateIn(viewModelScope, SharingStarted.Eagerly, emptyList())
val savedGridDisplayState: StateFlow<SavedGridDisplayState> = combine(
savedGridItemsFlow,
savedManager.syncState
) { items, syncState ->
when {
items.isNotEmpty() -> SavedGridDisplayState.Content(items)
syncState != SavedSyncState.Synced -> SavedGridDisplayState.Loading
else -> SavedGridDisplayState.Empty
}
}.stateIn(viewModelScope, SharingStarted.Lazily, SavedGridDisplayState.Loading)// SavedViewModel - Option A: Manual PagingData (Recommended)
val savedItems: StateFlow<PagingData<UserStoredStoryListItem>> =
savedManager.getSavedArticlesFlow(SAVED_ITEMS_LIMIT) // 500
.map { entities ->
PagingData.from(entities.map { it.toUserStoredStoryListItem() })
}
.stateIn(viewModelScope, SharingStarted.Eagerly, PagingData.empty())
// SavedViewModel - Option B: Room PagingSource (Has timing issues)
val savedItems = savedManager.getSavedArticlePager(PAGE_SIZE)
.flow
.map { pagingData -> pagingData.map { it.toUserStoredStoryListItem() } }
.cachedIn(viewModelScope) // ⚠️ cachedIn can cause stale cache on auth changeRecommendation: Use Option A because:
getSavedArticlesFlowmergesfreshItemsFlowfor instant updates- No
cachedInmeans no stale cache issues on auth change PagingData.from()converts List to PagingData for LazyPagingItems compatibility
| Decision | Problem It Solves | How It Helps |
|---|---|---|
| Merge freshItemsFlow + roomFlow | Room InvalidationTracker has ~16ms delay | UI sees data instantly when batch completes |
| Semaphore-limited parallel batches | Network congestion, memory pressure | BATCH_SIZE=10, MAX_CONCURRENT=3 balances speed vs resources |
| NonCancellable sync context | User navigates away mid-sync | Sync completes even if ViewModel cleared |
| onFirstBatchReady callback | Users wait too long for first content | Shows partial data while rest downloads |
| StateFlow with Eagerly | Race condition: subscribe after first emit | Collector active before data arrives |
| Clear ETag on logout | 304 response with empty local cache | Fresh fetch for new user session |
| PagingData.from() instead of PagingSource | PagingSource timing inconsistent with freshItemsFlow | Both patterns use same merged Flow |
| combine(items, syncState) for screen state | Multiple Flows cause state flickering | Single derived state prevents intermediate states |
// AssetSynchronizer.kt
internal suspend fun syncAssets(
downloadedAssetIndexList: List<SavedAssetIndex>,
onFirstBatchReady: () -> Unit = {}
) {
val assetsToDownload = downloadedAssetIndexList - savedArticleList.syncedItems
if (assetsToDownload.isEmpty()) {
onFirstBatchReady()
return
}
val batches = assetsToDownload.chunked(BATCH_SIZE)
val semaphore = Semaphore(MAX_CONCURRENT_BATCHES)
val totalDownloaded = AtomicInteger(0)
val firstBatchFired = AtomicBoolean(false)
coroutineScope {
batches.mapIndexed { index, batch ->
async {
semaphore.withPermit {
val (assetList, success) = ops.downloadAssets(batch)
if (success && assetList.isNotEmpty()) {
// Write to Room + emit to freshItemsFlow
ops.addAllFromReadingList(assetList, batch.map { it.savedDate })
// Track progress
val downloaded = totalDownloaded.addAndGet(assetList.size)
publishProgress(downloaded, assetsToDownload.size)
// Signal first batch ready (UI can start showing content)
if (firstBatchFired.compareAndSet(false, true)) {
onFirstBatchReady()
}
}
}
}
}.awaitAll()
}
}// SavedManager.kt
fun getSavedArticlesFlow(limit: Int): Flow<List<SavedArticleEntity>> {
// Instant updates from batch inserts (bypasses Room delay)
val freshFlow: Flow<List<SavedArticleEntity>> = ops.freshItemsFlow
.map { items -> items.take(limit) }
// Source of truth from Room (has ~16ms delay)
val roomFlow: Flow<List<SavedArticleEntity>> = savedArticleDao.getSavedArticlesFlow(limit)
// Merge: UI gets whichever emits first, dedup prevents double-render
return merge(freshFlow, roomFlow).distinctUntilChanged()
}
// LowLevelOperations.kt
suspend fun addAllFromReadingList(assets: List<Asset>, savedDates: List<String>) {
val roomEntities = assets.mapIndexed { index, asset ->
asset.toSavedArticleEntity(savedDates[index])
}
// Write to Room
savedArticleDao.insertOrReplaceAll(roomEntities)
// IMMEDIATELY emit to freshItemsFlow (UI sees data now, not after 16ms)
_freshItemsFlow.emit(roomEntities)
}// SavedManager.kt
suspend fun deleteCache() {
withContext(ioDispatcher) {
// 1. Clear all layers atomically
ops.deleteCache() // Asset files + FlyWeight
savedArticleDao.clearAll() // Room
ops.emitFreshItems(emptyList()) // Clear freshItemsFlow
// 2. Update state LAST (UI transitions to NotSynced)
_syncState.value = SavedSyncState.NotSynced
}
}
// SubauthListener (separate component, must coordinate)
override fun onLogout(logoutSource: LogoutSource) {
// Clear ETag headers so next login gets 200, not 304
val keysToRemove = sharedPreferences.all.keys.filter {
it.startsWith("ProgramHeadersHolder_")
}
sharedPreferences.edit {
keysToRemove.forEach { remove(it) }
}
}// SavedContent.kt
@Composable
fun SavedContent(viewModel: SavedViewModel = hiltViewModel()) {
val screenState by viewModel.screenState.collectAsState()
val savedItems = viewModel.savedItems.collectAsLazyPagingItems()
when (val state = screenState) {
is SavedScreenState.Loading -> {
CircularProgressIndicator()
}
is SavedScreenState.Empty -> {
EmptyState("You have no saved content yet")
}
is SavedScreenState.Content -> {
// Use LazyPagingItems for efficient list rendering
LazyColumn {
items(
count = savedItems.itemCount,
key = savedItems.itemKey { it.uri }
) { index ->
savedItems[index]?.let { item ->
SavedItemRow(item)
}
}
}
}
}
}- Login triggers sync automatically via auth subscription
- First batch appears within 2 seconds of login
- Progress indicator shows during multi-batch sync
- All batches download (not just first 10-12 items)
- Logout clears all 4 cache layers atomically
- Login after logout gets HTTP 200 (not 304)
- Different user login shows different user's data
- Same user re-login shows cached data instantly
- Content shows immediately if Room has data
- Loading shows only when syncing AND no cache
- Empty shows only when sync complete with 0 items
- Pull-to-refresh triggers sync and shows indicator
- App kill during sync → resumes correctly on restart
- Network failure during batch → partial data visible, retry works
- Rapid login/logout cycles don't cause race conditions
| File | Purpose |
|---|---|
saved-manager/.../SavedManager.kt |
Public API, state machine |
saved-manager/.../AssetSynchronizer.kt |
Batch download orchestration |
saved-manager/.../LowLevelOperations.kt |
CRUD, freshItemsFlow emission |
saved-manager/.../GraphQLReadingListRepository.kt |
Network, 304 handling |
saved-manager/.../db/SavedArticleDao.kt |
Room queries |
you-tab/.../SavedViewModel.kt |
UI state derivation |
you-tab/.../ActivityGridViewModel.kt |
Grid display state |
you-tab/.../SavedContent.kt |
Compose UI |