We currently have a de-normalized query cache. What does that mean? We have redundant data all over the place in the frontend (ReactQuery) cache.

Take a user profile as an example. It lives in many locations in our query cache:

ACCOUNT — canonical [ACCOUNT, uid] query via queryAccount(). The primary source of truth for a single account's profile.

LIST_ACCOUNTS — [LIST_ACCOUNTS] returns all known accounts, each with full profile metadata.

DOCUMENT_COMMENTS — [DOCUMENT_COMMENTS, docId] embeds authors: Record<string, HMMetadataPayload> via loadAccounts() in createCommentsResolver().

DOCUMENT_DISCUSSION — [DOCUMENT_DISCUSSION, docId] same pattern — createDiscussionsResolver() embeds author profiles.

BLOCK_DISCUSSIONS — [BLOCK_DISCUSSIONS, docId, blockId] via createCommentsByReferenceResolver(), also embeds authors.

COMMENTS — [COMMENTS, commentId] individual comment lookups that embed author profile.

AUTHORED_COMMENTS — [AUTHORED_COMMENTS, uid] lists comments by an author, embeds profile data.

ACTIVITY_FEED / FEED — each LoadedCommentEvent and LoadedCitationEvent embeds HMContactItem objects containing profile data (name, avatar) for all involved accounts.

ENTITY — [ENTITY, id] for account-type entities, the resource itself contains the profile document with metadata.

RESOLVED_ENTITY — [RESOLVED_ENTITY, id] same as ENTITY but after redirect resolution.

CONTACTS_ACCOUNT — [CONTACTS_ACCOUNT, uid] contact records that include the contact's profile info.

CONTACTS_SUBJECT — [CONTACTS_SUBJECT, uid] reverse contact lookups, also contain profile data.

SEARCH — search results can include account matches with embedded profile metadata.

CAPABILITIES — [CAPABILITIES, uid, ...path] capability entries reference delegate accounts whose profiles may be embedded in the response.

Why is that a problem? When some data changes- such as a profile blob comes in, we don't know what to invalidate. Because the profiles are scattered throughout, we basically need to invalidate the whole world when we see a new user profile come in. This results in extra-heavy data reloading.

Also, when data is duplicated everywhere inside the query cache, it leads to higher memory usage.

Supporting materials

Data Normalization

Problem Solution Scope Rabbit holes No goes Prior art Search Example: { // ...search result data } move document examples

Improve Web Data Loading

Problem Solution export const loader = dataLoader(async (load, request) => { // this server loader is entirely optional! if you skip this, everything will be loaded with AJAX requests like we do in the desktop app const doc = await load(request.params.profileId) await loadEmbeds(load, doc) }) export default const webPageContainer(params => { const { docId } = params return <DocPage id={docId} /> }) function DocPage({id}) { // shared with desktop const doc = useResource(id) return <DocumentContent doc={doc} /> } // deep within document content, it renders this component function ContentEmbed({id}) { // shared with desktop const doc = useResource(id) return <DocumentContent doc={doc} /> } In this example, the webPageContainer wraps the whole page with a client provider that has preloaded all the embed content. This means that the deep useResource in the <ContentEmbed> has access to the data that was preloaded by the server. Scope Rabbit Holes No Goes

Alias & Redirect Cache Implementation Plan (API Router Version - REVISED)

Target Branch: feat/api-router Context Key Changes from Original Plan Strategy: Hook-Layer Metadata + Select Functions Phase 1: Account Aliases Phase 2: Document Redirects (Later) Why This Approach is Better Testing Strategy Migration Path Summary

Normalized Client Data

This will help us conceptually model the Seed data within a given node. In SHM we have several types of things that can change: Query based Normalization Normalized Data Structure One very big problem with this Invalidation

Normalized Data Shape

On the frontend team we are designing the new normalized data structure, which is how the client will organize all data that is received from the API