amethyst/docs/brainstorms/2026-03-17-desktop-cache-architecture-brainstorm.md

# Desktop Cache Architecture — Navigation Persistence

**Date:** 2026-03-17
**Status:** Brainstorm
**Branch:** `feat/desktop-media` (current), will need dedicated branch

## What We're Building

A cache-centric data architecture for Amethyst Desktop that mirrors Android Amethyst's pattern: `DesktopLocalCache` as the single source of truth, `FeedFilter` query objects, and `FeedViewModel` for reactive UI state. This ensures loaded data (notes, metadata, reactions, zaps) survives navigation between screens.

### The Problem

- Feed events live in per-screen `EventCollectionState` inside `remember {}` — destroyed on navigation
- Navigating search → thread → back loses all loaded notes and search results
- Metadata is re-fetched per-screen via `loadMetadataForPubkeys()` even though `DesktopLocalCache` already holds it
- Zaps, reactions, reply counts are tracked per-screen in mutable state — lost on navigation
- UX feels broken: back navigation shows loading spinners for already-seen data

### The Goal

| Before | After |
|--------|-------|
| Screen creates EventCollectionState in `remember` | Screen observes FeedViewModel backed by cache |
| Events stored per-screen, lost on navigation | Events stored in DesktopLocalCache singleton |
| Metadata re-fetched per screen | Metadata cached, available immediately |
| Back navigation = full reload | Back navigation = instant (data in cache) |

## Why This Approach

**Mirror Android Amethyst's cache-centric design** rather than inventing a new repository pattern:

1. **Proven pattern** — Android Amethyst handles millions of events this way
2. **Shared code** — `FeedFilter`, `FeedViewModel`, `FeedContentState` already exist in `commons/`
3. **Future merge safety** — staying aligned with upstream means less divergence
4. **Natural fit** — `DesktopLocalCache` already implements `ICacheProvider` and `ICacheEventStream`

### Android's Architecture (what we're mirroring)

```
Relays → LocalCache (stores ALL events) → ICacheEventStream
                                              ↓
                                    FeedViewModel subscribes
                                              ↓
                                    FeedFilter.feed() queries cache
                                              ↓
                                    FeedContentState (Loading/Loaded/Empty)
                                              ↓
                                    UI collects StateFlow
```

### Desktop's Current Architecture (broken)

```
Relays → Screen composable (EventCollectionState in remember)
              ↓
         UI renders from local state
              ↓
         [navigation] → state destroyed → reload from scratch
```

### Desktop's Target Architecture

```
Relays → DesktopLocalCache (stores ALL events) → DesktopCacheEventStream
                                                      ↓
                                            FeedViewModel subscribes
                                                      ↓
                                            FeedFilter queries cache
                                                      ↓
                                            Screen observes FeedContentState
                                                      ↓
                                            [navigation] → cache persists → instant back
```

## Key Decisions

| Decision | Choice | Rationale |
|----------|--------|-----------|
| Architecture | Cache-centric (mirror Android) | Proven, shared code, merge-safe |
| Migration | Incremental (3 phases) | Each phase is a standalone UX improvement |
| Storage | In-memory only (no disk) | Matches Android, sufficient for navigation persistence |
| Feed queries | FeedFilter pattern from commons | Already exists, well-tested |
| State management | FeedViewModel + FeedContentState | Already in commons, handles Loading/Loaded/Empty |
| Thumbnails | Out of scope | Already survive navigation (singleton cache) |

## Implementation Phases

### Phase 1: Store ALL events in DesktopLocalCache

**Goal:** Make the cache the source of truth instead of per-screen state.

**Changes:**
- `DesktopLocalCache`: Store note events (not just metadata) when received from relays
- Relay subscription handlers: Call `localCache.consume(event)` for ALL event types
- `DesktopCacheEventStream`: Emit to `newEventBundles` / `deletedEventBundles` flows
- Zaps, reactions, reposts: Store relationship data in Note model (like Android)

**What it fixes:** Data accumulates in a singleton — screens can query it on mount.

### Phase 2: Create Desktop FeedFilters

**Goal:** Query the cache instead of holding per-screen event lists.

**Changes:**
- `DesktopGlobalFeedFilter` — queries cache for kind 1 events, sorted by createdAt
- `DesktopFollowingFeedFilter` — queries cache for events from followed users
- `DesktopThreadFilter` — queries cache for root + replies to a note ID
- `DesktopProfileFeedFilter` — queries cache for events by a specific pubkey
- `DesktopBookmarkFeedFilter` — queries cache for bookmarked event IDs

**What it fixes:** Screens get data from cache immediately, no relay round-trip on back navigation.

### Phase 3: Migrate Screens to FeedViewModel

**Goal:** Replace per-screen `EventCollectionState` with shared `FeedViewModel`.

**Changes per screen:**
- Replace `val eventState = remember { EventCollectionState(...) }` with `val viewModel = remember { FeedViewModel(filter, localCache) }`
- Replace `events by eventState.items.collectAsState()` with `feedState by viewModel.feedContent.collectAsState()`
- Remove per-screen relay subscription handlers (cache handles it)
- Remove per-screen zap/reaction/reply tracking (stored in Note model)

**Migration order:** FeedScreen → ThreadScreen → UserProfileScreen → SearchResultsList → BookmarksScreen → ReadsScreen → NotificationsScreen

**What it fixes:** Full navigation persistence, cleaner screen composables, shared ViewModel pattern.

## Existing Code to Reuse

| Component | Location | Status |
|-----------|----------|--------|
| `ICacheProvider` | `commons/model/cache/ICacheProvider.kt` | ✅ Already implemented by DesktopLocalCache |
| `ICacheEventStream` | `commons/model/cache/ICacheEventStream.kt` | ✅ Already implemented by DesktopCacheEventStream |
| `FeedFilter<T>` | `commons/ui/feeds/FeedFilter.kt` | ✅ Ready to subclass |
| `AdditiveFeedFilter<T>` | `commons/ui/feeds/AdditiveFeedFilter.kt` | ✅ Optimized for incremental updates |
| `FeedViewModel` | `commons/viewmodels/FeedViewModel.kt` | ⚠️ May need adaptation for desktop lifecycle |
| `FeedContentState` | `commons/ui/feeds/FeedContentState.kt` | ✅ Ready to use |
| `User` / `Note` models | `commons/model/` | ✅ Already used by DesktopLocalCache |

## Resolved Questions

| Question | Decision | Rationale |
|----------|----------|-----------|
| **ViewModel lifecycle** | App-level singletons | Desktop has no Activity lifecycle. Create ViewModels at startup, keep alive forever. Simple and matches desktop mental model. |
| **Cache eviction** | LRU eviction | Cap cache per type (e.g., 10k notes, 5k users). Desktop has more RAM but still finite. Defensive choice. |
| **Subscription management** | Centralized coordinator | `DesktopRelaySubscriptionsCoordinator` manages all feed subs. Screens request what they need, coordinator deduplicates. Already partially exists. |

## Resolved Questions (continued)

| Question | Decision | Rationale |
|----------|----------|-----------|
| **Event consumption scope** | Full port of Android's consume methods | Future-proof. Port all event kind handlers from Android LocalCache to DesktopLocalCache. |