The patch view shows new comments in place instead of pinning a snapshot, paginated lists keep their own pages, and `cached()` stays for small lookups, so the ADR now says so.
3.9 KiB
5. Data access and reactivity
Date: 2026-10-28
Status
Accepted
Context
Each app fetches its data in its own way. Desktop caches some reads through
a cached() helper, and explorer through its own copy. Neither
reacts to changes in its backend's data: desktop's backend emits only node
status and download progress, its repository list polls while replication is
pending, and radicle-httpd has no push API.
Both apps should react to such changes without disturbing the user. Lists, counts and new comments can show in place, but what the user is reading must not move or change under them, showing that newer data is available until the user applies it.
We also considered events that carry the new data, which ties them to each transport's response shapes; a cache of our own on Svelte stores, which would have to rebuild deduplication, retries and structural sharing; and polling in explorer, which loads the third-party nodes it browses.
Decision
- Core defines the keys of the data shared code reads, by domain identity and nested under the repository, so that one prefix covers all of a repository's data. Each app supplies the fetchers for them.
- A shared query cache on TanStack Query keeps the results and deduplicates
reads. It lives in
@radicle-gui/uibecause it needs Svelte's reactivity, and only the apps' views use it; shared components keep taking props, as in ADR 3. - Route loaders load through the cache and views read from it, so that a view's first data is already cached. Paginated lists keep their own pages, and the cache tells them when to refresh.
- Content-addressed data, keyed by an oid, never changes, so it is cached without expiry and never invalidated.
- Each app forwards its backend's ref updates: the repository and the names of the refs that changed. A pure function in core maps them to the keys they affect, which the cache invalidates and refetches while they are shown. A fetch already in flight when its key is invalidated counts as stale once it settles, since what it read may predate the change.
- The app's own writes invalidate the keys they affect, since a node doesn't announce every write, such as with announcing off or while it is stopped.
- New data that can be added without moving what the user is looking at, such as comments on a diff or rows in the inbox, shows as it arrives, and the view keeps its scroll position. Content the user is reading that newer data would replace, such as an issue's description, renders a pinned snapshot and shows that newer data is available when the cache's data is a different object. Refetches keep unchanged objects identical, so a different object means the data changed.
- Desktop's backend forwards its node's events, and invalidates more broadly when an event names no refs or events may have been missed. It also watches the node's databases for changes other processes make without an event, such as clearing notifications, changing seeding policies or writing a COB without announcing it.
- Explorer has no event source until radicle-httpd can push ref updates. It refetches mutable data on navigation and when the window regains focus, and so does desktop while its node is stopped.
Consequences
- Reads are deduplicated, and updates no longer reset what the user is doing.
- Both apps depend on TanStack Query, which replaces
cached()and explorer's copy of it for the data views show.cached()stays for content-addressed data and for small lookups such as hover cards, which are dropped whenever data changes. Events replace desktop's polling of its repository list. - Desktop's backend has to subscribe to its node's events.
- Explorer views move to runes before they use the cache.
- The rule in
shared/ui/AGENTS.mdthat components keep their local state when props change becomes essential.
Open questions
- Whether httpd grows finer endpoints, such as COB timelines, and a push API for ref updates.