Amend ADR 5 for updates shown in place

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.
This commit is contained in:
Rūdolfs Ošiņš
2026-11-20 19:32:16 +01:00
parent bc2914f06b
commit 5937288817
+27 -15
View File
@@ -14,10 +14,10 @@ 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
and counts can refresh in place, but a revision or diff under review must
stay as it is, showing that newer data is available until the user applies
it.
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
@@ -29,24 +29,34 @@ explorer, which loads the third-party nodes it browses.
- 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, deduplicates reads
and applies writes. It lives in `@radicle-gui/ui` because it needs Svelte's
- A shared query cache on TanStack Query keeps the results and deduplicates
reads. It lives in `@radicle-gui/ui` because 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, and paginated lists keep their pages
in it.
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 view whose content the user is acting on, such as a revision under review,
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.
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.
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.
@@ -56,7 +66,9 @@ explorer, which loads the third-party nodes it browses.
- 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. Events replace desktop's polling of its repository list.
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.md` that components keep their local state