Data fetching and caching

The web app has two data paths and they serve different data.

Data	Path	Cache
Domain data: trainees, plans, forms, tasks, content	Server component reads with `performApi`, passed to client views as props	None. Pages under `(authenticated)` are `force-dynamic`
Identity: session, organizations, members, invitations	TanStack Query calling `authClient`, hydrated from the server	QueryClient
Purchases, notifications, admin lists	TanStack Query through the oRPC utilities	QueryClient
A few on demand libraries inside builders	TanStack Query wrapping a server action	QueryClient

Domain data is not duplicated into the query cache. A client view keeps what it received in local state and updates it from action results.

The QueryClient

modules/shared/lib/query-client.ts:

export function createQueryClient() {
	return new QueryClient({
		defaultOptions: {
			queries: {
				staleTime: 60 * 1000,
				retry: false,
			},
			dehydrate: {
				shouldDehydrateQuery: (query) =>
					defaultShouldDehydrateQuery(query) || query.state.status === "pending",
			},
		},
	});
}

staleTime is one minute.
retry is off. A failed request surfaces at once.
Pending queries are dehydrated too, so a prefetch that has not finished can stream.

Two instances exist:

Where	How it is created
Browser	`ApiClientProvider` keeps one module level singleton
Server	`getServerQueryClient` in `modules/shared/lib/server.ts` is `cache(createQueryClient)`, so one instance per request

Hydration

Session and organization list

(authenticated)/layout.tsx prefetches on the server and dehydrates:

const queryClient = getServerQueryClient();

await queryClient.prefetchQuery({
	queryKey: sessionQueryKey,
	queryFn: () => session,
});

await queryClient.prefetchQuery({
	queryKey: organizationListQueryKey,
	queryFn: getOrganizationList,
});

return <HydrationBoundary state={dehydrate(queryClient)}>...</HydrationBoundary>;

On the client, useSessionQuery() reads the same key with staleTime: Infinity, refetchOnWindowFocus: false and retry: false. The session is therefore fetched once per full page load and then updated by hand:

reloadSession() from useSession() refetches with disableCookieCache and writes the result with setQueryData.
LoginForm invalidates sessionQueryKey after a successful sign in.
setActiveOrganization() patches activeOrganizationId and lastActiveOrganizationId in place.

The active organization boundary

[organizationSlug]/layout.tsx prefetches the organization and wraps its subtree in a second HydrationBoundary:

await queryClient.prefetchQuery({
	queryKey: activeOrganizationQueryKey({ slug: organizationSlug }),
	queryFn: () => organization,
});

return (
	<HydrationBoundary state={dehydrate(queryClient)}>
		<OrgTheme branding={branding} />
		<AppWrapper ...>{children}</AppWrapper>
	</HydrationBoundary>
);

The second boundary is required. React renders the parent layout first, so the parent’s dehydrate() snapshot is taken before the child layout has run its prefetch. Without a boundary of its own, the organization would be missing from the client cache on the first paint. That matters because NavBar gates every menu item except the home item on activeOrganization. With an empty cache the sidebar showed only the first item and filled in the rest after a client refetch. With the boundary the full menu is in the server HTML.

The general rule: with a request scoped server QueryClient, a parent layout’s dehydrated state never includes prefetches made by a child layout. Any layout or page that prefetches must render its own HydrationBoundary. admin/organizations/[id]/page.tsx does.

Three pages prefetch into the server QueryClient without a boundary of their own: [organizationSlug]/settings/billing/page.tsx and (account)/settings/billing/page.tsx (purchases), and (account)/settings/security/page.tsx (accounts and passkeys). Only three files in the app render a HydrationBoundary: the authenticated layout, the organization layout and the admin organization page. By the rule above those three prefetches do not reach the browser cache, and the client components fetch again after mount. The pages still work. The prefetch is just wasted.

useActiveOrganizationQuery sets placeholderData: (previous) => previous, so switching between two studios keeps the old one on screen until the new one arrives. ActiveOrganizationProvider treats placeholder data as not yet loaded when computing loaded.

Query keys

Hand written keys

Key	Defined in	Data
`["user", "session"]`	`modules/auth/lib/api.ts` (`sessionQueryKey`)	better-auth session and user
`["user", "accounts"]`	same (`userAccountQueryKey`)	Linked accounts
`["user", "passkeys"]`	same (`userPasskeyQueryKey`)	Passkeys
`["user", "organizations"]`	`modules/organizations/lib/api.ts` (`organizationListQueryKey`)	Organizations the user belongs to
`["user", "activeOrganization", slugOrId]`	same (`activeOrganizationQueryKey`)	Full organization with members
`["fullOrganization", id]`	same (`fullOrganizationQueryKey`)	Full organization by id, used in settings and admin
`["active-sessions"]`	`modules/settings/components/ActiveSessionsBlock.tsx`	Sessions list
`["food-library", slug]`	`templates/NutritionProgramsView.tsx`, `NutritionBuilder.tsx`, `foods/FoodsView.tsx`, `settings/general/MbpSettings.tsx`	Whole food library, `staleTime` five minutes
`["exercise-library", slug]`	`templates/TrainingProgramsView.tsx`	Whole exercise library, `staleTime` five minutes
`["form-food-catalog", slug]`	`clients/board/CompletedFormResponse.tsx`	Foods referenced by food preference answers
`["form-response-summary", slug, responseId]`	`clients/board/CompletedFormResponse.tsx`, `workboard/detail/blocks/FormResponseBlock.tsx`	AI summary of a submission

