amethyst: Skill for Claude Code

Account, LocalCache and Feeds

The client state backbone, all headless in commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/ (abbreviated commons/…/ below):

• model/cache/LocalCache.kt — object LocalCache : EventCache(). Every Note / User the client has seen. All logic is in model/cache/EventCache.kt (an open class so tests can build their own); Android and Desktop both use the LocalCache singleton (AppModules.kt, DesktopAppModules.kt).
• model/Account.kt — one Account per signed-in user: ~50 per-feature state objects (kind3FollowList, nip65RelayList, muteList, bookmarkState, …), each exposing .flow.
• feeds/ + viewmodels/ + <feature>/dal/ — feeds: a FeedFilter scans LocalCache, a FeedContentState / FeedViewModel keeps the result live.

relay EVENT ─► EventCache.justConsume ─► Note/User updated, indexes, live.newNote(...)
                     │                                   │
                     ▼                                   ▼
   XState pins its addressable note,            LocalCacheFlow.newEventBundles
   note.flow().metadata → XState.flow           → FeedViewModel → FeedFilter.applyFilter
                     │                                   │
                     └────────► ViewModels / composables ◄┘

Account state objects

Pattern, copied from model/nip51Lists/muteList/MuteListState.kt:

• Pin the note. val muteListNote = cache.getOrCreateAddressableNote(MuteListEvent.createAddress(signer.pubKey)). LocalCache's notes / addressables are LargeSoftCache (weak references), so the state object's field is what keeps its note from being collected.
• Expose one StateFlow. Map muteListNote.flow().metadata.stateFlow → decrypt (private lists go through a per-feature …DecryptionCache such as MuteListDecryptionCache, held next to it in Account as muteListDecryptionCache) → fall back to the AccountSettings backup (settings.backupMuteList) when the event is absent → stateIn(scope, SharingStarted.Eagerly, …).
• Mutation helpers return a signed event — publishing it is the caller's job. MuteListState.hideUser(pubkey) returns a MuteListEvent; Account.hideUser does sendMyPublicAndPrivateOutbox(muteList.hideUser(pubkeyHex)). A state change you never send is invisible to every other client and is lost when the next relay copy arrives.
• Consumers read account.<feature>.flow, never a MutableStateFlow on Account.