LobeHub Data Fetching Architecture

Component → Store useFetchXxx hook → Service → lambdaClient
          ← SWR request state + store data ← response

Layer boundaries

• Services in src/services/ own API calls: .query() for reads, .mutate() for writes. Export a service instance per domain; components and stores do not call lambdaClient directly.
• Store read hooks use useClientDataSWR and return its SWR response, including error and mutate. Sync successful results into the store through the wrapper's supported callback (onSuccess, or onData for the sync wrapper).
• Server lists and details that paint from a local copy go through @/libs/replica instead: the store's useFetchXxx returns slice.useSync(params) (flags only) and the engine writes the store. See the Replica section of zustand.
• Components call these hooks and read store data through selectors. Do not fetch in useEffect or duplicate server data in component useState.
• Use useFetchXxx for read hooks and refreshXxx for cache invalidation.
• For list/detail types, maps, reducers, and shared type sources, use Zustand data structures. For store layout and action classes, use zustand.

Home First Paint and Persistent Caches

When changing home/sidebar first paint or persisted display data, read references/home-first-paint.md. It covers avoiding flicker, reusing persistence, and the user displaySnapshot.ts boundary.

Cache keys and refresh

Reuse the domain key factory in src/libs/swr/keys.ts; define a shared key if the domain has none. Include every parameter that changes the response: entity or parent id, filters, sort, and pagination. Read and refresh must construct the same key.