Scope every domain key by slug. A user can belong to several studios and the cache outlives navigation between them. The food library key is shared on purpose. Editing a food in the foods page, changing MBP anchors in settings and editing inside the nutrition builder all call invalidateQueries({ queryKey: ["food-library", slug], refetchType: "all" }), so a stale copy never resurfaces in another screen.

oRPC keys

modules/shared/lib/orpc-query-utils.ts exports orpc, built with createTanstackQueryUtils(orpcClient). Each procedure gets queryOptions, mutationOptions and queryKey helpers:

const { data } = useQuery(
	orpc.payments.listPurchases.queryOptions({ input: { organizationId } }),
);

queryClient.invalidateQueries({
	queryKey: orpc.notifications.unreadCount.queryKey({ input: {} }),
});

Procedures the web app calls:

Namespace	Procedures
`payments`	`listPurchases`, `createCheckoutLink`, `changeSubscription`, `createCustomerPortalLink`, `setSeats`
`organizations`	`generateSlug`, `assignCode`, `createLogoUploadUrl`, `createBrandLogoUploadUrl`, `createSelfieExampleUploadUrl`
`users`	`avatarUploadUrl`, `setPassword`
`notifications`	`list`, `unreadCount`, `markRead`, `markAllRead`, `getPreferences`, `updatePreference`
`admin`	`users.list`, `organizations.list`

The router type is modules/shared/lib/orpc-router.generated.d.ts. It is excluded from oxlint in .oxlintrc.json. No script in the frontend repo generates it, and a comment in modules/admin/lib/admin-api.ts says it is kept by hand and lags new procedures. When the backend adds a procedure, update this file before calling it. orpcClient throws if used on the server (RPCLink is not allowed on the server side). On the server use createServerOrpcClient() from bff-server-fetch.ts. The client logs errors through logError, except aborted requests and SERVICE_UNAVAILABLE.

Server side request caching

React cache() deduplicates within one request:

All helpers in modules/auth/lib/server.ts (getSession, getActiveOrganization, getOrganizationList and the rest).
listPurchases in modules/payments/lib/server.ts.
loadSigning in modules/sign/sign-upstream.ts.

This is why three layouts and a page can each call getSession() and only one request reaches the API. resolveStudioContext is not wrapped itself, but the two helpers it calls are. performApi calls are not deduplicated. getStudioAppearance(slug) is called by the organization layout and again by pages that need the brand colour, and each call reads /studios/current. No fetch in the app opts into the Next.js data cache. fetchAuthApi sets cache: "no-store" and the signed client uses default fetch behaviour inside dynamic routes.

Pagination and lists

Pattern	Where
Server pagination with URL params	`clients/page.tsx` reads `?page=`, `?q=` and `?rules=` and requests `pageSize: 20`
Load more through an action	`loadClientsPage` appends pages to the trainee list
Client pagination over a loaded array	`usePagination(items, 25)` with the shared `Pagination` component. See Shared components
Whole library in memory	Exercises (`pageSize: 2000`) and foods (`pageSize: 5000`) for the builders

Pickers that search trainees call a server action per keystroke (for example searchTrainees in the dashboard actions, pageSize: 6). They do not take a snapshot of the whole trainee list.

URL state

nuqs is mounted through NuqsAdapter in the root layout. SocialSigninButton reads invitationId with useQueryState. The trainee board stores its filter rules in ?rules= as JSON and its selection in ?client=. The plan lists use ?scope=training or ?scope=nutrition, and ?ai=1 opens the import wizard.

Overview

Getting set up

Conventions

Backend architecture

Building backend modules

Backend security and access

Background work and delivery

Backend platform features

Backend operations

Backend packages

Data model

JSON shapes

Web app: basics

Web app: data and API

Web app: auth, organizations and billing

Web app: UI foundations

Web app: feature areas

Web app: quality and delivery

Trainee app: foundations

Trainee app: UI

Trainee app: workouts

Trainee app: nutrition

Trainee app: forms, content and tracking

Trainee app: device features

Trainee app: native, build and release

Messaging integrations

Platform integrations

External API and automation

Operations

Data fetching and caching

The QueryClient

Hydration

Session and organization list

The active organization boundary

Query keys

Hand written keys

oRPC keys

Server side request caching

URL state

​The QueryClient

​Hydration

​Session and organization list

​The active organization boundary

​Query keys

​Hand written keys

​oRPC keys

​Server side request caching

​Pagination and lists

​URL state

The QueryClient

Hydration

Session and organization list

The active organization boundary

Query keys

Hand written keys

oRPC keys

Server side request caching

Pagination and lists

URL state