cokit-cli 1.0.7 → 1.0.9

package/templates/repo/.github/skills/ck-frontend-development/resources/data-fetching.md

@@ -1,767 +1,767 @@
-# Data Fetching Patterns
-
-Modern data fetching using TanStack Query with Suspense boundaries, cache-first strategies, and centralized API services.
-
----
-
-## PRIMARY PATTERN: useSuspenseQuery
-
-### Why useSuspenseQuery?
-
-For **all new components**, use `useSuspenseQuery` instead of regular `useQuery`:
-
-**Benefits:**
-- No `isLoading` checks needed
-- Integrates with Suspense boundaries
-- Cleaner component code
-- Consistent loading UX
-- Better error handling with error boundaries
-
-### Basic Pattern
-
-```typescript
-import { useSuspenseQuery } from '@tanstack/react-query';
-import { myFeatureApi } from '../api/myFeatureApi';
-
-export const MyComponent: React.FC<Props> = ({ id }) => {
-    // No isLoading - Suspense handles it!
-    const { data } = useSuspenseQuery({
-        queryKey: ['myEntity', id],
-        queryFn: () => myFeatureApi.getEntity(id),
-    });
-
-    // data is ALWAYS defined here (not undefined | Data)
-    return <div>{data.name}</div>;
-};
-
-// Wrap in Suspense boundary
-<SuspenseLoader>
-    <MyComponent id={123} />
-</SuspenseLoader>
-```
-
-### useSuspenseQuery vs useQuery
-
-| Feature | useSuspenseQuery | useQuery |
-|---------|------------------|----------|
-| Loading state | Handled by Suspense | Manual `isLoading` check |
-| Data type | Always defined | `Data \| undefined` |
-| Use with | Suspense boundaries | Traditional components |
-| Recommended for | **NEW components** | Legacy code only |
-| Error handling | Error boundaries | Manual error state |
-
-**When to use regular useQuery:**
-- Maintaining legacy code
-- Very simple cases without Suspense
-- Polling with background updates
-
-**For new components: Always prefer useSuspenseQuery**
-
----
-
-## Cache-First Strategy
-
-### Cache-First Pattern Example
-
-**Smart caching** reduces API calls by checking React Query cache first:
-
-```typescript
-import { useSuspenseQuery, useQueryClient } from '@tanstack/react-query';
-import { postApi } from '../api/postApi';
-
-export function useSuspensePost(postId: number) {
-    const queryClient = useQueryClient();
-
-    return useSuspenseQuery({
-        queryKey: ['post', postId],
-        queryFn: async () => {
-            // Strategy 1: Try to get from list cache first
-            const cachedListData = queryClient.getQueryData<{ posts: Post[] }>([
-                'posts',
-                'list'
-            ]);
-
-            if (cachedListData?.posts) {
-                const cachedPost = cachedListData.posts.find(
-                    (post) => post.id === postId
-                );
-
-                if (cachedPost) {
-                    return cachedPost;  // Return from cache!
-                }
-            }
-
-            // Strategy 2: Not in cache, fetch from API
-            return postApi.getPost(postId);
-        },
-        staleTime: 5 * 60 * 1000,      // Consider fresh for 5 minutes
-        gcTime: 10 * 60 * 1000,         // Keep in cache for 10 minutes
-        refetchOnWindowFocus: false,    // Don't refetch on focus
-    });
-}
-```
-
-**Key Points:**
-- Check grid/list cache before API call
-- Avoids redundant requests
-- `staleTime`: How long data is considered fresh
-- `gcTime`: How long unused data stays in cache
-- `refetchOnWindowFocus: false`: User preference
-
----
-
-## Parallel Data Fetching
-
-### useSuspenseQueries
-
-When fetching multiple independent resources:
-
-```typescript
-import { useSuspenseQueries } from '@tanstack/react-query';
-
-export const MyComponent: React.FC = () => {
-    const [userQuery, settingsQuery, preferencesQuery] = useSuspenseQueries({
-        queries: [
-            {
-                queryKey: ['user'],
-                queryFn: () => userApi.getCurrentUser(),
-            },
-            {
-                queryKey: ['settings'],
-                queryFn: () => settingsApi.getSettings(),
-            },
-            {
-                queryKey: ['preferences'],
-                queryFn: () => preferencesApi.getPreferences(),
-            },
-        ],
-    });
-
-    // All data available, Suspense handles loading
-    const user = userQuery.data;
-    const settings = settingsQuery.data;
-    const preferences = preferencesQuery.data;
-
-    return <Display user={user} settings={settings} prefs={preferences} />;
-};
-```
-
-**Benefits:**
-- All queries in parallel
-- Single Suspense boundary
-- Type-safe results
-
----
-
-## Query Keys Organization
-
-### Naming Convention
-
-```typescript
-// Entity list
-['entities', blogId]
-['entities', blogId, 'summary']    // With view mode
-['entities', blogId, 'flat']
-
-// Single entity
-['entity', blogId, entityId]
-
-// Related data
-['entity', entityId, 'history']
-['entity', entityId, 'comments']
-
-// User-specific
-['user', userId, 'profile']
-['user', userId, 'permissions']
-```
-
-**Rules:**
-- Start with entity name (plural for lists, singular for one)
-- Include IDs for specificity
-- Add view mode / relationship at end
-- Consistent across app
-
-### Query Key Examples
-
-```typescript
-// From useSuspensePost.ts
-queryKey: ['post', blogId, postId]
-queryKey: ['posts-v2', blogId, 'summary']
-
-// Invalidation patterns
-queryClient.invalidateQueries({ queryKey: ['post', blogId] });  // All posts for form
-queryClient.invalidateQueries({ queryKey: ['post'] });          // All posts
-```
-
----
-
-## API Service Layer Pattern
-
-### File Structure
-
-Create centralized API service per feature:
-
-```
-features/
-  my-feature/
-    api/
-      myFeatureApi.ts    # Service layer
-```
-
-### Service Pattern (from postApi.ts)
-
-```typescript
-/**
- * Centralized API service for my-feature operations
- * Uses apiClient for consistent error handling
- */
-import apiClient from '@/lib/apiClient';
-import type { MyEntity, UpdatePayload } from '../types';
-
-export const myFeatureApi = {
-    /**
-     * Fetch a single entity
-     */
-    getEntity: async (blogId: number, entityId: number): Promise<MyEntity> => {
-        const { data } = await apiClient.get(
-            `/blog/entities/${blogId}/${entityId}`
-        );
-        return data;
-    },
-
-    /**
-     * Fetch all entities for a form
-     */
-    getEntities: async (blogId: number, view: 'summary' | 'flat'): Promise<MyEntity[]> => {
-        const { data } = await apiClient.get(
-            `/blog/entities/${blogId}`,
-            { params: { view } }
-        );
-        return data.rows;
-    },
-
-    /**
-     * Update entity
-     */
-    updateEntity: async (
-        blogId: number,
-        entityId: number,
-        payload: UpdatePayload
-    ): Promise<MyEntity> => {
-        const { data } = await apiClient.put(
-            `/blog/entities/${blogId}/${entityId}`,
-            payload
-        );
-        return data;
-    },
-
-    /**
-     * Delete entity
-     */
-    deleteEntity: async (blogId: number, entityId: number): Promise<void> => {
-        await apiClient.delete(`/blog/entities/${blogId}/${entityId}`);
-    },
-};
-```
-
-**Key Points:**
-- Export single object with methods
-- Use `apiClient` (axios instance from `@/lib/apiClient`)
-- Type-safe parameters and returns
-- JSDoc comments for each method
-- Centralized error handling (apiClient handles it)
-
----
-
-## Route Format Rules (IMPORTANT)
-
-### Correct Format
-
-```typescript
-// ✅ CORRECT - Direct service path
-await apiClient.get('/blog/posts/123');
-await apiClient.post('/projects/create', data);
-await apiClient.put('/users/update/456', updates);
-await apiClient.get('/email/templates');
-
-// ❌ WRONG - Do NOT add /api/ prefix
-await apiClient.get('/api/blog/posts/123');  // WRONG!
-await apiClient.post('/api/projects/create', data); // WRONG!
-```
-
-**Microservice Routing:**
-- Form service: `/blog/*`
-- Projects service: `/projects/*`
-- Email service: `/email/*`
-- Users service: `/users/*`
-
-**Why:** API routing is handled by proxy configuration, no `/api/` prefix needed.
-
----
-
-## Mutations
-
-### Basic Mutation Pattern
-
-```typescript
-import { useMutation, useQueryClient } from '@tanstack/react-query';
-import { myFeatureApi } from '../api/myFeatureApi';
-import { useMuiSnackbar } from '@/hooks/useMuiSnackbar';
-
-export const MyComponent: React.FC = () => {
-    const queryClient = useQueryClient();
-    const { showSuccess, showError } = useMuiSnackbar();
-
-    const updateMutation = useMutation({
-        mutationFn: (payload: UpdatePayload) =>
-            myFeatureApi.updateEntity(blogId, entityId, payload),
-
-        onSuccess: () => {
-            // Invalidate and refetch
-            queryClient.invalidateQueries({
-                queryKey: ['entity', blogId, entityId]
-            });
-            showSuccess('Entity updated successfully');
-        },
-
-        onError: (error) => {
-            showError('Failed to update entity');
-            console.error('Update error:', error);
-        },
-    });
-
-    const handleUpdate = () => {
-        updateMutation.mutate({ name: 'New Name' });
-    };
-
-    return (
-        <Button
-            onClick={handleUpdate}
-            disabled={updateMutation.isPending}
-        >
-            {updateMutation.isPending ? 'Updating...' : 'Update'}
-        </Button>
-    );
-};
-```
-
-### Optimistic Updates
-
-```typescript
-const updateMutation = useMutation({
-    mutationFn: (payload) => myFeatureApi.update(id, payload),
-
-    // Optimistic update
-    onMutate: async (newData) => {
-        // Cancel outgoing refetches
-        await queryClient.cancelQueries({ queryKey: ['entity', id] });
-
-        // Snapshot current value
-        const previousData = queryClient.getQueryData(['entity', id]);
-
-        // Optimistically update
-        queryClient.setQueryData(['entity', id], (old) => ({
-            ...old,
-            ...newData,
-        }));
-
-        // Return rollback function
-        return { previousData };
-    },
-
-    // Rollback on error
-    onError: (err, newData, context) => {
-        queryClient.setQueryData(['entity', id], context.previousData);
-        showError('Update failed');
-    },
-
-    // Refetch after success or error
-    onSettled: () => {
-        queryClient.invalidateQueries({ queryKey: ['entity', id] });
-    },
-});
-```
-
----
-
-## Advanced Query Patterns
-
-### Prefetching
-
-```typescript
-export function usePrefetchEntity() {
-    const queryClient = useQueryClient();
-
-    return (blogId: number, entityId: number) => {
-        return queryClient.prefetchQuery({
-            queryKey: ['entity', blogId, entityId],
-            queryFn: () => myFeatureApi.getEntity(blogId, entityId),
-            staleTime: 5 * 60 * 1000,
-        });
-    };
-}
-
-// Usage: Prefetch on hover
-<div onMouseEnter={() => prefetch(blogId, id)}>
-    <Link to={`/entity/${id}`}>View</Link>
-</div>
-```
-
-### Cache Access Without Fetching
-
-```typescript
-export function useEntityFromCache(blogId: number, entityId: number) {
-    const queryClient = useQueryClient();
-
-    // Get from cache, don't fetch if missing
-    const directCache = queryClient.getQueryData<MyEntity>(['entity', blogId, entityId]);
-
-    if (directCache) return directCache;
-
-    // Try grid cache
-    const gridCache = queryClient.getQueryData<{ rows: MyEntity[] }>(['entities-v2', blogId]);
-
-    return gridCache?.rows.find(row => row.id === entityId);
-}
-```
-
-### Dependent Queries
-
-```typescript
-// Fetch user first, then user's settings
-const { data: user } = useSuspenseQuery({
-    queryKey: ['user', userId],
-    queryFn: () => userApi.getUser(userId),
-});
-
-const { data: settings } = useSuspenseQuery({
-    queryKey: ['user', userId, 'settings'],
-    queryFn: () => settingsApi.getUserSettings(user.id),
-    // Automatically waits for user to load due to Suspense
-});
-```
-
----
-
-## API Client Configuration
-
-### Using apiClient
-
-```typescript
-import apiClient from '@/lib/apiClient';
-
-// apiClient is a configured axios instance
-// Automatically includes:
-// - Base URL configuration
-// - Cookie-based authentication
-// - Error interceptors
-// - Response transformers
-```
-
-**Do NOT create new axios instances** - use apiClient for consistency.
-
----
-
-## Error Handling in Queries
-
-### onError Callback
-
-```typescript
-import { useMuiSnackbar } from '@/hooks/useMuiSnackbar';
-
-const { showError } = useMuiSnackbar();
-
-const { data } = useSuspenseQuery({
-    queryKey: ['entity', id],
-    queryFn: () => myFeatureApi.getEntity(id),
-
-    // Handle errors
-    onError: (error) => {
-        showError('Failed to load entity');
-        console.error('Load error:', error);
-    },
-});
-```
-
-### Error Boundaries
-
-Combine with Error Boundaries for comprehensive error handling:
-
-```typescript
-import { ErrorBoundary } from 'react-error-boundary';
-
-<ErrorBoundary
-    fallback={<ErrorDisplay />}
-    onError={(error) => console.error(error)}
->
-    <SuspenseLoader>
-        <ComponentWithSuspenseQuery />
-    </SuspenseLoader>
-</ErrorBoundary>
-```
-
----
-
-## Complete Examples
-
-### Example 1: Simple Entity Fetch
-
-```typescript
-import React from 'react';
-import { useSuspenseQuery } from '@tanstack/react-query';
-import { Box, Typography } from '@mui/material';
-import { userApi } from '../api/userApi';
-
-interface UserProfileProps {
-    userId: string;
-}
-
-export const UserProfile: React.FC<UserProfileProps> = ({ userId }) => {
-    const { data: user } = useSuspenseQuery({
-        queryKey: ['user', userId],
-        queryFn: () => userApi.getUser(userId),
-        staleTime: 5 * 60 * 1000,
-    });
-
-    return (
-        <Box>
-            <Typography variant='h5'>{user.name}</Typography>
-            <Typography>{user.email}</Typography>
-        </Box>
-    );
-};
-
-// Usage with Suspense
-<SuspenseLoader>
-    <UserProfile userId='123' />
-</SuspenseLoader>
-```
-
-### Example 2: Cache-First Strategy
-
-```typescript
-import { useSuspenseQuery, useQueryClient } from '@tanstack/react-query';
-import { postApi } from '../api/postApi';
-import type { Post } from '../types';
-
-/**
- * Hook with cache-first strategy
- * Checks grid cache before API call
- */
-export function useSuspensePost(blogId: number, postId: number) {
-    const queryClient = useQueryClient();
-
-    return useSuspenseQuery<Post, Error>({
-        queryKey: ['post', blogId, postId],
-        queryFn: async () => {
-            // 1. Check grid cache first
-            const gridCache = queryClient.getQueryData<{ rows: Post[] }>([
-                'posts-v2',
-                blogId,
-                'summary'
-            ]) || queryClient.getQueryData<{ rows: Post[] }>([
-                'posts-v2',
-                blogId,
-                'flat'
-            ]);
-
-            if (gridCache?.rows) {
-                const cached = gridCache.rows.find(row => row.S_ID === postId);
-                if (cached) {
-                    return cached;  // Reuse grid data
-                }
-            }
-
-            // 2. Not in cache, fetch directly
-            return postApi.getPost(blogId, postId);
-        },
-        staleTime: 5 * 60 * 1000,
-        gcTime: 10 * 60 * 1000,
-        refetchOnWindowFocus: false,
-    });
-}
-```
-
-**Benefits:**
-- Avoids duplicate API calls
-- Instant data if already loaded
-- Falls back to API if not cached
-
-### Example 3: Parallel Fetching
-
-```typescript
-import { useSuspenseQueries } from '@tanstack/react-query';
-
-export const Dashboard: React.FC = () => {
-    const [statsQuery, projectsQuery, notificationsQuery] = useSuspenseQueries({
-        queries: [
-            {
-                queryKey: ['stats'],
-                queryFn: () => statsApi.getStats(),
-            },
-            {
-                queryKey: ['projects', 'active'],
-                queryFn: () => projectsApi.getActiveProjects(),
-            },
-            {
-                queryKey: ['notifications', 'unread'],
-                queryFn: () => notificationsApi.getUnread(),
-            },
-        ],
-    });
-
-    return (
-        <Box>
-            <StatsCard data={statsQuery.data} />
-            <ProjectsList projects={projectsQuery.data} />
-            <Notifications items={notificationsQuery.data} />
-        </Box>
-    );
-};
-```
-
----
-
-## Mutations with Cache Invalidation
-
-### Update Mutation
-
-```typescript
-import { useMutation, useQueryClient } from '@tanstack/react-query';
-import { postApi } from '../api/postApi';
-import { useMuiSnackbar } from '@/hooks/useMuiSnackbar';
-
-export const useUpdatePost = () => {
-    const queryClient = useQueryClient();
-    const { showSuccess, showError } = useMuiSnackbar();
-
-    return useMutation({
-        mutationFn: ({ blogId, postId, data }: UpdateParams) =>
-            postApi.updatePost(blogId, postId, data),
-
-        onSuccess: (data, variables) => {
-            // Invalidate specific post
-            queryClient.invalidateQueries({
-                queryKey: ['post', variables.blogId, variables.postId]
-            });
-
-            // Invalidate list to refresh grid
-            queryClient.invalidateQueries({
-                queryKey: ['posts-v2', variables.blogId]
-            });
-
-            showSuccess('Post updated');
-        },
-
-        onError: (error) => {
-            showError('Failed to update post');
-            console.error('Update error:', error);
-        },
-    });
-};
-
-// Usage
-const updatePost = useUpdatePost();
-
-const handleSave = () => {
-    updatePost.mutate({
-        blogId: 123,
-        postId: 456,
-        data: { responses: { '101': 'value' } }
-    });
-};
-```
-
-### Delete Mutation
-
-```typescript
-export const useDeletePost = () => {
-    const queryClient = useQueryClient();
-    const { showSuccess, showError } = useMuiSnackbar();
-
-    return useMutation({
-        mutationFn: ({ blogId, postId }: DeleteParams) =>
-            postApi.deletePost(blogId, postId),
-
-        onSuccess: (data, variables) => {
-            // Remove from cache manually (optimistic)
-            queryClient.setQueryData<{ rows: Post[] }>(
-                ['posts-v2', variables.blogId],
-                (old) => ({
-                    ...old,
-                    rows: old?.rows.filter(row => row.S_ID !== variables.postId) || []
-                })
-            );
-
-            showSuccess('Post deleted');
-        },
-
-        onError: (error, variables) => {
-            // Rollback - refetch to get accurate state
-            queryClient.invalidateQueries({
-                queryKey: ['posts-v2', variables.blogId]
-            });
-            showError('Failed to delete post');
-        },
-    });
-};
-```
-
----
-
-## Query Configuration Best Practices
-
-### Default Configuration
-
-```typescript
-// In QueryClientProvider setup
-const queryClient = new QueryClient({
-    defaultOptions: {
-        queries: {
-            staleTime: 1000 * 60 * 5,        // 5 minutes
-            gcTime: 1000 * 60 * 10,           // 10 minutes (was cacheTime)
-            refetchOnWindowFocus: false,       // Don't refetch on focus
-            refetchOnMount: false,             // Don't refetch on mount if fresh
-            retry: 1,                          // Retry failed queries once
-        },
-    },
-});
-```
-
-### Per-Query Overrides
-
-```typescript
-// Frequently changing data - shorter staleTime
-useSuspenseQuery({
-    queryKey: ['notifications', 'unread'],
-    queryFn: () => notificationApi.getUnread(),
-    staleTime: 30 * 1000,  // 30 seconds
-});
-
-// Rarely changing data - longer staleTime
-useSuspenseQuery({
-    queryKey: ['form', blogId, 'structure'],
-    queryFn: () => formApi.getStructure(blogId),
-    staleTime: 30 * 60 * 1000,  // 30 minutes
-});
-```
-
----
-
-## Summary
-
-**Modern Data Fetching Recipe:**
-
-1. **Create API Service**: `features/X/api/XApi.ts` using apiClient
-2. **Use useSuspenseQuery**: In components wrapped by SuspenseLoader
-3. **Cache-First**: Check grid cache before API call
-4. **Query Keys**: Consistent naming ['entity', id]
-5. **Route Format**: `/blog/route` NOT `/api/blog/route`
-6. **Mutations**: invalidateQueries after success
-7. **Error Handling**: onError + useMuiSnackbar
-8. **Type Safety**: Type all parameters and returns
-
-**See Also:**
-- [component-patterns.md](component-patterns.md) - Suspense integration
-- [loading-and-error-states.md](loading-and-error-states.md) - SuspenseLoader usage
+# Data Fetching Patterns
+
+Modern data fetching using TanStack Query with Suspense boundaries, cache-first strategies, and centralized API services.
+
+---
+
+## PRIMARY PATTERN: useSuspenseQuery
+
+### Why useSuspenseQuery?
+
+For **all new components**, use `useSuspenseQuery` instead of regular `useQuery`:
+
+**Benefits:**
+- No `isLoading` checks needed
+- Integrates with Suspense boundaries
+- Cleaner component code
+- Consistent loading UX
+- Better error handling with error boundaries
+
+### Basic Pattern
+
+```typescript
+import { useSuspenseQuery } from '@tanstack/react-query';
+import { myFeatureApi } from '../api/myFeatureApi';
+
+export const MyComponent: React.FC<Props> = ({ id }) => {
+    // No isLoading - Suspense handles it!
+    const { data } = useSuspenseQuery({
+        queryKey: ['myEntity', id],
+        queryFn: () => myFeatureApi.getEntity(id),
+    });
+
+    // data is ALWAYS defined here (not undefined | Data)
+    return <div>{data.name}</div>;
+};
+
+// Wrap in Suspense boundary
+<SuspenseLoader>
+    <MyComponent id={123} />
+</SuspenseLoader>
+```
+
+### useSuspenseQuery vs useQuery
+
+| Feature | useSuspenseQuery | useQuery |
+|---------|------------------|----------|
+| Loading state | Handled by Suspense | Manual `isLoading` check |
+| Data type | Always defined | `Data \| undefined` |
+| Use with | Suspense boundaries | Traditional components |
+| Recommended for | **NEW components** | Legacy code only |
+| Error handling | Error boundaries | Manual error state |
+
+**When to use regular useQuery:**
+- Maintaining legacy code
+- Very simple cases without Suspense
+- Polling with background updates
+
+**For new components: Always prefer useSuspenseQuery**
+
+---
+
+## Cache-First Strategy
+
+### Cache-First Pattern Example
+
+**Smart caching** reduces API calls by checking React Query cache first:
+
+```typescript
+import { useSuspenseQuery, useQueryClient } from '@tanstack/react-query';
+import { postApi } from '../api/postApi';
+
+export function useSuspensePost(postId: number) {
+    const queryClient = useQueryClient();
+
+    return useSuspenseQuery({
+        queryKey: ['post', postId],
+        queryFn: async () => {
+            // Strategy 1: Try to get from list cache first
+            const cachedListData = queryClient.getQueryData<{ posts: Post[] }>([
+                'posts',
+                'list'
+            ]);
+
+            if (cachedListData?.posts) {
+                const cachedPost = cachedListData.posts.find(
+                    (post) => post.id === postId
+                );
+
+                if (cachedPost) {
+                    return cachedPost;  // Return from cache!
+                }
+            }
+
+            // Strategy 2: Not in cache, fetch from API
+            return postApi.getPost(postId);
+        },
+        staleTime: 5 * 60 * 1000,      // Consider fresh for 5 minutes
+        gcTime: 10 * 60 * 1000,         // Keep in cache for 10 minutes
+        refetchOnWindowFocus: false,    // Don't refetch on focus
+    });
+}
+```
+
+**Key Points:**
+- Check grid/list cache before API call
+- Avoids redundant requests
+- `staleTime`: How long data is considered fresh
+- `gcTime`: How long unused data stays in cache
+- `refetchOnWindowFocus: false`: User preference
+
+---
+
+## Parallel Data Fetching
+
+### useSuspenseQueries
+
+When fetching multiple independent resources:
+
+```typescript
+import { useSuspenseQueries } from '@tanstack/react-query';
+
+export const MyComponent: React.FC = () => {
+    const [userQuery, settingsQuery, preferencesQuery] = useSuspenseQueries({
+        queries: [
+            {
+                queryKey: ['user'],
+                queryFn: () => userApi.getCurrentUser(),
+            },
+            {
+                queryKey: ['settings'],
+                queryFn: () => settingsApi.getSettings(),
+            },
+            {
+                queryKey: ['preferences'],
+                queryFn: () => preferencesApi.getPreferences(),
+            },
+        ],
+    });
+
+    // All data available, Suspense handles loading
+    const user = userQuery.data;
+    const settings = settingsQuery.data;
+    const preferences = preferencesQuery.data;
+
+    return <Display user={user} settings={settings} prefs={preferences} />;
+};
+```
+
+**Benefits:**
+- All queries in parallel
+- Single Suspense boundary
+- Type-safe results
+
+---
+
+## Query Keys Organization
+
+### Naming Convention
+
+```typescript
+// Entity list
+['entities', blogId]
+['entities', blogId, 'summary']    // With view mode
+['entities', blogId, 'flat']
+
+// Single entity
+['entity', blogId, entityId]
+
+// Related data
+['entity', entityId, 'history']
+['entity', entityId, 'comments']
+
+// User-specific
+['user', userId, 'profile']
+['user', userId, 'permissions']
+```
+
+**Rules:**
+- Start with entity name (plural for lists, singular for one)
+- Include IDs for specificity
+- Add view mode / relationship at end
+- Consistent across app
+
+### Query Key Examples
+
+```typescript
+// From useSuspensePost.ts
+queryKey: ['post', blogId, postId]
+queryKey: ['posts-v2', blogId, 'summary']
+
+// Invalidation patterns
+queryClient.invalidateQueries({ queryKey: ['post', blogId] });  // All posts for form
+queryClient.invalidateQueries({ queryKey: ['post'] });          // All posts
+```
+
+---
+
+## API Service Layer Pattern
+
+### File Structure
+
+Create centralized API service per feature:
+
+```
+features/
+  my-feature/
+    api/
+      myFeatureApi.ts    # Service layer
+```
+
+### Service Pattern (from postApi.ts)
+
+```typescript
+/**
+ * Centralized API service for my-feature operations
+ * Uses apiClient for consistent error handling
+ */
+import apiClient from '@/lib/apiClient';
+import type { MyEntity, UpdatePayload } from '../types';
+
+export const myFeatureApi = {
+    /**
+     * Fetch a single entity
+     */
+    getEntity: async (blogId: number, entityId: number): Promise<MyEntity> => {
+        const { data } = await apiClient.get(
+            `/blog/entities/${blogId}/${entityId}`
+        );
+        return data;
+    },
+
+    /**
+     * Fetch all entities for a form
+     */
+    getEntities: async (blogId: number, view: 'summary' | 'flat'): Promise<MyEntity[]> => {
+        const { data } = await apiClient.get(
+            `/blog/entities/${blogId}`,
+            { params: { view } }
+        );
+        return data.rows;
+    },
+
+    /**
+     * Update entity
+     */
+    updateEntity: async (
+        blogId: number,
+        entityId: number,
+        payload: UpdatePayload
+    ): Promise<MyEntity> => {
+        const { data } = await apiClient.put(
+            `/blog/entities/${blogId}/${entityId}`,
+            payload
+        );
+        return data;
+    },
+
+    /**
+     * Delete entity
+     */
+    deleteEntity: async (blogId: number, entityId: number): Promise<void> => {
+        await apiClient.delete(`/blog/entities/${blogId}/${entityId}`);
+    },
+};
+```
+
+**Key Points:**
+- Export single object with methods
+- Use `apiClient` (axios instance from `@/lib/apiClient`)
+- Type-safe parameters and returns
+- JSDoc comments for each method
+- Centralized error handling (apiClient handles it)
+
+---
+
+## Route Format Rules (IMPORTANT)
+
+### Correct Format
+
+```typescript
+// ✅ CORRECT - Direct service path
+await apiClient.get('/blog/posts/123');
+await apiClient.post('/projects/create', data);
+await apiClient.put('/users/update/456', updates);
+await apiClient.get('/email/templates');
+
+// ❌ WRONG - Do NOT add /api/ prefix
+await apiClient.get('/api/blog/posts/123');  // WRONG!
+await apiClient.post('/api/projects/create', data); // WRONG!
+```
+
+**Microservice Routing:**
+- Form service: `/blog/*`
+- Projects service: `/projects/*`
+- Email service: `/email/*`
+- Users service: `/users/*`
+
+**Why:** API routing is handled by proxy configuration, no `/api/` prefix needed.
+
+---
+
+## Mutations
+
+### Basic Mutation Pattern
+
+```typescript
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { myFeatureApi } from '../api/myFeatureApi';
+import { useMuiSnackbar } from '@/hooks/useMuiSnackbar';
+
+export const MyComponent: React.FC = () => {
+    const queryClient = useQueryClient();
+    const { showSuccess, showError } = useMuiSnackbar();
+
+    const updateMutation = useMutation({
+        mutationFn: (payload: UpdatePayload) =>
+            myFeatureApi.updateEntity(blogId, entityId, payload),
+
+        onSuccess: () => {
+            // Invalidate and refetch
+            queryClient.invalidateQueries({
+                queryKey: ['entity', blogId, entityId]
+            });
+            showSuccess('Entity updated successfully');
+        },
+
+        onError: (error) => {
+            showError('Failed to update entity');
+            console.error('Update error:', error);
+        },
+    });
+
+    const handleUpdate = () => {
+        updateMutation.mutate({ name: 'New Name' });
+    };
+
+    return (
+        <Button
+            onClick={handleUpdate}
+            disabled={updateMutation.isPending}
+        >
+            {updateMutation.isPending ? 'Updating...' : 'Update'}
+        </Button>
+    );
+};
+```
+
+### Optimistic Updates
+
+```typescript
+const updateMutation = useMutation({
+    mutationFn: (payload) => myFeatureApi.update(id, payload),
+
+    // Optimistic update
+    onMutate: async (newData) => {
+        // Cancel outgoing refetches
+        await queryClient.cancelQueries({ queryKey: ['entity', id] });
+
+        // Snapshot current value
+        const previousData = queryClient.getQueryData(['entity', id]);
+
+        // Optimistically update
+        queryClient.setQueryData(['entity', id], (old) => ({
+            ...old,
+            ...newData,
+        }));
+
+        // Return rollback function
+        return { previousData };
+    },
+
+    // Rollback on error
+    onError: (err, newData, context) => {
+        queryClient.setQueryData(['entity', id], context.previousData);
+        showError('Update failed');
+    },
+
+    // Refetch after success or error
+    onSettled: () => {
+        queryClient.invalidateQueries({ queryKey: ['entity', id] });
+    },
+});
+```
+
+---
+
+## Advanced Query Patterns
+
+### Prefetching
+
+```typescript
+export function usePrefetchEntity() {
+    const queryClient = useQueryClient();
+
+    return (blogId: number, entityId: number) => {
+        return queryClient.prefetchQuery({
+            queryKey: ['entity', blogId, entityId],
+            queryFn: () => myFeatureApi.getEntity(blogId, entityId),
+            staleTime: 5 * 60 * 1000,
+        });
+    };
+}
+
+// Usage: Prefetch on hover
+<div onMouseEnter={() => prefetch(blogId, id)}>
+    <Link to={`/entity/${id}`}>View</Link>
+</div>
+```
+
+### Cache Access Without Fetching
+
+```typescript
+export function useEntityFromCache(blogId: number, entityId: number) {
+    const queryClient = useQueryClient();
+
+    // Get from cache, don't fetch if missing
+    const directCache = queryClient.getQueryData<MyEntity>(['entity', blogId, entityId]);
+
+    if (directCache) return directCache;
+
+    // Try grid cache
+    const gridCache = queryClient.getQueryData<{ rows: MyEntity[] }>(['entities-v2', blogId]);
+
+    return gridCache?.rows.find(row => row.id === entityId);
+}
+```
+
+### Dependent Queries
+
+```typescript
+// Fetch user first, then user's settings
+const { data: user } = useSuspenseQuery({
+    queryKey: ['user', userId],
+    queryFn: () => userApi.getUser(userId),
+});
+
+const { data: settings } = useSuspenseQuery({
+    queryKey: ['user', userId, 'settings'],
+    queryFn: () => settingsApi.getUserSettings(user.id),
+    // Automatically waits for user to load due to Suspense
+});
+```
+
+---
+
+## API Client Configuration
+
+### Using apiClient
+
+```typescript
+import apiClient from '@/lib/apiClient';
+
+// apiClient is a configured axios instance
+// Automatically includes:
+// - Base URL configuration
+// - Cookie-based authentication
+// - Error interceptors
+// - Response transformers
+```
+
+**Do NOT create new axios instances** - use apiClient for consistency.
+
+---
+
+## Error Handling in Queries
+
+### onError Callback
+
+```typescript
+import { useMuiSnackbar } from '@/hooks/useMuiSnackbar';
+
+const { showError } = useMuiSnackbar();
+
+const { data } = useSuspenseQuery({
+    queryKey: ['entity', id],
+    queryFn: () => myFeatureApi.getEntity(id),
+
+    // Handle errors
+    onError: (error) => {
+        showError('Failed to load entity');
+        console.error('Load error:', error);
+    },
+});
+```
+
+### Error Boundaries
+
+Combine with Error Boundaries for comprehensive error handling:
+
+```typescript
+import { ErrorBoundary } from 'react-error-boundary';
+
+<ErrorBoundary
+    fallback={<ErrorDisplay />}
+    onError={(error) => console.error(error)}
+>
+    <SuspenseLoader>
+        <ComponentWithSuspenseQuery />
+    </SuspenseLoader>
+</ErrorBoundary>
+```
+
+---
+
+## Complete Examples
+
+### Example 1: Simple Entity Fetch
+
+```typescript
+import React from 'react';
+import { useSuspenseQuery } from '@tanstack/react-query';
+import { Box, Typography } from '@mui/material';
+import { userApi } from '../api/userApi';
+
+interface UserProfileProps {
+    userId: string;
+}
+
+export const UserProfile: React.FC<UserProfileProps> = ({ userId }) => {
+    const { data: user } = useSuspenseQuery({
+        queryKey: ['user', userId],
+        queryFn: () => userApi.getUser(userId),
+        staleTime: 5 * 60 * 1000,
+    });
+
+    return (
+        <Box>
+            <Typography variant='h5'>{user.name}</Typography>
+            <Typography>{user.email}</Typography>
+        </Box>
+    );
+};
+
+// Usage with Suspense
+<SuspenseLoader>
+    <UserProfile userId='123' />
+</SuspenseLoader>
+```
+
+### Example 2: Cache-First Strategy
+
+```typescript
+import { useSuspenseQuery, useQueryClient } from '@tanstack/react-query';
+import { postApi } from '../api/postApi';
+import type { Post } from '../types';
+
+/**
+ * Hook with cache-first strategy
+ * Checks grid cache before API call
+ */
+export function useSuspensePost(blogId: number, postId: number) {
+    const queryClient = useQueryClient();
+
+    return useSuspenseQuery<Post, Error>({
+        queryKey: ['post', blogId, postId],
+        queryFn: async () => {
+            // 1. Check grid cache first
+            const gridCache = queryClient.getQueryData<{ rows: Post[] }>([
+                'posts-v2',
+                blogId,
+                'summary'
+            ]) || queryClient.getQueryData<{ rows: Post[] }>([
+                'posts-v2',
+                blogId,
+                'flat'
+            ]);
+
+            if (gridCache?.rows) {
+                const cached = gridCache.rows.find(row => row.S_ID === postId);
+                if (cached) {
+                    return cached;  // Reuse grid data
+                }
+            }
+
+            // 2. Not in cache, fetch directly
+            return postApi.getPost(blogId, postId);
+        },
+        staleTime: 5 * 60 * 1000,
+        gcTime: 10 * 60 * 1000,
+        refetchOnWindowFocus: false,
+    });
+}
+```
+
+**Benefits:**
+- Avoids duplicate API calls
+- Instant data if already loaded
+- Falls back to API if not cached
+
+### Example 3: Parallel Fetching
+
+```typescript
+import { useSuspenseQueries } from '@tanstack/react-query';
+
+export const Dashboard: React.FC = () => {
+    const [statsQuery, projectsQuery, notificationsQuery] = useSuspenseQueries({
+        queries: [
+            {
+                queryKey: ['stats'],
+                queryFn: () => statsApi.getStats(),
+            },
+            {
+                queryKey: ['projects', 'active'],
+                queryFn: () => projectsApi.getActiveProjects(),
+            },
+            {
+                queryKey: ['notifications', 'unread'],
+                queryFn: () => notificationsApi.getUnread(),
+            },
+        ],
+    });
+
+    return (
+        <Box>
+            <StatsCard data={statsQuery.data} />
+            <ProjectsList projects={projectsQuery.data} />
+            <Notifications items={notificationsQuery.data} />
+        </Box>
+    );
+};
+```
+
+---
+
+## Mutations with Cache Invalidation
+
+### Update Mutation
+
+```typescript
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { postApi } from '../api/postApi';
+import { useMuiSnackbar } from '@/hooks/useMuiSnackbar';
+
+export const useUpdatePost = () => {
+    const queryClient = useQueryClient();
+    const { showSuccess, showError } = useMuiSnackbar();
+
+    return useMutation({
+        mutationFn: ({ blogId, postId, data }: UpdateParams) =>
+            postApi.updatePost(blogId, postId, data),
+
+        onSuccess: (data, variables) => {
+            // Invalidate specific post
+            queryClient.invalidateQueries({
+                queryKey: ['post', variables.blogId, variables.postId]
+            });
+
+            // Invalidate list to refresh grid
+            queryClient.invalidateQueries({
+                queryKey: ['posts-v2', variables.blogId]
+            });
+
+            showSuccess('Post updated');
+        },
+
+        onError: (error) => {
+            showError('Failed to update post');
+            console.error('Update error:', error);
+        },
+    });
+};
+
+// Usage
+const updatePost = useUpdatePost();
+
+const handleSave = () => {
+    updatePost.mutate({
+        blogId: 123,
+        postId: 456,
+        data: { responses: { '101': 'value' } }
+    });
+};
+```
+
+### Delete Mutation
+
+```typescript
+export const useDeletePost = () => {
+    const queryClient = useQueryClient();
+    const { showSuccess, showError } = useMuiSnackbar();
+
+    return useMutation({
+        mutationFn: ({ blogId, postId }: DeleteParams) =>
+            postApi.deletePost(blogId, postId),
+
+        onSuccess: (data, variables) => {
+            // Remove from cache manually (optimistic)
+            queryClient.setQueryData<{ rows: Post[] }>(
+                ['posts-v2', variables.blogId],
+                (old) => ({
+                    ...old,
+                    rows: old?.rows.filter(row => row.S_ID !== variables.postId) || []
+                })
+            );
+
+            showSuccess('Post deleted');
+        },
+
+        onError: (error, variables) => {
+            // Rollback - refetch to get accurate state
+            queryClient.invalidateQueries({
+                queryKey: ['posts-v2', variables.blogId]
+            });
+            showError('Failed to delete post');
+        },
+    });
+};
+```
+
+---
+
+## Query Configuration Best Practices
+
+### Default Configuration
+
+```typescript
+// In QueryClientProvider setup
+const queryClient = new QueryClient({
+    defaultOptions: {
+        queries: {
+            staleTime: 1000 * 60 * 5,        // 5 minutes
+            gcTime: 1000 * 60 * 10,           // 10 minutes (was cacheTime)
+            refetchOnWindowFocus: false,       // Don't refetch on focus
+            refetchOnMount: false,             // Don't refetch on mount if fresh
+            retry: 1,                          // Retry failed queries once
+        },
+    },
+});
+```
+
+### Per-Query Overrides
+
+```typescript
+// Frequently changing data - shorter staleTime
+useSuspenseQuery({
+    queryKey: ['notifications', 'unread'],
+    queryFn: () => notificationApi.getUnread(),
+    staleTime: 30 * 1000,  // 30 seconds
+});
+
+// Rarely changing data - longer staleTime
+useSuspenseQuery({
+    queryKey: ['form', blogId, 'structure'],
+    queryFn: () => formApi.getStructure(blogId),
+    staleTime: 30 * 60 * 1000,  // 30 minutes
+});
+```
+
+---
+
+## Summary
+
+**Modern Data Fetching Recipe:**
+
+1. **Create API Service**: `features/X/api/XApi.ts` using apiClient
+2. **Use useSuspenseQuery**: In components wrapped by SuspenseLoader
+3. **Cache-First**: Check grid cache before API call
+4. **Query Keys**: Consistent naming ['entity', id]
+5. **Route Format**: `/blog/route` NOT `/api/blog/route`
+6. **Mutations**: invalidateQueries after success
+7. **Error Handling**: onError + useMuiSnackbar
+8. **Type Safety**: Type all parameters and returns
+
+**See Also:**
+- [component-patterns.md](component-patterns.md) - Suspense integration
+- [loading-and-error-states.md](loading-and-error-states.md) - SuspenseLoader usage
 - [complete-examples.md](complete-examples.md) - Full working examples