🚀 Development Guidelines - Backoffice Frontend

IoT Data Engine Platform | Frontend Development Standards & Best Practices

---

📋 Table of Contents

1. Architecture Overview
2. Performance & Bundle Optimization
3. TanStack Query Best Practices
4. Client-Side State Management ⚠️ Setup in progress
5. UI Component Guidelines
6. Code Quality Standards
7. Development Workflow
8. Security Best Practices
9. Anti-patterns to Avoid
10. Quick Reference

---

🏗️ Architecture Overview

Tech Stack

Our frontend is built with modern technologies optimized for performance and maintainability:

• Framework: Next.js 14 with App Router
• State Management: TanStack Query v5 for server state
• Forms: React Hook Form + Zod validation
• UI Library: Radix UI + Tailwind CSS
• Real-time: Socket.IO client
• Maps: Azure Maps integration
• Authentication: NextAuth.js with Azure AD
• Testing: Jest (unit) + Playwright (e2e)

Workspace Structure

apps/backoffice-frontend/
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── [lang]/            # Internationalized routes
│   │   ├── api/               # API routes
│   │   └── providers.tsx      # Global providers
│   ├── components/            # Shared components
│   ├── hooks/                 # Custom hooks organized by domain
│   ├── lib/                   # Utilities and configurations
│   ├── stores/                # Zustand stores organized by domain
│   │   ├── device/           # Device management stores
│   │   ├── user/             # User & authentication stores  
│   │   ├── ui/               # Pure UI state stores
│   │   └── index.ts          # Store re-exports
│   └── styles/               # Global styles
├── public/                   # Static assets
└── @pxs/* packages          # Workspace dependencies

Workspace Packages

• @pxs/ui: Shared UI components and design system
• @pxs/database: Prisma types and database utilities
• @pxs/common: Shared utilities and constants

🏪 Store Organization & Import Patterns

Our Zustand stores are organized by business domains for better maintainability and team collaboration.

Domain-Based File Organization

⚠️ Architecture Status: This store organization will be implemented when Zustand is integrated into the project. The architecture below represents the target recommended structure for organizing stores once Zustand is integrated.

src/stores/
├── device/                 # Device management domain
│   ├── useDeviceStore.ts      # Core device state & actions
│   ├── useDeviceFilters.ts    # Filtering & search logic
│   ├── useDeviceSelection.ts  # Selection & bulk operations
│   └── useDeviceStatusStore.ts # Real-time status updates
├── user/                   # User & authentication domain
│   ├── useUserStore.ts        # User profile & settings
│   ├── useAuthStore.ts        # Authentication state
│   └── useUserPreferencesStore.ts # UI preferences & persistence
├── ui/                     # Pure UI state domain
│   ├── useModalStore.ts       # Modal management
│   ├── useNotificationStore.ts # Toast notifications
│   └── useSidebarStore.ts     # Sidebar collapse/expand
└── index.ts               # Clean re-exports for easy imports

This architecture will be implemented progressively, starting with the most critical stores (notifications, device filters) then extending to other business domains.

Import Patterns & Best Practices

// ✅ Direct imports (when using few stores)
import { useDeviceFilters } from '@/stores/device/useDeviceFilters';
import { useModalStore } from '@/stores/ui/useModalStore';

// ✅ Centralized imports (when using many stores) 
import { 
  useDeviceFilters, 
  useDeviceSelection,
  useModalStore,
  useNotificationStore 
} from '@/stores';

// ✅ Domain-specific imports
import * as DeviceStores from '@/stores/device';
import * as UIStores from '@/stores/ui';

// Component usage
const DeviceManagement = () => {
  const { filters, setFilters } = useDeviceFilters();
  const { selectedDevices, toggleDevice } = useDeviceSelection();
  const { openModal } = useModalStore();
  
  return (
    // Component implementation
  );
};

Store Re-export Configuration

File: src/stores/index.ts

// Device domain exports
export { useDeviceStore } from './device/useDeviceStore';
export { useDeviceFilters } from './device/useDeviceFilters'; 
export { useDeviceSelection } from './device/useDeviceSelection';
export { useDeviceStatusStore } from './device/useDeviceStatusStore';

// User domain exports  
export { useUserStore } from './user/useUserStore';
export { useAuthStore } from './user/useAuthStore';
export { useUserPreferencesStore } from './user/useUserPreferencesStore';

// UI domain exports
export { useModalStore } from './ui/useModalStore';
export { useNotificationStore } from './ui/useNotificationStore';
export { useSidebarStore } from './ui/useSidebarStore';

// Type exports (optional, for better DX)
export type { DeviceFiltersStore } from './device/useDeviceFilters';
export type { DeviceSelectionStore } from './device/useDeviceSelection';
export type { NotificationStore } from './ui/useNotificationStore';

⚠️ Store Naming Conventions

Developer Experience Question: The use prefix in Zustand stores can create confusion with custom React hooks. Here are the different approaches available:

🎯 Available naming options:

Approach	Example	Advantages	Disadvantages
use-prefix	useDeviceFilters()	Familiar to React devs	Confusion with custom hooks
store-suffix	deviceFiltersStore()	Clear about object type	Less idiomatic in React
create-prefix	createDeviceFilters()	Indicates store creation	More verbose
domain-object	deviceFilters()	Simple and direct	May lack context

💡 Our recommended choice: use prefix with clarification

// ✅ Chosen approach - with clear documentation
import { useDeviceFilters } from '@/stores/device/useDeviceFilters';  // Zustand store
import { useCustomDeviceHook } from '@/hooks/useCustomDeviceHook';    // Custom React hook

// In code, clear differentiation:
const DeviceManagement = () => {
  // 🏪 Zustand stores (global state management)
  const { filters, setFilters } = useDeviceFilters();
  const { selectedDevices } = useDeviceSelection();
  
  // 🎣 Custom hooks (business logic/API)
  const { deviceData, isLoading } = useCustomDeviceHook(filters);
  
  return (/* component */);
};

🔍 Choice justification:

• Consistency: React ecosystem massively uses the use prefix
• Familiar DX: React developers expect this convention
• Import differentiation: Folder structure clarifies usage
• Documentation: Clear guidelines to distinguish stores vs hooks

📋 Differentiation rules:

// 🏪 STORES (Zustand) - Global state management
const useDeviceFilters = create((set) => ({ ... }));     // Shared state
const useNotificationStore = create((set) => ({ ... })); // Global UI state

// 🎣 HOOKS (Custom) - Business logic/API  
const useDeviceData = (filters) => { ... };              // API calls + logic
const useDeviceValidation = (device) => { ... };         // Business logic

---

⚡ Performance & Bundle Optimization

Dynamic Imports Pattern

✅ DO - For components > 50KB:

// Example: Heavy component lazy loading
const DeviceEventList = dynamic(() => 
  import("@/app/[lang]/components/device-event-list").then(mod => ({ default: mod.DeviceEventList })), 
  { 
    ssr: false,
    loading: () => (
      <div className="animate-pulse">
        <div className="h-8 bg-gray-200 rounded mb-4"></div>
        <div className="space-y-3">
          {[...Array(5)].map((_, i) => (
            <div key={i} className="h-16 bg-gray-200 rounded"></div>
          ))}
        </div>
      </div>
    )
  }
);

Conditional Loading Pattern

✅ DO - Load expensive libraries only when needed:

// Example: Azure Maps conditional loading
const areLocationsSet = data.filter(item => item.location).length > 0;

const GeojsonClient = dynamic(() => 
  import("@/app/[lang]/components/map/AzureMapGeoJsonConverter"), 
  { 
    ssr: false,
    loading: () => <div className="animate-pulse h-64 bg-gray-200 rounded">Loading map...</div>
  }
);

return (
  <>
    {/* Always render lightweight components */}
    <DataTable data={data} />
    
    {/* Conditionally render heavy components */}
    {areLocationsSet && mapsToken && (
      <GeojsonClient
        devices={data}
        azureMapsClientId={azureMapsClientId}
        mapsToken={mapsToken}
      />
    )}
  </>
);

Bundle Analysis Workflow

# Generate bundle analysis
ANALYZE=true npm run build

# View reports
open .next/analyze/client.html
open .next/analyze/server.html

Regular monitoring:

• Run analysis before major releases
• Monitor pages > 500KB
• Track vendor chunk sizes

Webpack Vendor Splitting

🤔 What is a Vendor Chunk?

A vendor chunk is a separate JavaScript file containing external dependencies (npm packages) from your application. Instead of having one large bundle with all code, Webpack intelligently separates:

• App code: Your business code (changes frequently)
• Vendor code: Third-party libraries (changes rarely)

💡 Why separate?

• 🚀 Cache optimization: Vendors change rarely, browser keeps them in cache longer
• ⚡ Parallel loading: Downloads multiple chunks in parallel
• 🔄 Faster deployments: Only app code is re-downloaded during updates

🎯 Our optimized splitting strategy:

// next.config.js - Current configuration
module.exports = {
  webpack: (config) => {
    config.optimization.splitChunks = {
      chunks: 'all',
      cacheGroups: {
        // 🗺️ Azure Maps - Heaviest, conditional loading
        azureMaps: {
          name: 'azure-maps-vendor',
          test: /[\\/]node_modules[\\/]azure-maps.*[\\/]/,
          priority: 30,  // Higher priority = guaranteed separate chunk
          chunks: 'all',
        },
        // 🎨 Radix UI - UI Components, used everywhere
        radixUI: {
          name: 'radix-ui-vendor', 
          test: /[\\/]node_modules[\\/]@radix-ui[\\/]/,
          priority: 28,
          chunks: 'all',
        },
        // 🎭 Icons - Lightweight, shared globally
        icons: {
          name: 'icons-vendor',
          test: /[\\/]node_modules[\\/](lucide-react|@heroicons)[\\/]/,
          priority: 25,
          chunks: 'all',
        },
        // 🛠️ Utilities - Lodash, date-fns, etc.
        utilities: {
          name: 'ui-vendor',
          test: /[\\/]node_modules[\\/](lodash|date-fns|clsx|tailwind-merge)[\\/]/,
          priority: 20,
          chunks: 'all',
        },
        // ⚛️ React ecosystem - Framework core
        react: {
          name: 'react-vendor',
          test: /[\\/]node_modules[\\/](react|react-dom|scheduler)[\\/]/,
          priority: 15,
          chunks: 'all',
        },
      },
    };
    return config;
  },
};

📊 Analysis of our current splitting:

Vendor Chunk	Size	Priority	Loading Strategy	Justification
azure-maps-vendor.js	1.6MB	30	🔄 Lazy loading	Heavy, used only with geolocation
radix-ui-vendor.js	336KB	28	📦 Initial bundle	UI components everywhere, critical for UX
icons-vendor.js	48KB	25	📦 Initial bundle	Lightweight, icons used globally
ui-vendor.js	88KB	20	📦 Initial bundle	Utilities, used frequently
react-vendor.js	~200KB	15	📦 Initial bundle	Framework, required for entire app

🔢 Priority System Explained:

// 🎯 How Webpack decides splitting with priorities:

priority: 30  // 🥇 HIGHEST - Always creates separate chunk
// Example: Azure Maps (1.6MB) - too heavy to be mixed

priority: 28  // 🥈 HIGH - Separate chunk if > size threshold  
// Example: Radix UI (336KB) - heavy enough + used everywhere

priority: 25  // 🥉 MEDIUM - Can be combined if small
// Example: Icons (48KB) - lightweight but logically separated

priority: 20  // 🏃 LOW - Combined with others if possible
// Example: Utilities (88KB) - less critical business logic

priority: 15  // 🐌 LOWEST - Fallback, default chunk
// Example: React (~200KB) - framework, lower priority

⚡ Performance Impact:

# 🚀 BEFORE vendor splitting:
main.js: 2.4MB  # 😱 One large file
# - First load: 2.4MB to download
# - Code update: 2.4MB to re-download  
# - Parallelization: impossible

# ✅ AFTER vendor splitting:
react-vendor.js: 200KB      # Cache: 1 month (stable framework)  
ui-vendor.js: 88KB          # Cache: 2 weeks (utilities)
icons-vendor.js: 48KB       # Cache: 1 month (stable icons)
radix-ui-vendor.js: 336KB   # Cache: 2 weeks (components)
azure-maps-vendor.js: 1.6MB # Cache: 1 month + lazy loading
app.js: 150KB               # Cache: 1 day (changing business code)

# 📊 Results:
# - First load: 822KB (only necessary chunks)  
# - Code update: 150KB (only app.js)
# - Parallel download: 6 files in parallel
# - Cache hit ratio: ~85% on repeat visits

🎯 Loading strategies by use case:

// 🗺️ Azure Maps - Conditional loading (priority: 30)
const MapComponent = dynamic(() => import('./AzureMapComponent'), {
  loading: () => <MapSkeleton />,
  ssr: false, // Maps don't work in SSR
});

// Usage: Load azure-maps-vendor.js only when necessary
const DeviceLocationView = ({ devices }) => {
  const hasLocations = devices.some(d => d.location);
  
  return (
    <>
      <DeviceTable devices={devices} />
      {/* ⚡ Azure Maps chunk loaded only when needed */}
      {hasLocations && <MapComponent devices={devices} />}
    </>
  );
};

// ⚛️ Radix UI - Immediate loading (priority: 28)  
import { Button, Dialog, Select } from '@radix-ui/react-*';
// radix-ui-vendor.js loaded immediately as used everywhere

// 🎭 Icons - Immediate loading (priority: 25)
import { Search, Filter, Download } from 'lucide-react';  
// icons-vendor.js lightweight, loaded with initial bundle

🔍 Monitoring and optimization:

# Bundle analysis
ANALYZE=true npm run build

# 🎯 Metrics to monitor:
# - Vendor chunks > 500KB → Candidates for lazy loading
# - App code > vendor code → Good ratio
# - Cache hit rate > 80% → Effective splitting
# - Parallel loading time < 2s → Performance OK

# 🚨 Warning signals:
# - A vendor chunk > 2MB → Mandatory lazy loading  
# - Too many small chunks (< 20KB) → Over-splitting
# - Cache hit rate < 60% → Review strategy

💡 Evolution recommendations:

1. 🔄 Additional lazy loading: TanStack Query DevTools, Playwright (dev only)
2. 📦 Micro-chunking: Separate Zustand stores by domain
3. 🎯 Route-based splitting: Page-specific chunks (admin, dashboard)
4. 🌐 CDN optimization: Pre-load vendor chunks from external CDN

---

🔄 TanStack Query Best Practices

What is TanStack Query? (For NestJS Developers)

If you're coming from NestJS backend development, think of TanStack Query as a smart caching layer for frontend API calls - similar to how you'd use @nestjs/cache-manager in your controllers, but automatic and declarative.

🏗️ Backend vs Frontend Analogy:

// ❌ Traditional approach (like calling API without cache)
const [data, setData] = useState(null);
const [loading, setLoading] = useState(false);
const [error, setError] = useState(null);

useEffect(() => {
  setLoading(true);
  fetch('/api/users')
    .then(res => res.json())
    .then(data => {
      setData(data);
      setLoading(false);
    })
    .catch(err => {
      setError(err);
      setLoading(false);
    });
}, []);

// ✅ TanStack Query approach (like NestJS with automatic caching)
const { data, isLoading, error } = useQuery({
  queryKey: ['users'],           // Cache key (like Redis key)
  queryFn: () => api.getUsers(), // API call (like calling your NestJS service)
});

🔗 NestJS Equivalences:

• Query = @Get() endpoint with automatic caching
• Mutation = @Post(), @Put(), @Delete() endpoints
• Query Key = Cache key strategy (like Redis keys)
• Invalidation = Cache eviction (like cacheManager.del())

---

Integration with Your NestJS Monorepo Architecture

Our TanStack Query implementation is specifically designed to work seamlessly with your existing NestJS backend. Here's how it integrates with your current API structure:

🏗️ Your Current API Architecture:

// Your existing API structure in src/lib/api/
import api from '@/lib/api'; // Single API instance

// Available API classes:
api.device     // APIDevice class
api.tag        // APITag class  
api.user       // APIUser class
api.project    // APIProject class
api.organization // APIOrganization class
// ... and more

🔗 Direct Integration with Your NestJS Controllers:

// Backend Controller (NestJS)
@Controller('device')
export class DeviceController {
  @Get()
  async findAll(@Query() filters: DeviceFilterDto) {
    return this.deviceService.findAll(filters);
  }
  
  @Get(':id')  
  async findOne(@Param('id') id: string) {
    return this.deviceService.findOne(id);
  }
}

// Frontend API Class (Your existing code)
export class APIDevice extends AbstractAPI {
  async list(token: string, pageIdx = 1, take = 10, ...filters): Promise<PaginationType<DeviceDTO>> {
    return await this.doRequest(`${process.env.NEXT_PUBLIC_API_URL}/device?page=${pageIdx}&take=${take}`, {
      method: "GET",
      headers: { Authorization: `Bearer ${token}` },
    });
  }
  
  async get(token: string, deviceId: string): Promise<DeviceDTO> {
    return await this.doRequest(`${process.env.NEXT_PUBLIC_API_URL}/device/${deviceId}`, {
      method: "GET", 
      headers: { Authorization: `Bearer ${token}` },
    });
  }
}

// TanStack Query Integration (What we're adding)
function useDevices(token: string, filters = {}) {
  return useQuery({
    queryKey: ['devices', filters],                    // Cache key
    queryFn: () => api.device.list(token, 1, 10, ...filters), // Uses your existing API class!
    enabled: !!token,                                  // Only call if authenticated
  });
}

---

🚀 Real Use Case: Device Dashboard Migration

This section demonstrates a complete real-world migration from Server Components to Client Components with TanStack Query, using our actual Device Dashboard implementation.

📋 The Challenge: Device Dashboard Performance

Original Implementation (Server Component):

// src/app/[lang]/(dashboard)/dashboard/device/page.tsx - BEFORE
const PageViewContent = async ({ searchParams, params: { lang } }) => {
  const session = await getSession();
  
  // ❌ Problems with this approach:
  // - No caching - refetches on every navigation
  // - No loading states - shows blank page during load
  // - No optimistic updates - poor UX for pagination/filtering
  // - Server-side only - can't leverage client-side optimizations
  
  const [{ datatable, pages }, devicesWithProductAndOrganization] = await Promise.all([
    getDictionary(lang),
    api.device.getWithProductAndOrganization(
      session.token,
      paginationParams.page,
      paginationParams.take, 
      paginationParams.order,
      "",
      undefined,
      filterParams,
    ),
  ]);
  
  return (
    <Dashboard>
      <DeviceTableForm
        allDevices={devicesWithProductAndOrganization.data}
        meta={devicesWithProductAndOrganization.meta}
        // ... other props passed from server
      />
    </Dashboard>
  );
};

🎯 Migration Strategy: Step-by-Step

Step 1: Create TanStack Query Hook

// src/hooks/devices/useDevicesWithProductAndOrganization.ts - NEW
import { useQuery } from "@tanstack/react-query";
import api from "@/lib/api";
import { OrganizationDTO } from "@pxs/database/src/dto/organization.dto";
import { DeviceDTO, ProductDTO } from "@pxs/database";
import { PaginationType } from "@/lib/types/Pagination.type";
import { deviceQueries } from "@/lib/queries/device-queries";

export function useDevicesWithProductAndOrganization(
  token: string,
  page: number,
  take: number,
  order: string,
  searchQuery: string,
  filterColumn: string,
  filtersFromUrl: { [key: string]: string | undefined },
) {
  return useQuery<PaginationType<DeviceDTO & { product: ProductDTO; organization: OrganizationDTO }>>({
    queryKey: deviceQueries.withProductAndOrganization({ 
      page, take, order, searchQuery, filterColumn, filtersFromUrl 
    }),
    queryFn: () =>
      api.device.getWithProductAndOrganization(token, page, take, order, searchQuery, filterColumn, filtersFromUrl),
    enabled: !!token,
  });
}

Step 2: Create Query Keys Factory

// src/lib/queries/device-queries.ts - NEW
export const deviceQueries = {
  all: () => ["devices"] as const,
  withProductAndOrganization: (params: {
    page?: number;
    take?: number;
    order?: string;
    searchQuery?: string;
    filterColumn?: string;
    filtersFromUrl?: Record<string, string | undefined>; // ✅ Fixed type compatibility
  }) => [...deviceQueries.all(), "withProductAndOrganization", params] as const,
};

Step 3: Migrate Component to Client-Side

// src/app/[lang]/components/device/device-table-form.tsx - MIGRATED
"use client";

import { useDevicesWithProductAndOrganization } from "@/hooks/devices";

type Props = {
  lang: Locale;
  datatable: DataTableTranslation;
  dialog: DeviceTableDropdownSettingsTranslation;
  roles: string[];
  token: string; // ✅ Now receives token instead of data
  // ❌ Removed: allDevices and meta (now fetched client-side)
};

export default function DeviceTableForm(props: Props) {
  const session = useSessionRequired();
  const router = useRouter();
  const searchParams = useSearchParams();
  
  // 🎯 Extract URL parameters for TanStack Query
  const page = parseInt(searchParams?.get("page") || "1");
  const take = parseInt(searchParams?.get("take") || "10");
  const order = (searchParams?.get("order") as "ASC" | "DESC") || "DESC";
  const searchQuery = searchParams?.get("q") || "";
  const filterParams: { [key: string]: string | undefined } = {};
  searchParams?.forEach((value, key) => {
    if (!["page", "take", "order", "q"].includes(key)) {
      filterParams[key] = value;
    }
  });

  // 🚀 TanStack Query replaces server-side data fetching
  const {
    data: devicesWithProductAndOrganization,
    isLoading,
    error,
  } = useDevicesWithProductAndOrganization(
    props.token, page, take, order, searchQuery, "", filterParams
  );

  // ✅ Extract data with defaults
  const allDevices = devicesWithProductAndOrganization?.data || [];
  const meta = devicesWithProductAndOrganization?.meta || {
    page: 1,
    take: 10,
    itemCount: 0,
    pageCount: 1,
    hasPreviousPage: false,
    hasNextPage: false,
  };

  // 🎨 Loading and error states (impossible with Server Components)
  if (isLoading) {
    return (
      <div className="flex items-center justify-center p-8">
        <div className="text-lg">Loading devices...</div>
      </div>
    );
  }

  if (error) {
    return (
      <div className="flex items-center justify-center p-8">
        <div className="text-lg text-red-600">Error loading devices. Please try again.</div>
      </div>
    );
  }

  // 🎯 Simplified pagination (no local state needed)
  const handlePageChange = (newPage: number) => {
    const searchParams = new URLSearchParams(window.location.search);
    searchParams.set("page", newPage.toString());
    const newPath = `/${props.lang}/dashboard/device?${searchParams.toString()}`;
    router.push(newPath); // TanStack Query automatically refetches
  };

  return (
    <DataTable
      data={allDevices as any}
      // ... all the existing props work the same
      pageCount={Math.ceil(meta.itemCount / meta.take)}
      currentPage={meta.page}
      take={meta.take}
      itemCount={meta.itemCount}
      onPageChange={handlePageChange}
      // ...
    />
  );
}

Step 4: Simplify Server Component

// src/app/[lang]/(dashboard)/dashboard/device/page.tsx - SIMPLIFIED
const PageViewContent = async ({ params: { lang } }) => {
  const session = await getSession();
  if (!session) return redirect(`/${lang}/auth/login`);

  // ✅ Only fetch static data server-side (translations)
  const { datatable, pages } = await getDictionary(lang);

  return (
    <Dashboard>
      <DashboardTitle className="flex flex-row items-center">
        <H2>{pages.resources.title}</H2>
        {/* ... */}
      </DashboardTitle>
      <DashboardContent>
        <DeviceTableForm
          token={session.token}    // ✅ Pass token instead of data
          lang={lang}
          datatable={datatable}
          dialog={pages.resources.dialog}
          roles={session.roles}
          // ❌ Removed: allDevices and meta (now handled client-side)
        />
      </DashboardContent>
    </Dashboard>
  );
};

📊 Results: Before vs After Comparison

Aspect	Before (Server)	After (Client + TanStack Query)
🔄 Caching	❌ No cache - refetch every navigation	✅ Intelligent cache with 60s stale time
⚡ Loading States	❌ Blank page during server render	✅ Skeleton UI with smooth transitions
📱 Pagination	❌ Full page reload + server round trip	✅ Instant navigation with cached data
🔍 Filtering	❌ Server round trip for each filter	✅ Cached filter combinations
🔄 Data Sync	❌ Manual revalidation needed	✅ Automatic background refetching
🛠️ Developer Experience	🟡 Server-side debugging only	✅ React DevTools + Query DevTools
🎯 Type Safety	✅ Full type safety maintained	✅ Enhanced with query-specific types
⚠️ Error Handling	🟡 Server error pages	✅ Component-level error boundaries

🎯 Key Benefits Achieved

🚀 Performance Improvements:

• Cache Hit Ratio: ~80% of device list requests served from cache
• Pagination Speed: Instant navigation (cached pages)
• Filter Combinations: Each filter combo cached separately
• Background Refresh: Data stays fresh without user awareness

🎨 Enhanced User Experience:

• Progressive Loading: Skeleton → Data → Optimistic updates
• Offline Resilience: Last known data shown when offline
• Smooth Interactions: No page flashes during navigation
• Error Recovery: Retry mechanisms with exponential backoff

🛠️ Developer Experience:

// 🔍 Debugging with React Query DevTools
// - View all cached device queries
// - Inspect query states (fresh, stale, fetching)
// - Monitor network requests and cache hits
// - Debug invalidation strategies

// 📊 Query inspection in browser console:
queryClient.getQueryData(deviceQueries.withProductAndOrganization({ page: 1, take: 10 }))
// Returns cached device data or undefined

🎯 This migration pattern can be applied to:

• Tag management pages
• Project dashboards
• User management interfaces
• Any paginated/filtered data views
• Complex forms with dependent data

---

📋 Shared Types with @pxs/database: Your monorepo setup allows perfect type safety between backend and frontend:

// Backend (NestJS) - Uses Prisma generated types
import { DeviceDTO, TagDTO, UserDTO } from '@pxs/database';

@Controller('device')
export class DeviceController {
  @Get(':id')
  async findOne(@Param('id') id: string): Promise<DeviceDTO> {
    return this.deviceService.findOne(id); // Returns DeviceDTO
  }
}

// Frontend (Next.js) - Uses the SAME types!
import { DeviceDTO, TagDTO, UserDTO } from '@pxs/database';

function useDevice(deviceId: string, token: string): UseQueryResult<DeviceDTO> {
  return useQuery({
    queryKey: ['device', deviceId],
    queryFn: () => api.device.get(token, deviceId), // Returns DeviceDTO (same type!)
    enabled: !!deviceId && !!token,
  });
}

🛡️ Error Handling with Your AbstractAPI: Your AbstractAPI class already handles authentication and errors perfectly:

// Your existing AbstractAPI handles:
// ✅ JWT token forwarding
// ✅ SSR/CSR cookie management  
// ✅ Unauthorized redirects to /auth/login
// ✅ Validation error parsing from NestJS

// TanStack Query leverages this automatically:
function useCreateDevice(token: string) {
  return useMutation({
    mutationFn: (deviceData) => api.device.create(token, deviceData),
    
    // Your AbstractAPI.handleError() will:
    // - Redirect to /auth/login on 401
    // - Parse validation errors from NestJS
    // - Handle all HTTP error codes properly
  });
}

🎯 This means for your developers:

• ✅ Zero learning curve - TanStack Query uses your existing API classes
• ✅ Perfect type safety - Same DTOs backend ↔ frontend
• ✅ Familiar error handling - Your AbstractAPI handles everything
• ✅ Consistent patterns - Same token passing, same endpoints structure

---

Global Configuration (Detailed)

Our optimized QueryClient setup in providers.tsx - think of this as your global caching configuration:

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      // ↔ NestJS: CacheModule.register({ ttl: 60 })
      staleTime: 60 * 1000,          // 1 minute before data is considered "stale"
                                     // During this time, React won't refetch automatically
      
      // ↔ NestJS: Cache cleanup/garbage collection policy  
      gcTime: 5 * 60 * 1000,         // 5 minutes in memory after component unmounts
                                     // Like keeping cache in memory for potential reuse
      
      // ↔ NestJS: Disable automatic health checks
      refetchOnWindowFocus: false,    // Don't refetch when user returns to tab
                                     // Prevents unnecessary API calls to your backend
      
      // ↔ NestJS: Retry interceptor configuration
      retry: 1,                       // Retry failed requests once (like HTTP retry logic)
                                     // Prevents overwhelming your backend with failed requests
    },
  },
});

🎯 Why These Settings?

# In your NestJS backend, you might have:
@Controller('users')
@UseInterceptors(CacheInterceptor) // Cache for 60 seconds
export class UsersController {
  @Get()
  @CacheKey('users_list')
  @CacheTTL(60) // Same as our staleTime!
  async getUsers() {
    return this.usersService.findAll();
  }
}

# TanStack Query mirrors this caching behavior on the frontend!

useQuery Pattern (Like NestJS @Get() Endpoints)

useQuery is for reading data - equivalent to your @Get() endpoints with automatic caching:

// ↔ NestJS Backend equivalent:
// @Get('tag/:id')
// async findOne(@Param('id') id: string): Promise<TagDTO> {
//   return this.tagService.findOne(id);
// }

// Frontend TanStack Query using your REAL API class:
import { TagDTO } from '@pxs/database';
import api from '@/lib/api';

export function useTag(tagId: string, token: string): UseQueryResult<TagDTO> {
  return useQuery({
    // 🔑 Query Key: Maps to GET /tag/:id
    queryKey: ["tag", tagId],                    
    
    // 🎯 Query Function: Uses your existing APITag.get() method
    queryFn: () => api.tag.get(token, tagId),    // Calls: ${NEXT_PUBLIC_API_URL}/tag/${tagId}
    
    // 📋 Options (leveraging your AbstractAPI):
    enabled: !!tagId && !!token,                 // Only call if authenticated
                                                 // Your AbstractAPI handles the rest
    
    throwOnError: false,                         // Let AbstractAPI.handleError() manage errors
                                                 // - 401 → redirect to /auth/login  
                                                 // - Validation errors → parsed automatically
    
    // 🔄 Retry Logic (works with your backend)
    retry: (failureCount, error) => {
      if (error?.status === 404) return false;   // Tag not found - don't retry
      return failureCount < 2;                   // Retry server errors twice
    },
    
    // ⚡ Caching behavior
    staleTime: 2 * 60 * 1000,                   // 2 minutes fresh
    gcTime: 10 * 60 * 1000,                     // 10 minutes in memory
  });
}

// Example: Tag list with filters (using your real list method)
export function useTags(
  token: string, 
  searchQuery = "", 
  filterColumn?: string,
  filtersFromUrl?: { [key: string]: string | undefined },
  take = 10
) {
  return useQuery({
    queryKey: ["tags", searchQuery, filterColumn, filtersFromUrl, take],
    queryFn: () => api.tag.list(token, searchQuery, filterColumn, filtersFromUrl, take),
    enabled: !!token,
    staleTime: 1 * 60 * 1000, // Lists get stale faster (1 minute)
  });
}

// Usage in component:
function TagDetails({ tagId }: { tagId: string }) {
  const { data: token } = useSession(); // Your auth setup
  const { data: tag, isLoading, error } = useTag(tagId, token);
  
  // 🎯 Fully typed with TagDTO from @pxs/database
  if (isLoading) return <Skeleton />;
  if (error) return <ErrorMessage error={error} />;
  
  return (
    <div>
      <h1>{tag.name}</h1>             {/* TypeScript knows these fields */}
      <p>{tag.description}</p>        {/* from TagDTO interface */}
      <span>{tag.color}</span>
      {/* Your AbstractAPI ensures this data is properly typed */}
    </div>
  );
}

---

useMutation Pattern (Like NestJS @Post/@Put/@Delete)

useMutation is for modifying data - equivalent to your CUD operations:

// ↔ NestJS Backend equivalent:
// @Put('tag/:id')
// async update(
//   @Param('id') id: string,
//   @Body() updateTagDto: UpdateTagDto
// ): Promise<TagDTO> {
//   const updatedTag = await this.tagService.update(id, updateTagDto);
//   return updatedTag;
// }

// Frontend TanStack Query using your REAL API methods:
import { TagDTO } from '@pxs/database';
import api from '@/lib/api';
import { toast } from '@/components/ui/use-toast';

// 📝 Create Tag
export function useCreateTag() {
  const queryClient = useQueryClient();
  
  return useMutation({
    mutationFn: (params: { token: string; data: any }): Promise<TagDTO> => {
      // Uses your real APITag.create() method
      return api.tag.create(params.token, params.data);
    },
    
    onSuccess: () => {
      // Invalidate tags list to show the new tag
      queryClient.invalidateQueries({ queryKey: ["tags"] });
      toast({ title: "Tag created successfully" });
    },
    
    // Your AbstractAPI.handleError() already handles:
    // - 401 redirect to login
    // - Validation error parsing
    // - Proper error formatting
  });
}

// ✏️ Update Tag  
export function useUpdateTag() {
  const queryClient = useQueryClient();
  
  return useMutation({
    mutationFn: (params: { token: string; tagId: string; data: any }): Promise<TagDTO> => {
      // Uses your real APITag.update() method
      return api.tag.update(params.token, params.tagId, params.data);
    },
    
    onSuccess: (updatedTag, variables) => {
      // 🧹 Cache Invalidation (like cacheManager.del())
      queryClient.invalidateQueries({ queryKey: ["tag", variables.tagId] });
      queryClient.invalidateQueries({ queryKey: ["tags"] }); // Update lists too
      
      toast({ title: "Tag updated successfully" });
    },
  });
}

// 🗑️ Delete Tag
export function useDeleteTag() {
  const queryClient = useQueryClient();
  
  return useMutation({
    mutationFn: (params: { token: string; tagId: string }): Promise<void> => {
      // Uses your real APITag.delete() method
      return api.tag.delete(params.token, params.tagId);
    },
    
    onSuccess: (_, variables) => {
      // Remove from cache and invalidate lists
      queryClient.removeQueries({ queryKey: ["tag", variables.tagId] });
      queryClient.invalidateQueries({ queryKey: ["tags"] });
      
      toast({ title: "Tag deleted successfully" });
    },
  });
}

// 📱 Device Examples (showing your IoT domain)
import { DeviceDTO, TagDTO } from '@pxs/database';
import { PaginationType } from '@/lib/types/Pagination.type';

// Device List with pagination (your real signature)
export function useDevices(
  token: string,
  pageIdx = 1,
  take = 10,
  order = "DESC",
  searchQuery = "",
  filterColumn?: string,
  filtersFromUrl?: { [key: string]: string | undefined }
) {
  return useQuery({
    queryKey: ["devices", pageIdx, take, order, searchQuery, filterColumn, filtersFromUrl],
    queryFn: (): Promise<PaginationType<DeviceDTO & { tags: TagDTO[] }>> => {
      return api.device.list(token, pageIdx, take, order, searchQuery, filterColumn, filtersFromUrl);
    },
    enabled: !!token,
    staleTime: 30 * 1000, // Device data changes frequently - 30 seconds stale time
  });
}

// Device creation
export function useCreateDevice() {
  const queryClient = useQueryClient();
  
  return useMutation({
    mutationFn: (params: { token: string; device: object }): Promise<DeviceDTO> => {
      return api.device.create(params.token, params.device);
    },
    
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ["devices"] });
      toast({ title: "Device created successfully" });
    },
  });
}

// Usage in component:
function DeviceList() {
  const { data: token } = useSession();
  const [page, setPage] = useState(1);
  const { data: devicesPage, isLoading } = useDevices(token, page);
  
  if (isLoading) return <DeviceListSkeleton />;
  
  return (
    <div>
      {devicesPage?.data.map(device => (
        <div key={device.id}>
          <h3>{device.name}</h3>
          <p>Status: {device.status}</p>
          <div>Tags: {device.tags.map(tag => tag.name).join(', ')}</div>
        </div>
      ))}
      <Pagination 
        current={page}
        total={devicesPage?.meta.totalPages}
        onPageChange={setPage}
      />
    </div>
  );
}

---

Perfect Type Safety with @pxs/database DTOs

Your monorepo architecture provides a huge advantage: shared types between backend and frontend. This eliminates the need to duplicate type definitions and ensures perfect consistency.

🏗️ How it works in your setup:

// 📦 Shared package: @pxs/database (generated by Prisma)
// This package is used by BOTH backend and frontend

// Backend NestJS Controller
import { DeviceDTO, TagDTO, UserDTO, OrganizationDTO } from '@pxs/database';

@Controller('device')
export class DeviceController {
  @Get(':id')
  async findOne(@Param('id') id: string): Promise<DeviceDTO> {
    // Your service returns a DeviceDTO
    return this.deviceService.findOne(id);
  }
  
  @Get()
  async findAll(): Promise<PaginationType<DeviceDTO & { tags: TagDTO[] }>> {
    // Complex nested DTOs are automatically typed
    return this.deviceService.findAllWithTags();
  }
}

// Frontend API Layer - Uses SAME types
import { DeviceDTO, TagDTO, UserDTO, OrganizationDTO } from '@pxs/database';
import { PaginationType } from '@/lib/types/Pagination.type';

export class APIDevice extends AbstractAPI {
  // 🎯 Return types match backend exactly
  async get(token: string, deviceId: string): Promise<DeviceDTO> {
    return await this.doRequest(`${process.env.NEXT_PUBLIC_API_URL}/device/${deviceId}`, {
      // ... your existing implementation
    });
  }
  
  async list(token: string, ...params): Promise<PaginationType<DeviceDTO & { tags: TagDTO[] }>> {
    return await this.doRequest(url, { /* ... */ });
  }
}

// Frontend TanStack Query - Perfectly typed
function useDevice(deviceId: string, token: string): UseQueryResult<DeviceDTO> {
  return useQuery({
    queryKey: ['device', deviceId],
    queryFn: () => api.device.get(token, deviceId), // 🎯 DeviceDTO guaranteed
  });
}

// Frontend Component - Full IntelliSense
function DeviceCard({ deviceId }: { deviceId: string }) {
  const { data: device } = useDevice(deviceId, token);
  
  if (!device) return <Skeleton />;
  
  return (
    <div>
      {/* 💡 TypeScript knows all these properties from DeviceDTO */}
      <h2>{device.name}</h2>
      <p>Serial: {device.serialNumber}</p>
      <p>Status: {device.status}</p>
      <p>Battery: {device.batteryLevel}%</p>
      <p>Last seen: {new Date(device.lastSeenAt).toLocaleDateString()}</p>
      
      {/* 🏷️ Nested DTOs are fully typed too */}
      {device.tags?.map(tag => (
        <Badge key={tag.id} style={{ backgroundColor: tag.color }}>
          {tag.name}
        </Badge>
      ))}
    </div>
  );
}

✅ Benefits of this approach:

1. 🔄 Zero duplication - Types defined once in Prisma schema
2. 🎯 Guaranteed consistency - Backend and frontend can't drift apart
3. ⚡ IntelliSense everywhere - Full autocomplete in VS Code
4. 🐛 Compile-time safety - Breaking changes caught at build time
5. 🔧 Refactoring safety - Rename a field once, updates everywhere

🚨 Example of how this prevents bugs:

// If your backend team changes DeviceDTO:
// OLD: { batteryLevel: number }
// NEW: { battery: { level: number, isCharging: boolean } }

// ❌ Without shared types: Runtime error in production
function BatteryIndicator({ device }) {
  return <span>{device.batteryLevel}%</span>; // undefined.batteryLevel!
}

// ✅ With @pxs/database DTOs: Compile error caught immediately  
function BatteryIndicator({ device }: { device: DeviceDTO }) {
  return <span>{device.batteryLevel}%</span>; // TS Error: Property 'batteryLevel' does not exist
  // Fix: return <span>{device.battery.level}%</span>; ✅
}

🎯 Best Practices for Your Team:

1. Import DTOs consistently:

   // ✅ Good - Import specific DTOs
   import { DeviceDTO, TagDTO, UserDTO } from '@pxs/database';
   
   // ❌ Avoid - Generic any types
   function useDevice(id: string): UseQueryResult<any> { ... }

2. Use DTOs in API layer return types:

   // ✅ Your existing API classes should specify return types
   export class APIDevice extends AbstractAPI {
     async get(token: string, deviceId: string): Promise<DeviceDTO> {
       return this.doRequest(/* ... */);
     }
   }

3. Leverage nested DTOs:

   // Your API often returns nested data
   type DeviceWithTags = DeviceDTO & { tags: TagDTO[] };
   type UserWithOrganization = UserDTO & { organization: OrganizationDTO };

---

Query Keys Conventions - Your Real API Endpoints

🤔 Problem to solve: How to organize query keys to efficiently manage cache and invalidations with your actual IoT platform API?

💡 Approach: Query keys that mirror your exact API structure

🏗️ Your Real API Endpoints → Query Keys Mapping:

# Your actual backend endpoints:
GET /device                                    → ['devices']
GET /device?page=1&take=10                     → ['devices', { page: 1, take: 10, ... }]  
GET /device/:id                                → ['device', deviceId]
GET /device/devicesWithProductAndOrganization  → ['devices', 'withProductAndOrganization', params]
GET /device-type                               → ['device-types']
GET /device-event                              → ['device-events']

GET /tag                       → ['tags'] 
GET /tag/:id                   → ['tag', tagId]

GET /project                   → ['projects']
GET /project/:id               → ['project', projectId]
GET /project-dashboard         → ['project-dashboard']

GET /organization              → ['organizations']
GET /user                      → ['users']
GET /business-flow             → ['business-flows']

🎯 Query Keys Factories for Your Domains:

// 🏭 Complete Query Keys Factory for your IoT Platform
// Based on your real API classes in src/lib/api/

// 📱 Device Management
export const deviceQueries = {
  all: () => ['devices'] as const,
  
  // Maps to: api.device.list(token, pageIdx, take, order, searchQuery, filterColumn, filtersFromUrl)
  list: (params: {
    pageIdx?: number;
    take?: number; 
    order?: string;
    searchQuery?: string;
    filterColumn?: string;
    filtersFromUrl?: Record<string, string | undefined>; // ✅ Updated type
  }) => [...deviceQueries.all(), 'list', params] as const,
  
  // Maps to: api.device.get(token, deviceId)  
  detail: (deviceId: string) => ['device', deviceId] as const,
  
  // ✅ NEW: Maps to: api.device.getWithProductAndOrganization(token, page, take, order, searchQuery, filterColumn, filtersFromUrl)
  withProductAndOrganization: (params: {
    page?: number;
    take?: number;
    order?: string;
    searchQuery?: string;
    filterColumn?: string;
    filtersFromUrl?: Record<string, string | undefined>;
  }) => [...deviceQueries.all(), 'withProductAndOrganization', params] as const,
  
  // Maps to: api.device.getTypes(token, pageIdx, take, order)
  types: (params: { pageIdx?: number; take?: number; order?: string }) => 
    ['device-types', params] as const,
};

// 🏷️ Tag Management  
export const tagQueries = {
  all: () => ['tags'] as const,
  
  // Maps to: api.tag.list(token, searchQuery, filterColumn, filtersFromUrl, take)
  list: (params: {
    searchQuery?: string;
    filterColumn?: string; 
    filtersFromUrl?: Record<string, string>;
    take?: number;
  }) => [...tagQueries.all(), params] as const,
  
  // Maps to: api.tag.get(token, tagId)
  detail: (tagId: string) => ['tag', tagId] as const,
};

// 📊 Project Management
export const projectQueries = {
  all: () => ['projects'] as const,
  
  // Maps to: api.project.list(...)
  list: (params: any) => [...projectQueries.all(), params] as const,
  
  // Maps to: api.project.get(token, projectId)
  detail: (projectId: string) => ['project', projectId] as const,
  
  // Maps to: api.projectDashboard methods
  dashboard: () => ['project-dashboard'] as const,
};

// 🏢 Organization Management
export const organizationQueries = {
  all: () => ['organizations'] as const,
  
  list: (params: any) => [...organizationQueries.all(), params] as const,
  detail: (orgId: string) => ['organization', orgId] as const,
};

// 👥 User Management
export const userQueries = {
  all: () => ['users'] as const,
  
  list: (params: any) => [...userQueries.all(), params] as const,
  detail: (userId: string) => ['user', userId] as const,
};

// 🔀 Business Flow Management  
export const businessFlowQueries = {
  all: () => ['business-flows'] as const,
  
  list: (params: any) => [...businessFlowQueries.all(), params] as const,
  detail: (flowId: string) => ['business-flow', flowId] as const,
};

// 📊 Device Events
export const deviceEventQueries = {
  all: () => ['device-events'] as const,
  
  list: (params: any) => [...deviceEventQueries.all(), params] as const,
};

// 🗺️ Azure Digital Twin
export const azureDigitalTwinQueries = {
  all: () => ['azure-digital-twin'] as const,
  
  // Add specific queries based on your api.azureDigitalTwin methods
};

// 🎛️ Configuration Templates
export const configTemplateQueries = {
  all: () => ['config-templates'] as const,
  
  list: (params: any) => [...configTemplateQueries.all(), params] as const,
  detail: (templateId: string) => ['config-template', templateId] as const,
  
  commands: () => ['config-template-commands'] as const,
  executed: () => ['executed-config-templates'] as const,
};

🔍 Concrete Usage Examples with Your Real API:

// 📱 DeviceTableForm.tsx - REAL IMPLEMENTATION from our Device Dashboard
import { deviceQueries } from '@/lib/queries/device-queries';
import { useDevicesWithProductAndOrganization } from '@/hooks/devices';

export default function DeviceTableForm(props: Props) {
  const searchParams = useSearchParams();
  
  // 🎯 Extract URL parameters exactly like our real implementation
  const page = parseInt(searchParams?.get("page") || "1");
  const take = parseInt(searchParams?.get("take") || "10");
  const order = (searchParams?.get("order") as "ASC" | "DESC") || "DESC";
  const searchQuery = searchParams?.get("q") || "";
  const filterParams: { [key: string]: string | undefined } = {};
  searchParams?.forEach((value, key) => {
    if (!["page", "take", "order", "q"].includes(key)) {
      filterParams[key] = value;
    }
  });

  // ✅ REAL HOOK: Using our actual useDevicesWithProductAndOrganization
  const {
    data: devicesWithProductAndOrganization,
    isLoading,
    error,
  } = useDevicesWithProductAndOrganization(
    props.token, page, take, order, searchQuery, "", filterParams
  );

  // 🎯 Query key is automatically generated by our factory:
  // deviceQueries.withProductAndOrganization({ page, take, order, searchQuery, filterColumn: "", filtersFromUrl: filterParams })
  // Results in: ["devices", "withProductAndOrganization", { page: 1, take: 10, order: "DESC", searchQuery: "", filterColumn: "", filtersFromUrl: {...} }]

  const allDevices = devicesWithProductAndOrganization?.data || [];
  const meta = devicesWithProductAndOrganization?.meta || { page: 1, take: 10, itemCount: 0, pageCount: 1, hasPreviousPage: false, hasNextPage: false };

  if (isLoading) return <LoadingSkeleton />;
  if (error) return <ErrorDisplay error={error} />;

  return (
    <DataTable
      data={allDevices}
      pageCount={Math.ceil(meta.itemCount / meta.take)}
      currentPage={meta.page}
      take={meta.take}
      itemCount={meta.itemCount}
      onPageChange={handlePageChange} // Automatic refetch via URL change
      // ... other props
    />
  );
}

// 🔄 Example: Invalidation after device mutation
const updateDeviceMutation = useMutation({
  mutationFn: (params) => api.device.update(params.token, params.deviceId, params.data),
  onSuccess: (updatedDevice, variables) => {
    // 🎯 Invalidate using our query factory
    queryClient.invalidateQueries({ 
      queryKey: deviceQueries.withProductAndOrganization({}) // Invalidates all device dashboard queries
    });
    queryClient.invalidateQueries({ 
      queryKey: deviceQueries.detail(variables.deviceId) // Invalidates specific device
    });
  },
});

// 🔍 Advanced: Complex filtering with factory
function DeviceFilters() {
  const [filters, setFilters] = useState({ status: 'online', type: 'sensor' });
  
  // Multiple queries with same factory, different parameters
  const { data: onlineSensors } = useQuery({
    queryKey: deviceQueries.withProductAndOrganization({
      page: 1,
      take: 50,
      filtersFromUrl: { status: 'online', type: 'sensor' }
    }),
    queryFn: () => api.device.getWithProductAndOrganization(token, 1, 50, "DESC", "", "", { status: 'online', type: 'sensor' }),
  });
  
  const { data: offlineGateways } = useQuery({
    queryKey: deviceQueries.withProductAndOrganization({
      page: 1,
      take: 20,
      filtersFromUrl: { status: 'offline', type: 'gateway' }
    }),
    queryFn: () => api.device.getWithProductAndOrganization(token, 1, 20, "DESC", "", "", { status: 'offline', type: 'gateway' }),
  });
  
  // 🎯 Each query has its own cache entry, managed independently
  return (
    <div>
      <DeviceGrid title="Online Sensors" devices={onlineSensors?.data} />
      <DeviceGrid title="Offline Gateways" devices={offlineGateways?.data} />
    </div>
  );
}

// 🏷️ TagEditor.tsx - Tag management with proper invalidation
function TagEditor({ tagId }: { tagId: string }) {
  const { data: token } = useSession();
  const queryClient = useQueryClient();

  // Get single tag (uses your real api.tag.get method)
  const { data: tag } = useQuery({
    queryKey: tagQueries.detail(tagId),
    queryFn: () => api.tag.get(token, tagId),
    enabled: !!tagId && !!token,
  });

  // Update tag mutation (uses your real api.tag.update method)
  const updateTagMutation = useMutation({
    mutationFn: (data: any) => api.tag.update(token, tagId, data),
    onSuccess: () => {
      // 🎯 Precise invalidation using your query keys
      queryClient.invalidateQueries({ queryKey: tagQueries.detail(tagId) });
      queryClient.invalidateQueries({ queryKey: tagQueries.all() }); // Update lists
    },
  });

  // Delete tag mutation (uses your real api.tag.delete method)
  const deleteTagMutation = useMutation({
    mutationFn: () => api.tag.delete(token, tagId),
    onSuccess: () => {
      // Remove from cache and update lists
      queryClient.removeQueries({ queryKey: tagQueries.detail(tagId) });
      queryClient.invalidateQueries({ queryKey: tagQueries.all() });
      
      // Also invalidate devices that might have this tag
      queryClient.invalidateQueries({ queryKey: deviceQueries.all() });
    },
  });

  return (
    <TagForm 
      tag={tag}
      onSave={updateTagMutation.mutate}
      onDelete={deleteTagMutation.mutate}
    />
  );
}

// 📊 ProjectDashboard.tsx - Complex multi-domain queries
function ProjectDashboard({ projectId }: { projectId: string }) {
  const { data: token } = useSession();

  // Project details (uses your real api.project.get method)
  const { data: project } = useQuery({
    queryKey: projectQueries.detail(projectId),
    queryFn: () => api.project.get(token, projectId),
    enabled: !!projectId && !!token,
  });

  // Project devices (filtered by project)
  const { data: projectDevices } = useQuery({
    queryKey: deviceQueries.list({
      filtersFromUrl: { projectId }
    }),
    queryFn: () => api.device.list(token, 1, 100, "DESC", "", undefined, { projectId }),
    enabled: !!projectId && !!token,
  });

  // Project dashboard data (uses your real api.projectDashboard methods)
  const { data: dashboardData } = useQuery({
    queryKey: projectQueries.dashboard(),
    queryFn: () => api.projectDashboard.getData(token, projectId),
    enabled: !!projectId && !!token,
    refetchInterval: 30 * 1000, // Refresh dashboard every 30s
  });

  return (
    <div>
      <ProjectHeader project={project} />
      <DashboardMetrics data={dashboardData} />
      <DevicesList devices={projectDevices?.data} />
    </div>
  );
}

🎯 Best Practices for Your Query Keys:

1. 📁 Store your query factories in a dedicated file:

   // src/lib/queries/index.ts
   export * from './device-queries';
   export * from './tag-queries';
   export * from './project-queries';
   // ... etc

2. 🔄 Use consistent patterns across your app:

   // ✅ Good - Consistent pattern
   const { data } = useQuery({
     queryKey: deviceQueries.list(params),
     queryFn: () => api.device.list(token, ...params),
   });
   
   // ❌ Avoid - Inconsistent keys  
   const { data } = useQuery({
     queryKey: ['random-device-key', params], // Doesn't match your API structure
   });

3. 🎯 Invalidation strategies for your IoT platform:

   // When a device is updated, invalidate related data
   onSuccess: () => {
     queryClient.invalidateQueries({ queryKey: deviceQueries.detail(deviceId) });
     queryClient.invalidateQueries({ queryKey: deviceQueries.all() });
     queryClient.invalidateQueries({ queryKey: projectQueries.all() }); // If device belongs to projects
   };

✅ This approach gives you:

• Perfect alignment between your NestJS API and frontend queries
• Zero confusion about cache keys and invalidation
• Type-safe query keys that match your API signatures
• Easy debugging - query keys mirror your API endpoints exactly
• Consistent patterns your whole team can follow

---

🛠️ Mutations with intelligent invalidation:

// ⚡ Example: Restart an IoT device
const restartDeviceMutation = useMutation({
  mutationFn: (deviceId: string) => api.devices.restart(deviceId),
  onSuccess: (updatedDevice, deviceId) => {
    
    // 🎯 STRATEGY 1: Precise invalidation
    // Invalidate only data affected by restart
    
    // ❌ Invalidate specific device (status changed)
    queryClient.invalidateQueries({ 
      queryKey: deviceQueries.detail(deviceId) 
    });
    
    // ❌ Invalidate telemetry (new data after restart)  
    queryClient.invalidateQueries({ 
      queryKey: deviceQueries.telemetry(deviceId)
    });
    
    // ❌ Invalidate lists (status may have changed device in filters)
    queryClient.invalidateQueries({ 
      queryKey: deviceQueries.lists() 
    });
    
    // ✅ Keep unaffected data intact (other devices, etc.)
  }
});

// 🔄 Example: Bulk update multiple devices
const bulkUpdateDevicesMutation = useMutation({
  mutationFn: (deviceIds: string[]) => api.devices.bulkUpdate(deviceIds),
  onSuccess: (updatedDevices, deviceIds) => {
    
    // 🎯 STRATEGY 2: Broad invalidation (simpler, less optimized)
    // When many devices are affected, invalidate everything
    
    queryClient.invalidateQueries({ 
      queryKey: deviceQueries.all() // Invalidate ['devices'] and everything starting with it
    });
    
    // Result: All device queries are invalidated and refetch automatically
  }
});

🧩 Why this structure works so well?

# 🎯 Cache keys structure in React Query DevTools:
├── ['devices'] 
│   ├── ['devices', 'list']
│   │   ├── ['devices', 'list', { type: 'sensor', status: 'online' }] ✅ Cached
│   │   ├── ['devices', 'list', { type: 'gateway', status: 'online' }] ✅ Cached  
│   │   └── ['devices', 'list', { type: 'sensor', status: 'offline' }] ✅ Cached
│   ├── ['devices', 'detail'] 
│   │   ├── ['devices', 'detail', 'device-123'] ✅ Cached
│   │   │   └── ['devices', 'detail', 'device-123', 'telemetry'] ✅ Cached
│   │   └── ['devices', 'detail', 'device-456'] ✅ Cached
│   └── ...

💡 Concrete advantages:

1. 🎯 Precise invalidation: queryClient.invalidateQueries({ queryKey: deviceQueries.lists() }) invalidates all lists but keeps details
2. 📊 Optimal cache: Each filter combination has its own cache
3. 🚀 Performance: No unnecessary re-fetch of unaffected data
4. 🛠️ Maintenance: Predictable structure and easy to debug
5. 🔄 Synchronization: Related data updates together

🚨 Example of invalidation during device update:

// When updating device-123:
queryClient.invalidateQueries({ queryKey: deviceQueries.detail('device-123') });

// ✅ Will be invalidated and refetched:
// - ['devices', 'detail', 'device-123']  
// - ['devices', 'detail', 'device-123', 'telemetry']

// ✅ Will remain cached (not affected):
// - ['devices', 'detail', 'device-456']
// - ['devices', 'list', { type: 'sensor' }]
// - All other data

---

🛠️ Migration Guidelines: Server to Client Components

Based on our real Device Dashboard migration, here's a comprehensive guide for migrating other pages in your IoT platform.

🤔 Decision Matrix: When to Migrate

Scenario	Keep Server	Migrate to Client + TanStack Query	Use Hybrid
Static content pages	✅ Best	❌ Over-engineering	❌ Unnecessary
SEO-critical pages	✅ Best	❌ Poor SEO	🟡 Consider hybrid
Interactive dashboards	❌ Poor UX	✅ Best	🟡 Good alternative
Forms with validation	❌ Hard to manage	✅ Best	❌ Complex
Real-time data	❌ Won't work	✅ Best	❌ Mixed approaches
Paginated/filtered lists	🟡 Slow navigation	✅ Best	🟡 Good alternative

🚀 Migration Patterns

Pattern 1: Pure Client Migration (Our Device Dashboard)

Best for: Interactive dashboards, real-time data, complex filtering

// ✅ When to use: High interactivity, frequent updates, complex state
// ❌ When to avoid: SEO requirements, static content

// Before: Server Component
const ServerDevicePage = async ({ searchParams }) => {
  const data = await api.device.getWithProductAndOrganization(/* ... */);
  return <DeviceTable data={data} />;
};

// After: Client Component + TanStack Query
const ClientDevicePage = ({ token, lang, /* static props */ }) => {
  return <DeviceTableForm token={token} lang={lang} />;
};

// DeviceTableForm internally uses:
const { data, isLoading, error } = useDevicesWithProductAndOrganization(/* params */);

Pattern 2: Hybrid Approach (Recommended for SEO-sensitive pages)

Best for: Pages that need both SEO and interactivity

// ✅ Best of both worlds: SEO + Client interactivity
const HybridDevicePage = async ({ searchParams, params }) => {
  // 🟢 Server-side: Initial data for SEO and fast first paint
  const initialData = await api.device.getWithProductAndOrganization(
    serverToken, 1, 10, "DESC", "", "", {}
  );
  
  const { datatable, pages } = await getDictionary(params.lang);
  
  return (
    <Dashboard>
      <DeviceTableFormHybrid
        initialData={initialData}    // 🎯 Pre-populate cache
        token={session.token}
        lang={params.lang}
        datatable={datatable}
        dialog={pages.resources.dialog}
        roles={session.roles}
      />
    </Dashboard>
  );
};

// Client component with initial data
const DeviceTableFormHybrid = ({ initialData, ...props }) => {
  const { data, isLoading } = useDevicesWithProductAndOrganization(
    props.token, page, take, order, searchQuery, "", filterParams,
    {
      initialData,           // 🚀 Immediate rendering with server data
      staleTime: 60 * 1000, // Fresh for 1 minute
    }
  );
  
  // First render: shows initialData immediately
  // Background: TanStack Query manages updates, cache, etc.
  return <DataTable data={data?.data || []} />; 
};

Pattern 3: Progressive Enhancement

Best for: Gradual migration of large applications

// 🔄 Step 1: Keep server component, add client features
const ProgressiveDevicePage = async ({ searchParams }) => {
  const serverData = await api.device.getWithProductAndOrganization(/* ... */);
  
  return (
    <Dashboard>
      <DeviceTableServerBased data={serverData} />
      {/* ✅ Add client-only features progressively */}
      <ClientOnlyFeatures>
        <RealTimeStatusIndicator />
        <AdvancedFilters />
      </ClientOnlyFeatures>
    </Dashboard>
  );
};

// 🔄 Step 2: Gradually replace server features with client
// 🔄 Step 3: Eventually full client migration when ready

📋 Step-by-Step Migration Checklist

Phase 1: Preparation

• Identify pages with high interactivity (pagination, filtering, real-time updates)
• Check if page needs SEO (public pages = keep server, dashboards = migrate)
• Create TanStack Query hooks for existing API calls
• Set up Query Keys factories for organized cache management

Phase 2: Hook Creation

• Create custom hook (e.g., useDevicesWithProductAndOrganization)
• Import existing API methods (no need to change)
• Add proper TypeScript types from @pxs/database
• Test hook in isolation

Phase 3: Component Migration

• Add "use client" directive to component
• Replace server props with hook calls
• Add loading and error states
• Simplify pagination/filtering logic (URL-based)
• Remove server-side data fetching from parent

Phase 4: Testing & Optimization

• Test all user interactions (pagination, filtering, search)
• Verify cache behavior with React Query DevTools
• Check performance with bundle analysis
• Validate error handling and retry logic

🎯 Application to Your IoT Platform

Immediate candidates for migration:

• ✅ Tag management pages - High CRUD interactivity
• ✅ User management dashboards - Real-time status updates
• ✅ Project dashboards - Complex filtering and analytics
• ✅ Device configuration pages - Form-heavy with validation

Keep as Server Components:

• ✅ Landing pages - Static content, SEO important
• ✅ Documentation - Static, indexable content
• ✅ Error pages - Simple, fast rendering needed

Consider hybrid approach:

• 🟡 Device detail pages - Need SEO but have interactive features
• 🟡 Report pages - Large datasets with export features
• 🟡 Public dashboards - Shareable but interactive

🔧 Common Migration Patterns

// 🔄 Pattern: URL State Management
// Before: Complex server-side parameter processing
// After: Simple URL-based state with automatic refetching

const useUrlParams = () => {
  const searchParams = useSearchParams();
  return {
    page: parseInt(searchParams?.get("page") || "1"),
    filters: Object.fromEntries(
      Array.from(searchParams?.entries() || []).filter(([key]) => 
        !["page", "take", "order", "q"].includes(key)
      )
    )
  };
};

// 🔄 Pattern: Loading States
// Before: Blank page during server render
// After: Progressive loading with skeletons

const LoadingStates = ({ isLoading, error, data, children }) => {
  if (isLoading) return <DataTableSkeleton />;
  if (error) return <ErrorBoundary error={error} />;
  return children({ data });
};

// 🔄 Pattern: Error Recovery
// Before: Full page error, requires page reload
// After: Component-level error with retry

const ErrorBoundary = ({ error, onRetry }) => (
  <div className="p-8 text-center">
    <p className="text-red-600">Failed to load data</p>
    <button onClick={onRetry} className="mt-4 px-4 py-2 bg-blue-600 text-white rounded">
      Retry
    </button>
  </div>
);

🎯 Expected Results After Migration:

• Performance: 60-80% cache hit ratio, instant navigation
• UX: Smooth loading states, optimistic updates, error recovery
• DX: React/TanStack Query DevTools, better debugging
• Maintainability: Cleaner separation of concerns, reusable hooks

---

Error Handling with Your AbstractAPI Integration

Your AbstractAPI class already provides excellent error handling that integrates perfectly with TanStack Query. Here's how they work together:

🏗️ Your Existing AbstractAPI Error Handling:

// Your AbstractAPI.handleError() already handles:
export class AbstractAPI {
  handleError(body: any) {
    // 🔓 Automatic auth redirect
    if (body?.title?.toLowerCase() === "unauthorized") {
      console.log("Error is unauthorized, redirecting to login");
      return redirect("/auth/login"); // ✅ Seamless auth handling
    }

    // 🔍 NestJS validation error parsing
    if (Object.keys(body).indexOf("invalid_params") > -1) {
      for (const item of body.invalid_params as ValidationErrorItem[]) {
        error += `${item.property}:\n`;
        for (const constraint in item.constraints) {
          error += ` - ${item.constraints[constraint]}\n`;
        }
      }
    } else {
      error = body?.message;
    }
    
    // Structured error ready for UI consumption
  }
}

🎯 TanStack Query + AbstractAPI Integration:

// Your existing API calls work perfectly with TanStack Query
export function useTag(tagId: string, token: string) {
  return useQuery({
    queryKey: ["tag", tagId],
    queryFn: () => api.tag.get(token, tagId), // Uses your AbstractAPI
    enabled: !!tagId && !!token,
    
    // 🛡️ Let your AbstractAPI handle errors automatically:
    throwOnError: false, // AbstractAPI.handleError() processes errors
    
    // 🔄 Smart retry logic that works with your backend
    retry: (failureCount, error) => {
      // Your AbstractAPI already handled 401s (redirect to login)
      // Don't retry client errors (400-499)
      if (error?.status >= 400 && error?.status < 500) {
        return false;
      }
      
      // Retry server errors (500+) up to 2 times
      return failureCount < 2;
    },
  });
}

// Device example with your real error handling
export function useDevices(token: string, filters = {}) {
  return useQuery({
    queryKey: ["devices", filters],
    queryFn: () => api.device.list(token, 1, 10, "DESC", "", undefined, filters),
    enabled: !!token,
    
    // Your AbstractAPI handles:
    // ✅ 401 → Automatic redirect to /auth/login  
    // ✅ Validation errors → Parsed and formatted
    // ✅ Network errors → Proper APIError thrown
    // ✅ Cookie/header forwarding → SSR/CSR compatibility
  });
}

// Usage with your error handling
function DeviceList() {
  const { data: token } = useSession();
  const { data: devicesPage, isLoading, error } = useDevices(token);
  
  if (isLoading) return <DeviceListSkeleton />;
  
  // 🎯 Error handling leverages your AbstractAPI processing
  if (error) {
    // Your AbstractAPI already:
    // - Redirected on 401 (user won't see this)
    // - Parsed validation errors into readable format
    // - Handled network issues appropriately
    
    return (
      <ErrorCard 
        title="Unable to load devices"
        message={error.message || "Please try again"}
        onRetry={() => queryClient.invalidateQueries(["devices"])}
      />
    );
  }
  
  return (
    <div>
      {devicesPage?.data.map(device => (
        <DeviceCard key={device.id} device={device} />
      ))}
    </div>
  );
}

// 🌍 Optional: Global Error Handling (complements your AbstractAPI)
const queryClient = new QueryClient({
  queryCache: new QueryCache({
    onError: (error, query) => {
      // Your AbstractAPI already handled most errors, but you can add:
      
      // 📊 Analytics/Monitoring
      console.error('TanStack Query failed:', query.queryKey, error);
      
      // 🔔 Global notifications for specific cases
      if (error?.message?.includes('Network')) {
        toast({
          title: "Connection Issue",
          description: "Please check your internet connection",
          variant: "destructive"
        });
      }
    },
  }),
  
  mutationCache: new MutationCache({
    onError: (error, variables, context, mutation) => {
      // Your AbstractAPI handles validation errors, but you can add:
      
      // 📈 Track mutation failures
      console.error('Mutation failed:', mutation.options.mutationKey, error);
      
      // 🚨 Critical operation failures
      if (mutation.options.mutationKey?.includes('device-control')) {
        toast({
          title: "Device Control Failed",
          description: "Unable to control device. Please try again.",
          variant: "destructive"
        });
      }
    }
  })
});

✅ Key Advantages of This Integration:

1. 🔄 Zero Configuration - Your AbstractAPI works out-of-the-box with TanStack Query
2. 🛡️ Centralized Error Handling - One place to manage all API error logic
3. 🔓 Seamless Authentication - 401s handled automatically with redirects
4. 📝 NestJS Validation Integration - ValidationErrorItem[] properly parsed
5. 🌐 SSR/CSR Compatibility - Cookie and header forwarding handled automatically
6. 📊 Consistent Error Format - Same error structure across your app

🎯 This means your developers:

• Don't need to learn new error handling patterns
• Can focus on business logic, not infrastructure
• Get consistent error behavior across all API calls
• Have automatic authentication flow management

---

Advanced Patterns (Like NestJS Advanced Features)

🔄 Background Refetching (Like Cron Jobs)

// ↔ NestJS: @Cron('*/30 * * * * *') // Every 30 seconds
// async updateDeviceStatuses() {
//   await this.devicesService.refreshStatuses();
// }

// Frontend: Background data refresh
const { data: deviceStatuses } = useQuery({
  queryKey: ['device-statuses'],
  queryFn: () => api.devices.getStatuses(),
  
  // 🔄 Background updates (like scheduled tasks)
  refetchInterval: 30 * 1000,        // Refresh every 30 seconds
  refetchIntervalInBackground: true, // Continue even when tab is not active
  
  // Only refetch if data is stale
  refetchOnMount: 'always',          // Like service restart behavior
});

🤝 Dependent Queries (Like Service Dependencies)

// ↔ NestJS: Service dependency injection
// constructor(
//   private userService: UserService,
//   private profileService: ProfileService, // Depends on user
// ) {}

// Frontend: Chain dependent queries
function UserProfile({ userId }: { userId: string }) {
  // First query: Get user (like injecting UserService)
  const { data: user, isLoading: userLoading } = useQuery({
    queryKey: ['user', userId],
    queryFn: () => api.users.getById(userId),
  });
  
  // Second query: Get user profile (depends on user data)
  const { data: profile, isLoading: profileLoading } = useQuery({
    queryKey: ['profile', user?.profileId],
    queryFn: () => api.profiles.getById(user.profileId),
    
    // 🔗 Dependency: Only run after user is loaded
    enabled: !!user?.profileId, // Like conditional service injection
  });
  
  if (userLoading) return <div>Loading user...</div>;
  if (profileLoading) return <div>Loading profile...</div>;
  
  return <UserProfileDisplay user={user} profile={profile} />;
}

⚡ Optimistic Updates (Like Database Transactions)

// ↔ NestJS: Database transaction with rollback
// async updateUser(id: string, data: UpdateUserDto) {
//   const queryRunner = this.connection.createQueryRunner();
//   await queryRunner.startTransaction();
//   try {
//     const updated = await queryRunner.manager.save(User, { id, ...data });
//     await queryRunner.commitTransaction();
//     return updated;
//   } catch (err) {
//     await queryRunner.rollbackTransaction(); // Rollback on error
//     throw err;
//   }
// }

// Frontend: Optimistic update with rollback
const useUpdateUserOptimistic = () => {
  const queryClient = useQueryClient();
  
  return useMutation({
    mutationFn: api.users.update,
    
    // 🚀 Optimistic update (like immediate DB write)
    onMutate: async (newUserData) => {
      // Cancel outgoing refetches (like locking)
      await queryClient.cancelQueries({ queryKey: ['user', newUserData.id] });
      
      // Snapshot previous value (like transaction backup)
      const previousUser = queryClient.getQueryData(['user', newUserData.id]);
      
      // Optimistically update to new value (like immediate response)
      queryClient.setQueryData(['user', newUserData.id], newUserData);
      
      // Return context for rollback
      return { previousUser, userId: newUserData.id };
    },
    
    // ❌ Rollback on error (like transaction rollback)
    onError: (err, newUserData, context) => {
      if (context?.previousUser) {
        queryClient.setQueryData(['user', context.userId], context.previousUser);
      }
      toast({ title: "Error", content: "Update failed, changes reverted" });
    },
    
    // ✅ Confirm success (like transaction commit)
    onSettled: (data, error, variables) => {
      // Always refetch to ensure consistency (like refresh from DB)
      queryClient.invalidateQueries({ queryKey: ['user', variables.id] });
    },
  });
};

---

Debugging TanStack Query (Like NestJS Logging)

🔍 React Query DevTools (Like NestJS Logger)

// ↔ NestJS: Built-in logger
// @Injectable()
// export class MyService {
//   private readonly logger = new Logger(MyService.name);
//   
//   async getData() {
//     this.logger.log('Fetching data...');
//     this.logger.debug('Cache hit/miss');
//   }
// }

// Frontend: Enable DevTools for debugging
import { ReactQueryDevtools } from '@tanstack/react-query-devtools';

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      {/* Your app */}
      
      {/* 🔍 DevTools: Like NestJS Logger in development */}
      <ReactQueryDevtools 
        initialIsOpen={false}
        buttonPosition="bottom-right"
      />
    </QueryClientProvider>
  );
}

// What you can see in DevTools:
// 📊 All active queries (like active connections)
// 💾 Cache contents (like Redis cache inspection) 
// 🔄 Query status (fresh, stale, fetching)
// 📈 Query timelines (like request logs)
// 🗑️ Cache invalidation events (like cache evictions)

📊 Query Client Debugging (Like Health Checks)

// ↔ NestJS: Health check endpoint
// @Get('health')
// @HealthCheck()
// check() {
//   return this.health.check([
//     () => this.db.pingCheck('database'),
//     () => this.redis.pingCheck('redis'),
//   ]);
// }

// Frontend: Query client inspection
function DebugPanel() {
  const queryClient = useQueryClient();
  
  // 📊 Get cache stats (like health check)
  const cacheStats = {
    queries: queryClient.getQueryCache().getAll().length,
    mutations: queryClient.getMutationCache().getAll().length,
    
    // Detailed query states
    fresh: queryClient.getQueryCache().getAll().filter(q => q.state.dataUpdatedAt > Date.now() - 60000).length,
    stale: queryClient.getQueryCache().getAll().filter(q => q.isStale()).length,
    fetching: queryClient.getQueryCache().getAll().filter(q => q.state.isFetching).length,
  };
  
  // 🔍 Log cache contents (like Redis scan)
  const logCache = () => {
    queryClient.getQueryCache().getAll().forEach(query => {
      console.log('Query:', query.queryKey, {
        status: query.state.status,
        dataUpdatedAt: new Date(query.state.dataUpdatedAt),
        isStale: query.isStale(),
        observers: query.getObserversCount(),
      });
    });
  };
  
  return (
    <div className="p-4 border rounded">
      <h3>TanStack Query Debug Panel</h3>
      <div>Active Queries: {cacheStats.queries}</div>
      <div>Fresh: {cacheStats.fresh} | Stale: {cacheStats.stale} | Fetching: {cacheStats.fetching}</div>
      <button onClick={logCache}>Log Cache Contents</button>
    </div>
  );
}

⚠️ Common Issues & Solutions

// 🚨 Issue: Queries not updating after mutations
// ❌ Wrong: Forgot cache invalidation
const updateMutation = useMutation({
  mutationFn: api.users.update,
  // Missing onSuccess invalidation!
});

// ✅ Solution: Always invalidate related queries
const updateMutation = useMutation({
  mutationFn: api.users.update,
  onSuccess: (data, variables) => {
    queryClient.invalidateQueries({ queryKey: ['users'] });
    queryClient.invalidateQueries({ queryKey: ['user', variables.id] });
  },
});

// 🚨 Issue: Too many API calls
// ❌ Wrong: Default staleTime is 0 (always refetch)
const { data } = useQuery({
  queryKey: ['users'],
  queryFn: fetchUsers,
  // Refetches on every component mount!
});

// ✅ Solution: Set appropriate staleTime
const { data } = useQuery({
  queryKey: ['users'],
  queryFn: fetchUsers,
  staleTime: 5 * 60 * 1000, // 5 minutes fresh
});

// 🚨 Issue: Queries running when they shouldn't
// ❌ Wrong: Missing enabled condition
const { data } = useQuery({
  queryKey: ['user', userId],
  queryFn: () => fetchUser(userId),
  // Runs even when userId is null/undefined!
});

// ✅ Solution: Use enabled condition
const { data } = useQuery({
  queryKey: ['user', userId],
  queryFn: () => fetchUser(userId),
  enabled: !!userId, // Only run when userId exists
});

🔗 Documentation Links:

• TanStack Query Docs
• DevTools Guide
• Caching Examples
• Error Handling

---

🧠 Client-Side State Management

⚠️ Implementation Status: This section contains the complete architecture and examples for Zustand integration. The actual implementation in the codebase is in progress. See the Getting Started with Zustand tutorial at the end of this section to begin implementation.

Client-side state management complements our server state (TanStack Query) and form state (React Hook Form) strategies, providing optimal performance and developer experience for UI state, user preferences, and complex interactions.

🎯 State Management Strategy

Our approach uses a complementary trio:

• TanStack Query: Server state (API data, caching, synchronization)
• React Hook Form: Form state (validation, submission, temporary input)
• Zustand + Context: Client state (UI state, preferences, application logic)

📊 Decision Matrix: When to Use What

Scenario	useState	Context API	Zustand	Example
Component-local UI	✅ Best	❌ Over-engineering	❌ Over-engineering	Toggle button, local loading
Tree-scoped config	❌ Prop drilling	✅ Best	❌ Over-engineering	Theme, modal provider
Global app state	❌ Won't work	🟡 Performance risk	✅ Best	User prefs, device filters
Complex logic	❌ Hard to maintain	🟡 Context hell	✅ Best	Multi-step wizards, bulk ops
Persist to storage	❌ Manual work	❌ Manual work	✅ Built-in	Settings, recent searches

🔗 Zustand + TanStack Query Integration Patterns

🤔 Filter Store Architecture: Specific vs Generic

Architectural question: Why create useDeviceFilters instead of a generic useFilters store?

🎯 Approach comparison:

Aspect	Generic Store	Specific Stores
Complexity	🟡 Simpler at start	🟢 Simple to maintain long term
Type Safety	🔴 Complex generic types	🟢 Precise and simple types
Reusability	🟢 Single implementation	🟡 Apparent code duplication
Business Logic	🔴 Hard to customize	🟢 Specialized business logic
Performance	🟡 Potential re-renders	🟢 Targeted optimizations

💡 Why specific stores in our IoT context:

// ❌ Generic approach - hidden complexity
interface GenericFiltersStore<T> {
  filters: Record<string, any>;
  setFilter: <K extends keyof T>(key: K, value: T[K]) => void;
  resetFilters: () => void;
  // 🚨 Problems:
  // - Complex generic types
  // - No business validation
  // - Generic reset logic
}

// ✅ Specific approach - clarity and power
interface DeviceFiltersStore {
  filters: {
    type: DeviceType | 'all';           // 🎯 Precise types
    status: DeviceStatus;               // 🎯 Business enumerations
    location: GeoLocation | null;       // 🎯 Complex objects
    dateRange: DateRange | null;        // 🎯 Composite types
  };
  
  // 🎯 Specialized business methods
  setDeviceType: (type: DeviceType | 'all') => void;
  setLocationFilter: (bounds: GeoBounds) => void;
  clearLocationFilter: () => void;
  
  // 🎯 Specific business logic
  resetToDefaults: () => void; // Reset with IoT default values
  hasActiveFilters: () => boolean; // Specific detection logic
  getQueryParams: () => URLSearchParams; // Serialization for APIs
}

🔍 IoT Platform use cases that justify specialization:

// 🏭 Device Filters - Specific business complexity
const useDeviceFilters = create<DeviceFiltersStore>((set, get) => ({
  filters: {
    type: 'all',
    status: 'online',
    location: null,
    dateRange: null,
    // 🎯 Specialized IoT filters
    connectivityProtocol: null,        // LoRa, NB-IoT, WiFi...
    batteryLevel: { min: 0, max: 100 },
    signalStrength: null,
    lastSeen: '24h',
  },
  
  // 🎯 Methods with business validation
  setBatteryRange: (min: number, max: number) => set(state => ({
    filters: {
      ...state.filters,
      batteryLevel: { 
        min: Math.max(0, min), 
        max: Math.min(100, max) 
      }
    }
  })),
  
  // 🎯 Intelligent reset based on context
  resetToDefaults: () => set({
    filters: {
      type: 'all',
      status: 'online', // ⚠️ IoT default: we want to see active devices
      location: null,
      dateRange: null,
      connectivityProtocol: null,
      batteryLevel: { min: 20, max: 100 }, // ⚠️ Exclude low batteries
      signalStrength: null,
      lastSeen: '24h', // ⚠️ Recent data by default
    }
  }),
  
  // 🎯 Integrated business validation
  hasActiveFilters: () => {
    const { filters } = get();
    return (
      filters.type !== 'all' ||
      filters.status !== 'online' ||
      filters.location !== null ||
      // 🎯 Specific logic: default batteryLevel != active filter
      filters.batteryLevel.min > 20 || filters.batteryLevel.max < 100
    );
  },
  
  // 🎯 Optimized serialization for IoT APIs
  getAPIFilters: () => {
    const { filters } = get();
    // Transform for IoT backend compatibility
    return {
      device_type: filters.type === 'all' ? undefined : filters.type,
      status_filter: filters.status,
      geo_bounds: filters.location?.toBounds(),
      battery_range: filters.batteryLevel.min > 0 ? filters.batteryLevel : undefined,
    };
  },
}));

// 🏢 User Filters - Different HR/Admin logic
const useUserFilters = create<UserFiltersStore>((set, get) => ({
  filters: {
    role: 'all',
    status: 'active',
    organization: null,
    // 🎯 Specialized HR filters
    permissions: [],
    createdAfter: null,
    lastLoginBefore: null,
  },
  
  // 🎯 Reset adapted to user context
  resetToDefaults: () => set({
    filters: {
      role: 'all',
      status: 'active', // ⚠️ HR context: hide inactive users
      organization: null,
      permissions: [],
      createdAfter: null,
      lastLoginBefore: null,
    }
  }),
  
  // 🎯 User business validation
  hasRestrictiveFilters: () => {
    const { filters } = get();
    return filters.permissions.length > 0 || filters.role !== 'all';
  },
}));

📊 When to use a generic store?

✅ Use a generic store when:

• Very simple logic (e.g.: search term, sort order)
• No specific business validation
• Identical types between domains
• Identical reset/transformation needs

❌ Avoid a generic store when:

• Complex and different business validation
• Specialized data types (IoT vs Users vs Organizations)
• Different reset logic depending on context
• Specific transformation/serialization needs

Pattern 1: Reactive Filtering - Dashboard IoT Device Management

🎯 Concrete IoT Use Case: IoT monitoring dashboard with real-time filters for surveillance of 1000+ devices (sensors, gateways, actuators) with different statuses, locations, and connectivity types.

💡 Why this pattern?

• ✅ Automatic reactivity: Filter change → Query refetch automatically
• ✅ Performance: Intelligent cache per filter combination
• ✅ Synchronization: Multiple components use same filters
• ✅ Smooth UX: No props drilling, transparent shared state

// File: src/stores/device/useDeviceFilters.ts
import { create } from 'zustand';
import { devtools, persist } from 'zustand/middleware';
import type { DeviceType, DeviceStatus, GeoLocation, DateRange } from '@/types/iot';

// 📋 Complete types for the store
export interface DeviceFilters {
  type: DeviceType | 'all';
  status: DeviceStatus[];
  location: GeoLocation | null;
  dateRange: DateRange | null;
  batteryLevel: { min: number; max: number } | null;
  connectivityProtocol: string[] | null;
  organizationId: string | null;
}

export interface DeviceFiltersStore {
  // 🎯 State
  filters: DeviceFilters;
  isFiltersChanged: boolean;
  
  // 🎯 Actions with IoT business validation
  setDeviceType: (type: DeviceType | 'all') => void;
  setDeviceStatus: (status: DeviceStatus[]) => void;
  setLocationFilter: (location: GeoLocation | null) => void;
  setDateRange: (range: DateRange | null) => void;
  setBatteryRange: (min: number, max: number) => void;
  setConnectivityFilter: (protocols: string[]) => void;
  setOrganization: (orgId: string | null) => void;
  
  // 🎯 Computed & utilities
  resetFilters: () => void;
  hasActiveFilters: () => boolean;
  getActiveFilterCount: () => number;
  getApiFilters: () => Record<string, any>;
}

// 🏪 Store implementation with IoT business logic
export const useDeviceFilters = create<DeviceFiltersStore>()(
  devtools(
    persist(
      (set, get) => ({
        // 🎯 Initial state with sensible IoT defaults
        filters: {
          type: 'all',
          status: ['online', 'maintenance'], // Default: exclude offline devices
          location: null,
          dateRange: null,
          batteryLevel: { min: 20, max: 100 }, // Exclude critical batteries by default
          connectivityProtocol: null,
          organizationId: null,
        },
        isFiltersChanged: false,

        // 🎯 Actions with business validation
        setDeviceType: (type) => set((state) => ({
          filters: { ...state.filters, type },
          isFiltersChanged: true,
        })),

        setDeviceStatus: (status) => set((state) => ({
          filters: { ...state.filters, status },
          isFiltersChanged: true,
        })),

        setLocationFilter: (location) => set((state) => ({
          filters: { ...state.filters, location },
          isFiltersChanged: true,
        })),

        setBatteryRange: (min, max) => set((state) => ({
          filters: { 
            ...state.filters, 
            batteryLevel: { 
              min: Math.max(0, Math.min(min, 100)), 
              max: Math.max(0, Math.min(max, 100)) 
            }
          },
          isFiltersChanged: true,
        })),

        // 🎯 Smart reset for IoT context
        resetFilters: () => set({
          filters: {
            type: 'all',
            status: ['online', 'maintenance'], // Smart reset: keep active devices
            location: null,
            dateRange: null,
            batteryLevel: { min: 20, max: 100 }, // Reset with sensible battery threshold
            connectivityProtocol: null,
            organizationId: null,
          },
          isFiltersChanged: false,
        }),

        // 🎯 Computed values for UI and API
        hasActiveFilters: () => {
          const { filters } = get();
          return (
            filters.type !== 'all' ||
            !filters.status.includes('offline') ||
            filters.location !== null ||
            filters.dateRange !== null ||
            filters.batteryLevel?.min !== 20 ||
            filters.batteryLevel?.max !== 100 ||
            filters.connectivityProtocol !== null ||
            filters.organizationId !== null
          );
        },

        getActiveFilterCount: () => {
          const { filters } = get();
          let count = 0;
          if (filters.type !== 'all') count++;
          if (!filters.status.includes('offline')) count++;
          if (filters.location) count++;
          if (filters.dateRange) count++;
          if (filters.batteryLevel && (filters.batteryLevel.min > 20 || filters.batteryLevel.max < 100)) count++;
          if (filters.connectivityProtocol?.length) count++;
          if (filters.organizationId) count++;
          return count;
        },

        // 🎯 Transformation for backend API
        getApiFilters: () => {
          const { filters } = get();
          return {
            device_type: filters.type === 'all' ? undefined : filters.type,
            status_in: filters.status,
            geo_bounds: filters.location?.toBounds(),
            created_after: filters.dateRange?.startDate,
            created_before: filters.dateRange?.endDate,
            battery_min: filters.batteryLevel?.min,
            battery_max: filters.batteryLevel?.max,
            protocols: filters.connectivityProtocol,
            organization_id: filters.organizationId,
          };
        },
      }),
      {
        name: 'device-filters', // localStorage key
        partialize: (state) => ({ filters: state.filters }), // Persist only the filters
      }
    )
  )
);

// File: src/components/DeviceList.tsx
import React from 'react';
import { useQuery } from '@tanstack/react-query';
import { useDeviceFilters } from '@/stores/device/useDeviceFilters';
import { deviceQueries } from '@/lib/queries/deviceQueries';
import { api } from '@/lib/api';
import { DeviceGrid } from './DeviceGrid';
import { DeviceListSkeleton } from './DeviceListSkeleton';

// 📱 Main component with automatic reactivity
export const DeviceList = () => {
  // 🏪 Zustand store - reactive to changes
  const { filters, getApiFilters } = useDeviceFilters();
  
  // 🔄 TanStack Query - automatic refetch when filters change
  const { data: devices, isLoading, error, isStale } = useQuery({
    queryKey: deviceQueries.list(filters), // 🎯 Key reactive to Zustand state
    queryFn: () => api.devices.list(getApiFilters()), // 🎯 API call with transformed filters
    staleTime: 5 * 60 * 1000, // 5 minutes cache
    
    // 🎯 Optimized options for IoT monitoring
    refetchOnWindowFocus: true, // Refresh when user returns to app
    refetchInterval: isStale ? 30 * 1000 : false, // Auto refresh if stale
  });

  // 🎯 Loading state with optimized skeleton
  if (isLoading) return <DeviceListSkeleton />;
  
  // 🎯 Error handling
  if (error) {
    return (
      <div className="p-4 text-center">
        <p className="text-red-600">Failed to load devices: {error.message}</p>
        <button 
          onClick={() => window.location.reload()} 
          className="mt-2 px-4 py-2 bg-red-100 rounded"
        >
          Retry
        </button>
      </div>
    );
  }

  return (
    <div>
      {/* 📊 Feedback utilisateur */}
      <div className="flex justify-between items-center mb-4">
        <p className="text-sm text-gray-600">
          {devices?.length || 0} devices found
        </p>
        {isStale && (
          <span className="text-xs text-yellow-600">
            Data may be outdated, refreshing...
          </span>
        )}
      </div>
      
      {/* 📋 Device grid with reactive data */}
      <DeviceGrid devices={devices || []} />
    </div>
  );
};

// File: src/components/DeviceFilters.tsx
import React from 'react';
import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select';
import { Button } from '@/components/ui/button';
import { Badge } from '@/components/ui/badge';
import { Slider } from '@/components/ui/slider';
import { useDeviceFilters } from '@/stores/device/useDeviceFilters';
import { DeviceType, DeviceStatus } from '@/types/iot';

// 🎛️ Filter controls component
export const DeviceFilters = () => {
  // 🏪 Store connection
  const { 
    filters, 
    setDeviceType, 
    setDeviceStatus, 
    setBatteryRange,
    resetFilters, 
    hasActiveFilters,
    getActiveFilterCount 
  } = useDeviceFilters();

  return (
    <div className="p-4 bg-gray-50 rounded-lg space-y-4">
      {/* 📊 Filter status indicator */}
      <div className="flex items-center justify-between">
        <h3 className="text-lg font-medium">Device Filters</h3>
        {hasActiveFilters() && (
          <Badge variant="secondary">
            {getActiveFilterCount()} filters active
          </Badge>
        )}
      </div>

      <div className="grid grid-cols-1 md:grid-cols-4 gap-4">
        {/* 🏭 Device Type Filter */}
        <div>
          <label className="text-sm font-medium mb-2 block">Device Type</label>
          <Select 
            value={filters.type}
            onValueChange={(type: DeviceType | 'all') => setDeviceType(type)}
          >
            <SelectTrigger>
              <SelectValue placeholder="Select type..." />
            </SelectTrigger>
            <SelectContent>
              <SelectItem value="all">All Types</SelectItem>
              <SelectItem value="sensor">🌡️ Sensors</SelectItem>
              <SelectItem value="gateway">📡 Gateways</SelectItem>
              <SelectItem value="actuator">⚙️ Actuators</SelectItem>
              <SelectItem value="controller">🎛️ Controllers</SelectItem>
            </SelectContent>
          </Select>
        </div>

        {/* 🔋 Battery Level Filter */}
        <div>
          <label className="text-sm font-medium mb-2 block">
            Battery Level ({filters.batteryLevel?.min}% - {filters.batteryLevel?.max}%)
          </label>
          <Slider
            value={[filters.batteryLevel?.min || 0, filters.batteryLevel?.max || 100]}
            onValueChange={([min, max]) => setBatteryRange(min, max)}
            max={100}
            min={0}
            step={5}
            className="mt-2"
          />
        </div>

        {/* 🎯 Status Filter - Multi-select */}
        <div>
          <label className="text-sm font-medium mb-2 block">Status</label>
          <div className="flex gap-2 flex-wrap">
            {(['online', 'offline', 'maintenance', 'error'] as DeviceStatus[]).map((status) => (
              <Button
                key={status}
                variant={filters.status.includes(status) ? "default" : "outline"}
                size="sm"
                onClick={() => {
                  const newStatus = filters.status.includes(status)
                    ? filters.status.filter(s => s !== status)
                    : [...filters.status, status];
                  setDeviceStatus(newStatus);
                }}
                className="text-xs"
              >
                {status}
              </Button>
            ))}
          </div>
        </div>

        {/* 🔄 Reset Button */}
        <div className="flex items-end">
          <Button 
            onClick={resetFilters} 
            variant="outline" 
            size="sm"
            disabled={!hasActiveFilters()}
            className="w-full"
          >
            Reset Filters
          </Button>
        </div>
      </div>
    </div>
  );
};

Pattern 2: Bulk Operations State - IoT Device Management

🎯 Concrete IoT Use Case: IoT fleet administration with multiple selection and bulk operations on 100-1000+ devices: mass restart, OTA firmware updates, configuration changes, tag assignment, scheduled maintenance.

💡 Why this pattern?

• ✅ Persistent selection: Keeps selection during navigation/filters
• ✅ Real-time feedback: Bulk operation status with progress
• ✅ Performance: Optimistic updates with rollback on error
• ✅ Professional UX: Robust and predictable IoT admin experience

// File: src/stores/device/useDeviceSelection.ts
import { create } from 'zustand';
import { devtools } from 'zustand/middleware';
import type { Device, BulkOperationType, OperationProgress } from '@/types/iot';

// 📋 Complete types for IoT bulk operations
export type BulkAction = 
  | 'restart'           // Device restart
  | 'update_firmware'   // OTA update
  | 'change_config'     // Configuration change
  | 'assign_tags'       // Tag assignment
  | 'schedule_maintenance' // Maintenance scheduling
  | 'change_organization' // Organization change
  | 'deactivate'        // Deactivation
  | 'factory_reset';    // Factory reset

export interface BulkOperationResult {
  operationType: BulkAction;
  totalDevices: number;
  successfulDevices: string[];
  failedDevices: Array<{ deviceId: string; error: string }>;
  startTime: number;
  endTime?: number;
  progress: OperationProgress;
}

export interface DeviceSelectionStore {
  // 🎯 Selection state
  selectedDevices: Set<string>;
  lastSelectedDevice: string | null;
  selectionMode: 'normal' | 'range' | 'all';
  
  // 🎯 Bulk operation state
  currentBulkOperation: BulkOperationResult | null;
  operationHistory: BulkOperationResult[];
  isOperationInProgress: boolean;
  
  // 🎯 Selection actions
  toggleDevice: (deviceId: string, withShift?: boolean) => void;
  selectAll: (deviceIds: string[]) => void;
  selectNone: () => void;
  selectByFilter: (predicate: (device: Device) => boolean, devices: Device[]) => void;
  
  // 🎯 Bulk operation actions
  startBulkOperation: (operation: BulkAction, deviceIds: string[]) => void;
  updateOperationProgress: (progress: OperationProgress) => void;
  completeBulkOperation: (result: BulkOperationResult) => void;
  clearSelection: () => void;
  
  // 🎯 Computed values
  getSelectionCount: () => number;
  hasSelection: () => boolean;
  getSelectedDeviceIds: () => string[];
  canPerformOperation: (operation: BulkAction) => boolean;
}

// 🏪 Store implementation with professional IoT logic
export const useDeviceSelection = create<DeviceSelectionStore>()(
  devtools(
    (set, get) => ({
      // 🎯 Initial state
      selectedDevices: new Set<string>(),
      lastSelectedDevice: null,
      selectionMode: 'normal',
      currentBulkOperation: null,
      operationHistory: [],
      isOperationInProgress: false,

      // 🎯 Selection with range support (Shift+click)
      toggleDevice: (deviceId, withShift = false) => set(state => {
        const newSelected = new Set(state.selectedDevices);
        
        if (withShift && state.lastSelectedDevice) {
          // TODO: Implement range selection
          // For now, simple toggle
          if (newSelected.has(deviceId)) {
            newSelected.delete(deviceId);
          } else {
            newSelected.add(deviceId);
          }
        } else {
          // Toggle normal
          if (newSelected.has(deviceId)) {
            newSelected.delete(deviceId);
          } else {
            newSelected.add(deviceId);
          }
        }

        return {
          selectedDevices: newSelected,
          lastSelectedDevice: deviceId,
          selectionMode: withShift ? 'range' : 'normal',
        };
      }),

      selectAll: (deviceIds) => set({
        selectedDevices: new Set(deviceIds),
        selectionMode: 'all',
      }),

      selectNone: () => set({
        selectedDevices: new Set(),
        lastSelectedDevice: null,
        selectionMode: 'normal',
      }),

      // 🎯 Smart selection by IoT criteria
      selectByFilter: (predicate, devices) => set(state => {
        const filteredDeviceIds = devices
          .filter(predicate)
          .map(device => device.id);
        
        return {
          selectedDevices: new Set([...state.selectedDevices, ...filteredDeviceIds]),
        };
      }),

      // 🎯 Start bulk operation with tracking
      startBulkOperation: (operation, deviceIds) => set(state => ({
        currentBulkOperation: {
          operationType: operation,
          totalDevices: deviceIds.length,
          successfulDevices: [],
          failedDevices: [],
          startTime: Date.now(),
          progress: { completed: 0, total: deviceIds.length, percentage: 0 },
        },
        isOperationInProgress: true,
      })),

      // 🎯 Real-time progress update
      updateOperationProgress: (progress) => set(state => ({
        currentBulkOperation: state.currentBulkOperation ? {
          ...state.currentBulkOperation,
          progress,
        } : null,
      })),

      // 🎯 Operation finalization with history
      completeBulkOperation: (result) => set(state => ({
        currentBulkOperation: null,
        isOperationInProgress: false,
        operationHistory: [
          { ...result, endTime: Date.now() },
          ...state.operationHistory.slice(0, 9), // Keep the last 10
        ],
        // Clear selection only if operation succeeded
        selectedDevices: result.failedDevices.length === 0 
          ? new Set() 
          : new Set(result.failedDevices.map(f => f.deviceId)),
      })),

      clearSelection: () => set({
        selectedDevices: new Set(),
        lastSelectedDevice: null,
        selectionMode: 'normal',
      }),

      // 🎯 Computed values
      getSelectionCount: () => get().selectedDevices.size,
      hasSelection: () => get().selectedDevices.size > 0,
      getSelectedDeviceIds: () => Array.from(get().selectedDevices),
      
      // 🎯 Business validation for IoT operations
      canPerformOperation: (operation) => {
        const { selectedDevices, isOperationInProgress } = get();
        
        if (isOperationInProgress || selectedDevices.size === 0) {
          return false;
        }

        // Operation-specific business rules
        switch (operation) {
          case 'factory_reset':
            return selectedDevices.size <= 10; // Safety limit for reset
          case 'update_firmware':
            return selectedDevices.size <= 50; // Bandwidth limit
          default:
            return true;
        }
      },
    })
  )
);

// File: src/components/DeviceBulkActions.tsx
import React from 'react';
import { useMutation, useQueryClient } from '@tanstack/react-query';
import { Button } from '@/components/ui/button';
import { Progress } from '@/components/ui/progress';
import { Badge } from '@/components/ui/badge';
import { 
  DropdownMenu, 
  DropdownMenuContent, 
  DropdownMenuItem, 
  DropdownMenuTrigger 
} from '@/components/ui/dropdown-menu';
import { ChevronDown, X, AlertTriangle, CheckCircle } from 'lucide-react';
import { useDeviceSelection } from '@/stores/device/useDeviceSelection';
import { deviceQueries } from '@/lib/queries/deviceQueries';
import { api } from '@/lib/api';
import { toast } from '@/components/ui/use-toast';
import type { BulkAction, BulkOperationResult } from '@/types/iot';

// 📊 IoT bulk operations configuration
const BULK_OPERATIONS: Record<BulkAction, { 
  label: string; 
  icon: string; 
  variant: 'default' | 'destructive' | 'secondary';
  requiresConfirmation: boolean;
  confirmationMessage?: string;
}> = {
  restart: { 
    label: 'Restart Devices', 
    icon: '🔄', 
    variant: 'secondary', 
    requiresConfirmation: true,
    confirmationMessage: 'This will restart all selected devices. They will be offline for ~30 seconds.'
  },
  update_firmware: { 
    label: 'Update Firmware', 
    icon: '📦', 
    variant: 'default', 
    requiresConfirmation: true,
    confirmationMessage: 'Firmware update will take 5-10 minutes per device. Devices will be offline during update.'
  },
  assign_tags: { 
    label: 'Assign Tags', 
    icon: '🏷️', 
    variant: 'default', 
    requiresConfirmation: false
  },
  schedule_maintenance: { 
    label: 'Schedule Maintenance', 
    icon: '🔧', 
    variant: 'secondary', 
    requiresConfirmation: false
  },
  deactivate: { 
    label: 'Deactivate Devices', 
    icon: '⏸️', 
    variant: 'destructive', 
    requiresConfirmation: true,
    confirmationMessage: 'Deactivated devices will stop sending data and cannot be controlled remotely.'
  },
  factory_reset: { 
    label: 'Factory Reset', 
    icon: '⚠️', 
    variant: 'destructive', 
    requiresConfirmation: true,
    confirmationMessage: 'This will permanently reset devices to factory settings. All configuration will be lost!'
  },
};

// 🎛️ Main bulk actions component
export const DeviceBulkActions = () => {
  const queryClient = useQueryClient();
  
  // 🏪 Store state
  const { 
    selectedDevices,
    currentBulkOperation,
    isOperationInProgress,
    getSelectionCount,
    canPerformOperation,
    startBulkOperation,
    updateOperationProgress,
    completeBulkOperation,
    clearSelection
  } = useDeviceSelection();

  // 🔄 Mutation for bulk operations with progress tracking
  const bulkOperationMutation = useMutation({
    mutationFn: async ({ operation, deviceIds }: { operation: BulkAction; deviceIds: string[] }) => {
      // Start the operation
      startBulkOperation(operation, deviceIds);
      
      // Simulate progress tracking (in reality, websocket or polling)
      const progressUpdates = [
        { completed: Math.floor(deviceIds.length * 0.1), total: deviceIds.length },
        { completed: Math.floor(deviceIds.length * 0.3), total: deviceIds.length },
        { completed: Math.floor(deviceIds.length * 0.6), total: deviceIds.length },
        { completed: Math.floor(deviceIds.length * 0.9), total: deviceIds.length },
      ];

      for (const progress of progressUpdates) {
        await new Promise(resolve => setTimeout(resolve, 1000)); // Simulate work
        updateOperationProgress({
          ...progress,
          percentage: Math.round((progress.completed / progress.total) * 100),
        });
      }

      // Actual API call
      const result = await api.devices.bulkOperation(deviceIds, operation);
      
      return {
        operationType: operation,
        totalDevices: deviceIds.length,
        successfulDevices: result.successful,
        failedDevices: result.failed,
        startTime: Date.now() - 4000, // Adjust according to actual duration
        progress: { completed: deviceIds.length, total: deviceIds.length, percentage: 100 },
      } as BulkOperationResult;
    },
    
    onSuccess: (result) => {
      // Finalize the operation
      completeBulkOperation(result);
      
      // Invalidate device queries
      queryClient.invalidateQueries({ queryKey: deviceQueries.all() });
      
      // Success/error toast
      if (result.failedDevices.length === 0) {
        toast({ 
          title: "✅ Bulk operation completed", 
          description: `Successfully ${result.operationType} ${result.totalDevices} devices`
        });
      } else {
        toast({
          title: "⚠️ Bulk operation partially failed",
          description: `${result.successfulDevices.length}/${result.totalDevices} devices succeeded`,
          variant: "destructive"
        });
      }
    },
    
    onError: (error: any) => {
      completeBulkOperation({
        operationType: 'restart', // fallback
        totalDevices: getSelectionCount(),
        successfulDevices: [],
        failedDevices: Array.from(selectedDevices).map(id => ({ deviceId: id, error: error.message })),
        startTime: Date.now(),
        progress: { completed: 0, total: getSelectionCount(), percentage: 0 },
      });
      
      toast({ 
        title: "❌ Bulk operation failed", 
        description: error.message,
        variant: "destructive"
      });
    }
  });

  // 🎯 Handler to trigger operations
  const handleBulkAction = async (operation: BulkAction) => {
    const config = BULK_OPERATIONS[operation];
    const deviceIds = Array.from(selectedDevices);
    
    // Validation
    if (!canPerformOperation(operation)) {
      toast({
        title: "Operation not allowed",
        description: "Check selection or wait for current operation to complete",
        variant: "destructive"
      });
      return;
    }
    
    // Confirmation if necessary
    if (config.requiresConfirmation) {
      const confirmed = window.confirm(
        `${config.confirmationMessage}\n\nThis will affect ${deviceIds.length} devices. Continue?`
      );
      if (!confirmed) return;
    }
    
    // Start the operation
    bulkOperationMutation.mutate({ operation, deviceIds });
  };

  // 🚫 Don't display if no selection and no operation in progress
  if (getSelectionCount() === 0 && !currentBulkOperation) {
    return null;
  }

  return (
    <div className="sticky bottom-4 mx-4 p-4 bg-white border rounded-lg shadow-lg z-10">
      {/* 📊 Progress display during operation */}
      {currentBulkOperation && (
        <div className="mb-4 space-y-2">
          <div className="flex items-center justify-between">
            <span className="text-sm font-medium">
              {BULK_OPERATIONS[currentBulkOperation.operationType]?.label} in progress...
            </span>
            <span className="text-xs text-gray-500">
              {currentBulkOperation.progress.completed} / {currentBulkOperation.progress.total}
            </span>
          </div>
          <Progress value={currentBulkOperation.progress.percentage} className="w-full" />
        </div>
      )}

      {/* 🎛️ Controls */}
      <div className="flex items-center justify-between">
        <div className="flex items-center gap-3">
          <Badge variant="secondary" className="text-sm">
            {getSelectionCount()} devices selected
          </Badge>
          
          {currentBulkOperation && (
            <Badge variant="default" className="text-sm">
              <div className="animate-spin w-3 h-3 border border-white border-t-transparent rounded-full mr-2"></div>
              Processing...
            </Badge>
          )}
        </div>

        <div className="flex items-center gap-2">
          {/* 🗑️ Clear selection */}
          <Button
            variant="ghost"
            size="sm"
            onClick={clearSelection}
            disabled={isOperationInProgress}
          >
            <X className="w-4 h-4" />
            Clear
          </Button>

          {/* 📋 Bulk actions dropdown */}
          <DropdownMenu>
            <DropdownMenuTrigger asChild>
              <Button
                variant="default"
                size="sm"
                disabled={isOperationInProgress || getSelectionCount() === 0}
              >
                Bulk Actions
                <ChevronDown className="w-4 h-4 ml-1" />
              </Button>
            </DropdownMenuTrigger>
            <DropdownMenuContent align="end" className="w-48">
              {Object.entries(BULK_OPERATIONS).map(([action, config]) => (
                <DropdownMenuItem
                  key={action}
                  onClick={() => handleBulkAction(action as BulkAction)}
                  disabled={!canPerformOperation(action as BulkAction)}
                  className={config.variant === 'destructive' ? 'text-red-600' : ''}
                >
                  <span className="mr-2">{config.icon}</span>
                  {config.label}
                  {config.requiresConfirmation && (
                    <AlertTriangle className="w-3 h-3 ml-auto opacity-50" />
                  )}
                </DropdownMenuItem>
              ))}
            </DropdownMenuContent>
          </DropdownMenu>
        </div>
      </div>
    </div>
  );
};

⚖️ Context API vs Zustand Comparison

Use Context When:

// ✅ Good: Theme/UI configuration scoped to app tree
const ThemeContext = createContext<ThemeContextType | null>(null);

const ThemeProvider = ({ children }: { children: ReactNode }) => {
  const [theme, setTheme] = useState<Theme>('light');
  const [sidebarCollapsed, setSidebarCollapsed] = useState(false);
  
  return (
    <ThemeContext.Provider value={{ 
      theme, setTheme, 
      sidebarCollapsed, setSidebarCollapsed 
    }}>
      {children}
    </ThemeContext.Provider>
  );
};

// Usage: Simple, tree-scoped, no complex logic
const Header = () => {
  const { theme, setTheme } = useContext(ThemeContext);
  return (
    <Button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
      Toggle Theme
    </Button>
  );
};

Use Zustand When:

// File: src/stores/ui/useNotificationStore.ts
// ✅ Good: Complex global state with business logic
const useNotificationStore = create<NotificationStore>((set, get) => ({
  notifications: [],
  settings: { sound: true, desktop: false, email: true },
  
  addNotification: (notification) => set(state => ({
    notifications: [
      { ...notification, id: generateId(), timestamp: Date.now() },
      ...state.notifications.slice(0, 49) // Keep only last 50
    ]
  })),
  
  markAsRead: (id) => set(state => ({
    notifications: state.notifications.map(n => 
      n.id === id ? { ...n, read: true } : n
    )
  })),
  
  clearAll: () => set({ notifications: [] }),
  
  updateSettings: (newSettings) => set(state => ({
    settings: { ...state.settings, ...newSettings }
  })),
  
  // Complex derived state
  get unreadCount() {
    return get().notifications.filter(n => !n.read).length;
  },
}));

// Usage: Global access, complex logic, performance optimized
const NotificationBell = () => {
  // ✅ Only subscribes to unreadCount, not entire store
  const unreadCount = useNotificationStore(state => state.unreadCount);
  
  return (
    <Button variant="ghost" className="relative">
      <Bell className="h-5 w-5" />
      {unreadCount > 0 && (
        <Badge className="absolute -top-1 -right-1">
          {unreadCount}
        </Badge>
      )}
    </Button>
  );
};

📱 Priority IoT Use Cases

1. Real-time Device Status Updates

// File: src/stores/device/useDeviceStatusStore.ts
// Store: Device status with Socket.IO integration
const useDeviceStatusStore = create<DeviceStatusStore>((set, get) => ({
  deviceStatuses: new Map<string, DeviceStatus>(),
  lastUpdated: null,
  
  updateDeviceStatus: (deviceId, status) => set(state => {
    const newStatuses = new Map(state.deviceStatuses);
    newStatuses.set(deviceId, status);
    return {
      deviceStatuses: newStatuses,
      lastUpdated: Date.now(),
    };
  }),
  
  bulkUpdateStatuses: (updates) => set(state => {
    const newStatuses = new Map(state.deviceStatuses);
    updates.forEach(({ deviceId, status }) => {
      newStatuses.set(deviceId, status);
    });
    return {
      deviceStatuses: newStatuses,
      lastUpdated: Date.now(),
    };
  }),
}));

// Socket.IO integration
const useDeviceStatusSocket = () => {
  const { updateDeviceStatus, bulkUpdateStatuses } = useDeviceStatusStore();
  
  useEffect(() => {
    const socket = io('/devices');
    
    // Single device status update
    socket.on('device:status', ({ deviceId, status }) => {
      updateDeviceStatus(deviceId, status);
    });
    
    // Bulk status updates (performance optimization)
    socket.on('devices:bulk-status', (updates) => {
      bulkUpdateStatuses(updates);
    });
    
    return () => socket.disconnect();
  }, [updateDeviceStatus, bulkUpdateStatuses]);
};

// Component: Real-time device status indicator
const DeviceStatusIndicator = ({ deviceId }: { deviceId: string }) => {
  const deviceStatus = useDeviceStatusStore(state => 
    state.deviceStatuses.get(deviceId)
  );
  
  const getStatusColor = (status?: DeviceStatus) => {
    switch (status) {
      case 'online': return 'text-green-500';
      case 'offline': return 'text-red-500';
      case 'maintenance': return 'text-yellow-500';
      default: return 'text-gray-500';
    }
  };
  
  return (
    <div className={`flex items-center gap-2 ${getStatusColor(deviceStatus)}`}>
      <div className="w-2 h-2 rounded-full bg-current" />
      <span className="capitalize">{deviceStatus || 'unknown'}</span>
    </div>
  );
};

2. User Preferences with Persistence

// Store: User preferences with localStorage persistence
interface UserPreferencesStore {
  preferences: {
    theme: 'light' | 'dark' | 'system';
    language: string;
    dashboardLayout: 'grid' | 'list';
    notificationSettings: {
      email: boolean;
      push: boolean;
      sound: boolean;
    };
  };
  
  updateTheme: (theme: Theme) => void;
  updateLanguage: (language: string) => void;
  updateDashboardLayout: (layout: DashboardLayout) => void;
  updateNotificationSettings: (settings: Partial<NotificationSettings>) => void;
}

// File: src/stores/user/useUserPreferencesStore.ts
const useUserPreferencesStore = create<UserPreferencesStore>()(
  persist(
    (set, get) => ({
      preferences: {
        theme: 'system',
        language: 'en',
        dashboardLayout: 'grid',
        notificationSettings: {
          email: true,
          push: true,
          sound: false,
        },
      },
      
      updateTheme: (theme) => set(state => ({
        preferences: { ...state.preferences, theme }
      })),
      
      updateLanguage: (language) => set(state => ({
        preferences: { ...state.preferences, language }
      })),
      
      updateDashboardLayout: (dashboardLayout) => set(state => ({
        preferences: { ...state.preferences, dashboardLayout }
      })),
      
      updateNotificationSettings: (settings) => set(state => ({
        preferences: {
          ...state.preferences,
          notificationSettings: {
            ...state.preferences.notificationSettings,
            ...settings,
          }
        }
      })),
    }),
    {
      name: 'user-preferences', // localStorage key
      partialize: (state) => ({ preferences: state.preferences }), // Only persist preferences
    }
  )
);

// Usage in settings component
const UserSettingsForm = () => {
  const { preferences, updateTheme, updateNotificationSettings } = useUserPreferencesStore();
  
  return (
    <div className="space-y-6">
      <div>
        <Label>Theme</Label>
        <Select 
          value={preferences.theme}
          onValueChange={updateTheme}
        >
          <SelectItem value="light">Light</SelectItem>
          <SelectItem value="dark">Dark</SelectItem>
          <SelectItem value="system">System</SelectItem>
        </Select>
      </div>
      
      <div>
        <Label>Notifications</Label>
        <div className="space-y-2">
          <Checkbox
            checked={preferences.notificationSettings.email}
            onCheckedChange={(email) => updateNotificationSettings({ email: !!email })}
          >
            Email notifications
          </Checkbox>
          <Checkbox
            checked={preferences.notificationSettings.push}
            onCheckedChange={(push) => updateNotificationSettings({ push: !!push })}
          >
            Push notifications
          </Checkbox>
        </div>
      </div>
    </div>
  );
};

⚡ Performance Optimization Strategies

Selective Subscriptions

// ❌ Bad: Subscribes to entire store
const BadComponent = () => {
  const store = useDeviceStore(); // Re-renders on ANY store change
  
  return <div>{store.devices.length} devices</div>;
};

// ✅ Good: Selective subscription
const GoodComponent = () => {
  const deviceCount = useDeviceStore(state => state.devices.length); // Only re-renders when count changes
  
  return <div>{deviceCount} devices</div>;
};

// ✅ Better: Custom selector for complex logic
// File: src/hooks/useDeviceCount.ts
const useDeviceCount = () => useDeviceStore(
  useCallback(
    state => ({
      total: state.devices.length,
      online: state.onlineDevices.length,
      offline: state.offlineDevices.length,
    }),
    []
  ),
  shallow // Shallow comparison for object selectors
);

Migration from useState/Context

// Before: useState with prop drilling
const ParentComponent = () => {
  const [selectedDevices, setSelectedDevices] = useState<string[]>([]);
  
  return (
    <div>
      <DeviceFilters onSelectionChange={setSelectedDevices} />
      <DeviceList selectedDevices={selectedDevices} />
      <BulkActions selectedDevices={selectedDevices} />
    </div>
  );
};

// File: src/stores/device/useDeviceSelection.ts  
// After: Zustand store
const useDeviceSelection = create<DeviceSelectionStore>((set) => ({
  selectedDevices: [],
  toggleDevice: (deviceId) => set(state => ({
    selectedDevices: state.selectedDevices.includes(deviceId)
      ? state.selectedDevices.filter(id => id !== deviceId)
      : [...state.selectedDevices, deviceId]
  })),
  clearSelection: () => set({ selectedDevices: [] }),
}));

// Clean, no prop drilling needed
const ParentComponent = () => (
  <div>
    <DeviceFilters />
    <DeviceList />
    <BulkActions />
  </div>
);

🚀 Getting Started with Zustand

Ready to implement Zustand in your project? Follow this step-by-step guide to get up and running.

1. Installation & Dependencies

# Install Zustand and persistence middleware
npm install zustand
npm install @types/node --save-dev  # For TypeScript support

2. Create Your First Store

Create a simple notification store to get started:

// File: src/stores/ui/useNotificationStore.ts
import { create } from 'zustand';
import { persist } from 'zustand/middleware';

interface Notification {
  id: string;
  title: string;
  message: string;
  type: 'success' | 'error' | 'warning' | 'info';
  timestamp: number;
}

interface NotificationStore {
  notifications: Notification[];
  addNotification: (notification: Omit<Notification, 'id' | 'timestamp'>) => void;
  removeNotification: (id: string) => void;
  clearAll: () => void;
}

export const useNotificationStore = create<NotificationStore>((set) => ({
  notifications: [],
  
  addNotification: (notification) => set((state) => ({
    notifications: [
      {
        ...notification,
        id: crypto.randomUUID(),
        timestamp: Date.now(),
      },
      ...state.notifications.slice(0, 4) // Keep only last 5 notifications
    ]
  })),
  
  removeNotification: (id) => set((state) => ({
    notifications: state.notifications.filter(n => n.id !== id)
  })),
  
  clearAll: () => set({ notifications: [] }),
}));

3. Create Store Index File

// File: src/stores/index.ts
export { useNotificationStore } from './ui/useNotificationStore';

// Add more stores as you create them:
// export { useDeviceFilters } from './device/useDeviceFilters';
// export { useUserPreferences } from './user/useUserPreferences';

4. Use the Store in Components

// File: src/components/ui/NotificationToast.tsx
import { useNotificationStore } from '@/stores';

export const NotificationList = () => {
  const { notifications, removeNotification } = useNotificationStore();
  
  return (
    <div className="fixed top-4 right-4 space-y-2 z-50">
      {notifications.map((notification) => (
        <div
          key={notification.id}
          className={`p-4 rounded-lg shadow-lg transition-all duration-300 ${
            notification.type === 'success' ? 'bg-green-500 text-white' :
            notification.type === 'error' ? 'bg-red-500 text-white' :
            notification.type === 'warning' ? 'bg-yellow-500 text-black' :
            'bg-blue-500 text-white'
          }`}
        >
          <div className="flex justify-between items-start">
            <div>
              <h4 className="font-semibold">{notification.title}</h4>
              <p className="text-sm">{notification.message}</p>
            </div>
            <button
              onClick={() => removeNotification(notification.id)}
              className="ml-4 text-lg opacity-70 hover:opacity-100"
            >
              ×
            </button>
          </div>
        </div>
      ))}
    </div>
  );
};

// Usage in other components:
export const SomeComponent = () => {
  const { addNotification } = useNotificationStore();
  
  const handleSuccess = () => {
    addNotification({
      title: 'Success!',
      message: 'Operation completed successfully',
      type: 'success'
    });
  };
  
  return (
    <button onClick={handleSuccess}>
      Test Notification
    </button>
  );
};

5. Add to Your App Layout

// File: src/app/layout.tsx or your main layout component
import { NotificationList } from '@/components/ui/NotificationToast';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        {children}
        {/* Add notification system globally */}
        <NotificationList />
      </body>
    </html>
  );
}

6. Next Steps: Expand Your Architecture

Once you have the basic setup working, expand to the full architecture:

Create domain-specific stores:

# Create directory structure
mkdir -p src/stores/device
mkdir -p src/stores/user
mkdir -p src/stores/ui

# Create store files based on the examples in this guide
touch src/stores/device/useDeviceFilters.ts
touch src/stores/device/useDeviceSelection.ts  
touch src/stores/user/useUserPreferences.ts
# ... etc

Add persistence for user preferences:

// Example: Persistent user preferences store
import { create } from 'zustand';
import { persist } from 'zustand/middleware';

export const useUserPreferences = create<UserPreferencesStore>()(
  persist(
    (set) => ({
      theme: 'system',
      language: 'en',
      // ... your state and actions
    }),
    {
      name: 'user-preferences',
      // Only persist specific fields if needed
      partialize: (state) => ({ 
        theme: state.theme, 
        language: state.language 
      }),
    }
  )
);

Integration with TanStack Query:

// Example: Reactive filtering with TanStack Query
export const DeviceList = () => {
  const { filters } = useDeviceFilters(); // Zustand store
  
  // Automatically refetches when filters change
  const { data: devices } = useQuery({
    queryKey: ['devices', filters],
    queryFn: () => api.devices.list(filters),
  });
  
  return <DeviceGrid devices={devices} />;
};

7. Testing Your Implementation

// Test your store
import { renderHook, act } from '@testing-library/react';
import { useNotificationStore } from '@/stores/ui/useNotificationStore';

test('should add and remove notifications', () => {
  const { result } = renderHook(() => useNotificationStore());
  
  act(() => {
    result.current.addNotification({
      title: 'Test',
      message: 'Test message',
      type: 'success'
    });
  });
  
  expect(result.current.notifications).toHaveLength(1);
  expect(result.current.notifications[0].title).toBe('Test');
  
  act(() => {
    result.current.clearAll();
  });
  
  expect(result.current.notifications).toHaveLength(0);
});

🎯 You're Ready!

Your Zustand setup is now complete. Continue building stores using the patterns and examples provided in this guide. Remember to follow the domain-based organization and import patterns for maintainable code.

---

🎨 UI Component Guidelines

Form Handling Pattern

Our forms use React Hook Form + Zod validation for type-safe, performant form handling with comprehensive error management.

🏗️ Complete Form Architecture

📋 Use Cases & Architectural Decisions:

When to use this complete approach:

• ✅ User/organization creation/editing forms or complex business entities
• ✅ Forms with 5+ fields or complex business validation
• ✅ Cross-field validation requirements (password + confirmation, field dependencies)
• ✅ B2B applications where data robustness is critical

Validation mode selection:

// 🎯 Use cases for each validation mode
const form = useForm({
  // mode: "onChange" -> Use when:
  // - Critical forms (payment, sensitive data)
  // - Immediate feedback required
  // - Simple validation without API calls
  
  // mode: "onTouched" -> Use when:
  // - Standard forms (recommended default)
  // - Optimal UX/performance balance
  // - Validation after user interaction
  
  // mode: "onBlur" -> Use when:
  // - Expensive validation (API calls)
  // - Forms with many fields
  // - Performance critical
  
  mode: "onTouched", // ⭐ Recommended default choice
});

Validation architecture by complexity:

// 🟢 SIMPLE - Basic forms (contact, feedback)
const simpleSchema = z.object({
  email: z.string().email(),
  message: z.string().min(10),
});

// 🟡 STANDARD - Business forms (this section)
const standardSchema = z.object({
  // Business validation + cross-field
  email: z.string().email().max(100),
  password: z.string().min(8).regex(/complexity/),
}).refine((data) => /* cross-field logic */);

// 🔴 COMPLEX - Critical forms (billing, configuration)
const complexSchema = z.object({
  // Advanced business validation + async + conditional
}).superRefine(async (data, ctx) => {
  // Async validation + business rules
});

Complete example with usage context:

// 1. Schema Definition with Advanced Validation
const userFormSchema = z
  .object({
    // Basic validations
    email: z
      .string()
      .min(1, "Email is required")
      .email("Invalid email address")
      .max(100, "Email too long"),
    
    name: z
      .string()
      .min(1, "Name is required")
      .max(50, "Name too long")
      .regex(/^[a-zA-Z\s]+$/, "Only letters and spaces allowed"),
    
    // Advanced validations
    password: z
      .string()
      .min(8, "Password must be at least 8 characters")
      .regex(/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)/, "Password must contain uppercase, lowercase, and number"),
    
    passwordConfirm: z.string(),
    
    // Optional fields with conditional validation
    organizationId: z.string().optional(),
    
    // Array validations
    tags: z
      .array(z.object({ id: z.string(), name: z.string() }))
      .min(1, "At least one tag is required")
      .optional(),
    
    // Enum validations
    role: z.enum(["ADMIN", "USER", "VIEWER"], {
      errorMap: () => ({ message: "Please select a valid role" }),
    }),
    
    language: z.string().min(1, "Language is required"),
    
    // Date validations
    birthDate: z
      .date()
      .max(new Date(), "Birth date cannot be in the future")
      .optional(),
  })
  // Cross-field validation (refine)
  .refine((data) => data.password === data.passwordConfirm, {
    message: "Passwords do not match",
    path: ["passwordConfirm"], // Error appears on passwordConfirm field
  })
  // Conditional validation
  .refine((data) => {
    if (data.role === "ADMIN" && !data.organizationId) {
      return false;
    }
    return true;
  }, {
    message: "Organization is required for admin users",
    path: ["organizationId"],
  });

type UserFormData = z.infer<typeof userFormSchema>;

// 2. Form Component with Complete Error Handling
export function UserForm({ 
  initialData,
  onSubmit: onSubmitProp,
  isEditing = false 
}: {
  initialData?: Partial<UserFormData>;
  onSubmit: (data: UserFormData) => Promise<void>;
  isEditing?: boolean;
}) {
  const [isLoading, setIsLoading] = React.useState(false);
  
  const form = useForm<UserFormData>({
    resolver: zodResolver(userFormSchema),
    defaultValues: {
      email: initialData?.email ?? "",
      name: initialData?.name ?? "",
      password: "",
      passwordConfirm: "",
      organizationId: initialData?.organizationId,
      tags: initialData?.tags ?? [],
      role: initialData?.role ?? "USER",
      language: initialData?.language ?? "en",
      birthDate: initialData?.birthDate,
    },
    // Form validation modes
    mode: "onTouched", // Validate on blur/touch
    reValidateMode: "onChange", // Re-validate on change after first validation
  });

  // Watch specific fields for conditional logic
  const selectedRole = form.watch("role");
  const isAdmin = selectedRole === "ADMIN";

  const onSubmit = async (data: UserFormData) => {
    setIsLoading(true);
    try {
      await onSubmitProp(data);
      
      // Success feedback
      toast({ 
        title: "Success", 
        description: isEditing ? "User updated successfully" : "User created successfully"
      });
      
      // Reset form if creating new user
      if (!isEditing) {
        form.reset();
      }
    } catch (error) {
      // Handle different error types
      if (error instanceof z.ZodError) {
        // Handle validation errors from server
        error.errors.forEach((err) => {
          form.setError(err.path[0] as keyof UserFormData, {
            type: "server",
            message: err.message,
          });
        });
      } else if (error?.response?.status === 409) {
        // Handle conflict errors (e.g., email already exists)
        form.setError("email", {
          type: "server",
          message: "This email is already registered",
        });
      } else {
        // Generic error handling
        toast({
          title: "Error",
          description: error?.message || "An unexpected error occurred",
          variant: "destructive",
        });
      }
    } finally {
      setIsLoading(false);
    }
  };

  return (
    <Form {...form}>
      <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-6">
        
        {/* Email Field with Custom Validation */}
        <FormField
          control={form.control}
          name="email"
          render={({ field }) => (
            <FormItem>
              <FormLabel>Email Address *</FormLabel>
              <FormControl>
                <Input
                  type="email"
                  placeholder="user@example.com"
                  disabled={isLoading}
                  {...field}
                />
              </FormControl>
              <FormDescription>
                We'll use this email for important notifications
              </FormDescription>
              <FormMessage />
            </FormItem>
          )}
        />

        {/* Name Field */}
        <FormField
          control={form.control}
          name="name"
          render={({ field }) => (
            <FormItem>
              <FormLabel>Full Name *</FormLabel>
              <FormControl>
                <Input
                  placeholder="John Doe"
                  disabled={isLoading}
                  {...field}
                />
              </FormControl>
              <FormMessage />
            </FormItem>
          )}
        />

        {/* Password Fields */}
        <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
          <FormField
            control={form.control}
            name="password"
            render={({ field }) => (
              <FormItem>
                <FormLabel>Password *</FormLabel>
                <FormControl>
                  <Input
                    type="password"
                    placeholder="Enter password"
                    disabled={isLoading}
                    {...field}
                  />
                </FormControl>
                <FormMessage />
              </FormItem>
            )}
          />

          <FormField
            control={form.control}
            name="passwordConfirm"
            render={({ field }) => (
              <FormItem>
                <FormLabel>Confirm Password *</FormLabel>
                <FormControl>
                  <Input
                    type="password"
                    placeholder="Confirm password"
                    disabled={isLoading}
                    {...field}
                  />
                </FormControl>
                <FormMessage />
              </FormItem>
            )}
          />
        </div>

        {/* Role Selection with Conditional Organization */}
        <FormField
          control={form.control}
          name="role"
          render={({ field }) => (
            <FormItem>
              <FormLabel>Role *</FormLabel>
              <Select onValueChange={field.onChange} defaultValue={field.value} disabled={isLoading}>
                <FormControl>
                  <SelectTrigger>
                    <SelectValue placeholder="Select a role" />
                  </SelectTrigger>
                </FormControl>
                <SelectContent>
                  <SelectItem value="USER">User</SelectItem>
                  <SelectItem value="ADMIN">Admin</SelectItem>
                  <SelectItem value="VIEWER">Viewer</SelectItem>
                </SelectContent>
              </Select>
              <FormMessage />
            </FormItem>
          )}
        />

        {/* Conditional Organization Field */}
        {isAdmin && (
          <FormField
            control={form.control}
            name="organizationId"
            render={({ field }) => (
              <FormItem>
                <FormLabel>Organization *</FormLabel>
                <OrganizationSelect
                  value={field.value}
                  onValueChange={field.onChange}
                  disabled={isLoading}
                />
                <FormDescription>
                  Admin users must be assigned to an organization
                </FormDescription>
                <FormMessage />
              </FormItem>
            )}
          />
        )}

        {/* Multi-Select Tags */}
        <FormField
          control={form.control}
          name="tags"
          render={({ field }) => (
            <FormItem>
              <FormLabel>Tags</FormLabel>
              <FormControl>
                <MultiSelect
                  options={availableTags}
                  selected={field.value || []}
                  onChange={field.onChange}
                  placeholder="Select tags..."
                  disabled={isLoading}
                />
              </FormControl>
              <FormDescription>
                Tags help organize and filter users
              </FormDescription>
              <FormMessage />
            </FormItem>
          )}
        />

        {/* Form Actions */}
        <div className="flex items-center justify-between pt-4">
          <Button
            type="button"
            variant="outline"
            onClick={() => form.reset()}
            disabled={isLoading}
          >
            Reset Form
          </Button>
          
          <div className="flex gap-2">
            <Button type="button" variant="ghost" disabled={isLoading}>
              Cancel
            </Button>
            <Button
              type="submit"
              disabled={isLoading || !form.formState.isValid}
              className="min-w-[100px]"
            >
              {isLoading && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
              {isEditing ? "Update User" : "Create User"}
            </Button>
          </div>
        </div>

        {/* Form State Debug (dev only) */}
        {process.env.NODE_ENV === "development" && (
          <div className="mt-4 p-4 bg-gray-100 rounded-md text-xs">
            <details>
              <summary>Form Debug Info</summary>
              <pre>{JSON.stringify({
                isValid: form.formState.isValid,
                isDirty: form.formState.isDirty,
                errors: form.formState.errors,
                touchedFields: form.formState.touchedFields,
              }, null, 2)}</pre>
            </details>
          </div>
        )}
      </form>
    </Form>
  );
}

🔄 Advanced Form Patterns

📋 Advanced patterns selection guide:

Pattern	Use Cases	Complexity	When to Use
Multi-Step	User onboarding, E-commerce checkout, System configuration	🟡 Medium	8+ fields, complex business logic, improve UX
Dynamic Fields	Resumes/Profiles, Multiple addresses, Dynamic configuration	🟡 Medium	Variable lists, repetitive data
Async Validation	Uniqueness checks, Server-side business validation	🔴 High	Critical data, server business rules
File Upload	Documents, Profile images, Data import	🟡 Medium	File handling, previews

---

🎯 Multi-Step Forms - Concrete Use Cases:

Use when:

• ✅ User onboarding: Registration → Profile → Preferences → Confirmation
• ✅ Checkout process: Cart → Shipping → Payment → Confirmation
• ✅ IoT configuration: Sensor selection → Parameters → Location → Testing
• ✅ Organization creation: Basic info → Users → Configuration → Validation

DO NOT use when:

• ❌ Less than 6 total fields
• ❌ No business logic between steps
• ❌ Simple form without dependencies

Multi-Step Forms with State Management:

// Multi-step form with progress tracking
const steps = [
  { id: 'basic', title: 'Basic Info', schema: basicInfoSchema },
  { id: 'security', title: 'Security', schema: securitySchema },
  { id: 'preferences', title: 'Preferences', schema: preferencesSchema },
] as const;

export function MultiStepUserForm() {
  const [currentStep, setCurrentStep] = React.useState(0);
  const [formData, setFormData] = React.useState<Partial<UserFormData>>({});

  const currentStepSchema = steps[currentStep].schema;
  
  const form = useForm({
    resolver: zodResolver(currentStepSchema),
    defaultValues: formData,
    mode: "onChange",
  });

  const nextStep = async (data: any) => {
    // Validate current step
    const isValid = await form.trigger();
    if (!isValid) return;

    // Save step data
    setFormData(prev => ({ ...prev, ...data }));
    
    // Move to next step or submit
    if (currentStep < steps.length - 1) {
      setCurrentStep(prev => prev + 1);
      form.reset(formData); // Load saved data for next step
    } else {
      // Final submission
      await submitCompleteForm({ ...formData, ...data });
    }
  };

  const prevStep = () => {
    if (currentStep > 0) {
      setCurrentStep(prev => prev - 1);
      form.reset(formData);
    }
  };

  return (
    <div className="max-w-2xl mx-auto">
      {/* Progress Indicator */}
      <div className="mb-8">
        <div className="flex items-center justify-between">
          {steps.map((step, index) => (
            <div
              key={step.id}
              className={`flex items-center ${
                index <= currentStep ? 'text-primary' : 'text-muted-foreground'
              }`}
            >
              <div
                className={`rounded-full h-8 w-8 flex items-center justify-center border-2 ${
                  index < currentStep
                    ? 'bg-primary text-primary-foreground border-primary'
                    : index === currentStep
                    ? 'border-primary text-primary'
                    : 'border-muted-foreground'
                }`}
              >
                {index < currentStep ? '✓' : index + 1}
              </div>
              <span className="ml-2 text-sm font-medium">{step.title}</span>
              {index < steps.length - 1 && (
                <div className="flex-1 h-px bg-border mx-4" />
              )}
            </div>
          ))}
        </div>
      </div>

      {/* Form Content */}
      <Form {...form}>
        <form onSubmit={form.handleSubmit(nextStep)} className="space-y-6">
          {/* Dynamic step content */}
          {currentStep === 0 && <BasicInfoFields />}
          {currentStep === 1 && <SecurityFields />}
          {currentStep === 2 && <PreferencesFields />}

          {/* Navigation */}
          <div className="flex justify-between">
            <Button
              type="button"
              variant="outline"
              onClick={prevStep}
              disabled={currentStep === 0}
            >
              Previous
            </Button>
            <Button type="submit">
              {currentStep === steps.length - 1 ? 'Complete' : 'Next'}
            </Button>
          </div>
        </form>
      </Form>
    </div>
  );
}

🎯 Dynamic Fields - IoT Platform Use Cases:

Concrete scenarios in our platform:

• ✅ Sensor management: Variable list of IoT sensors to configure
• ✅ Alert configuration: Multiple conditions with dynamic thresholds
• ✅ User profiles: Skills, certifications, multiple contacts
• ✅ Business flows: Multiple actions triggered by conditions
• ✅ Tag configuration: Dynamic tag assignment to devices

Decision criteria:

// Use Dynamic Fields when:
const shouldUseDynamicFields = {
  dataStructure: "array" | "repeated_objects", // ✅ List-based data
  userControl: "add_remove_items",              // ✅ User can add/remove items
  minItems: 0,                                  // ✅ Variable number of elements
  maxItems: "unlimited" | number,               // ✅ No fixed limit
  validation: "per_item + global",              // ✅ Per-item AND global validation
};

// Concrete example: IoT sensor configuration
const sensorConfigUseCase = {
  scenario: "Multi-sensor configuration for an IoT site",
  why: "Each site can have 1 to N sensors of different types",
  userStory: "As an admin, I want to configure multiple sensors with their specific parameters",
  complexity: "Each sensor has its own parameters (type, thresholds, frequency)",
};

Dynamic Form Fields (Arrays):

// Dynamic array fields with add/remove functionality
const skillsFormSchema = z.object({
  skills: z.array(
    z.object({
      name: z.string().min(1, "Skill name is required"),
      level: z.enum(["beginner", "intermediate", "advanced"]),
      yearsExperience: z.number().min(0).max(50),
    })
  ).min(1, "At least one skill is required"),
});

export function SkillsForm() {
  const form = useForm<z.infer<typeof skillsFormSchema>>({
    resolver: zodResolver(skillsFormSchema),
    defaultValues: {
      skills: [{ name: "", level: "beginner", yearsExperience: 0 }],
    },
  });

  const { fields, append, remove } = useFieldArray({
    control: form.control,
    name: "skills",
  });

  return (
    <Form {...form}>
      <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-6">
        <div className="space-y-4">
          <div className="flex items-center justify-between">
            <h3 className="text-lg font-medium">Skills</h3>
            <Button
              type="button"
              variant="outline"
              size="sm"
              onClick={() => append({ name: "", level: "beginner", yearsExperience: 0 })}
            >
              Add Skill
            </Button>
          </div>

          {fields.map((field, index) => (
            <Card key={field.id} className="p-4">
              <div className="grid grid-cols-1 md:grid-cols-3 gap-4">
                <FormField
                  control={form.control}
                  name={`skills.${index}.name`}
                  render={({ field }) => (
                    <FormItem>
                      <FormLabel>Skill Name *</FormLabel>
                      <FormControl>
                        <Input placeholder="React, Node.js, etc." {...field} />
                      </FormControl>
                      <FormMessage />
                    </FormItem>
                  )}
                />

                <FormField
                  control={form.control}
                  name={`skills.${index}.level`}
                  render={({ field }) => (
                    <FormItem>
                      <FormLabel>Level *</FormLabel>
                      <Select onValueChange={field.onChange} defaultValue={field.value}>
                        <FormControl>
                          <SelectTrigger>
                            <SelectValue />
                          </SelectTrigger>
                        </FormControl>
                        <SelectContent>
                          <SelectItem value="beginner">Beginner</SelectItem>
                          <SelectItem value="intermediate">Intermediate</SelectItem>
                          <SelectItem value="advanced">Advanced</SelectItem>
                        </SelectContent>
                      </Select>
                      <FormMessage />
                    </FormItem>
                  )}
                />

                <FormField
                  control={form.control}
                  name={`skills.${index}.yearsExperience`}
                  render={({ field }) => (
                    <FormItem>
                      <FormLabel>Years of Experience</FormLabel>
                      <FormControl>
                        <Input
                          type="number"
                          min="0"
                          max="50"
                          {...field}
                          onChange={(e) => field.onChange(Number(e.target.value))}
                        />
                      </FormControl>
                      <FormMessage />
                    </FormItem>
                  )}
                />
              </div>

              {fields.length > 1 && (
                <div className="flex justify-end mt-2">
                  <Button
                    type="button"
                    variant="ghost"
                    size="sm"
                    onClick={() => remove(index)}
                    className="text-destructive hover:text-destructive"
                  >
                    Remove
                  </Button>
                </div>
              )}
            </Card>
          ))}
        </div>

        <Button type="submit">Save Skills</Button>
      </form>
    </Form>
  );
}

🎯 Async Validation - When to Implement:

Critical use cases requiring server validation:

• ✅ Uniqueness verification: Email, organization name, device serial number
• ✅ Business validation: License keys, API keys, IoT configuration verification
• ✅ Security controls: Permission validation, authorized access
• ✅ Data integrity: Consistency verification with backend

Decision matrix:

// Implement async validation when:
const asyncValidationCriteria = {
  // ✅ REQUIRED - Critical data
  dataIntegrity: "high_importance",     // Unique emails, serial numbers
  businessLogic: "server_side_only",   // Complex server-side business rules
  securityCheck: "auth_required",      // Permission verifications
  
  // ✅ PERFORMANCE - Expensive validation data
  validationCost: "expensive_check",   // DB call, external API
  debounceNeeded: true,                // Avoid API call spam
  
  // ❌ DO NOT use for
  simpleValidation: false,             // Regex, length, format
  offlineSupport: false,               // App must work offline
};

Concrete IoT Platform examples:

// 🎯 Device Serial Number - Uniqueness verification
const deviceSerialValidation = {
  useCase: "New IoT device registration",
  why: "Each device must have a unique serial within the organization",
  apiCall: "GET /api/devices/check-serial/{serial}",
  debounce: "500ms after input",
  feedback: "Real-time indicator (✓ available / ✗ already used)",
};

// 🎯 Organization Name - Business validation
const orgNameValidation = {
  useCase: "Organization creation",
  why: "Name must be unique + respect business naming rules",
  apiCall: "POST /api/organizations/validate-name",
  businessRules: ["No forbidden words", "Specific format", "Uniqueness"],
};

Async Validation with Server Checks:

// Email availability check with debouncing
const userFormWithAsyncValidation = z.object({
  email: z.string().email("Invalid email format"),
  // ... other fields
});

export function FormWithAsyncValidation() {
  const [emailCheckStatus, setEmailCheckStatus] = React.useState<'idle' | 'checking' | 'available' | 'taken'>('idle');

  const form = useForm<z.infer<typeof userFormWithAsyncValidation>>({
    resolver: zodResolver(userFormWithAsyncValidation),
    mode: "onChange",
  });

  // Debounced email availability check
  const debouncedEmailCheck = React.useCallback(
    debounce(async (email: string) => {
      if (!email || !z.string().email().safeParse(email).success) {
        setEmailCheckStatus('idle');
        return;
      }

      setEmailCheckStatus('checking');
      try {
        const response = await api.checkEmailAvailability(email);
        if (response.available) {
          setEmailCheckStatus('available');
        } else {
          setEmailCheckStatus('taken');
          form.setError('email', {
            type: 'server',
            message: 'This email is already registered',
          });
        }
      } catch (error) {
        setEmailCheckStatus('idle');
      }
    }, 500),
    [form]
  );

  // Watch email field for async validation
  const watchedEmail = form.watch('email');
  React.useEffect(() => {
    if (watchedEmail) {
      debouncedEmailCheck(watchedEmail);
    }
  }, [watchedEmail, debouncedEmailCheck]);

  return (
    <Form {...form}>
      <form onSubmit={form.handleSubmit(onSubmit)}>
        <FormField
          control={form.control}
          name="email"
          render={({ field }) => (
            <FormItem>
              <FormLabel>Email Address *</FormLabel>
              <FormControl>
                <div className="relative">
                  <Input
                    type="email"
                    placeholder="user@example.com"
                    {...field}
                  />
                  {/* Async validation indicator */}
                  <div className="absolute right-3 top-1/2 transform -translate-y-1/2">
                    {emailCheckStatus === 'checking' && (
                      <Loader2 className="h-4 w-4 animate-spin text-muted-foreground" />
                    )}
                    {emailCheckStatus === 'available' && (
                      <Check className="h-4 w-4 text-green-500" />
                    )}
                    {emailCheckStatus === 'taken' && (
                      <X className="h-4 w-4 text-red-500" />
                    )}
                  </div>
                </div>
              </FormControl>
              <FormDescription>
                We'll check if this email is available in real-time
              </FormDescription>
              <FormMessage />
            </FormItem>
          )}
        />
        {/* Rest of form fields */}
      </form>
    </Form>
  );
}

🎯 File Upload - IoT Platform Use Cases:

File upload scenarios:

• ✅ Profile images: User avatars, organization logos
• ✅ Technical documents: Device manuals, certificates, technical specs
• ✅ Bulk configuration: CSV device import, sensor configuration
• ✅ Firmware updates: Firmware upload for IoT devices
• ✅ Geolocation: Map uploads, site plans, geographical zones

Selection criteria by file type:

// 🎯 Decision matrix by use case
const fileUploadUseCases = {
  // 📷 IMAGES - User interface
  profileImages: {
    when: "User avatar, organization logo",
    formats: ["JPEG", "PNG", "WebP"],
    maxSize: "5MB",
    features: ["Preview", "Crop", "Compression"],
    validation: "Client + Server",
  },
  
  // 📄 DOCUMENTS - Technical documentation
  technicalDocs: {
    when: "Manuals, certificates, technical specs",
    formats: ["PDF", "DOC", "TXT"],
    maxSize: "10MB", 
    features: ["Preview", "Download", "Versioning"],
    security: "Virus scan, MIME type check",
  },
  
  // 📊 DATA FILES - Bulk import
  dataImport: {
    when: "CSV device import, bulk configuration",
    formats: ["CSV", "JSON", "XML"],
    maxSize: "50MB",
    features: ["Validation", "Preview", "Error reporting"],
    processing: "Background job, progress tracking",
  },
  
  // ⚙️ FIRMWARE - IoT updates
  firmwareUpdate: {
    when: "Over-the-air IoT device updates",
    formats: ["BIN", "HEX", "Custom"],
    maxSize: "100MB",
    features: ["Checksum", "Signature verification"],
    security: "Cryptographic validation",
  },
};

File Upload Integration:

// File upload with validation and preview
const fileUploadSchema = z.object({
  profileImage: z
    .instanceof(File)
    .refine((file) => file.size <= 5000000, "File size must be less than 5MB")
    .refine(
      (file) => ["image/jpeg", "image/png", "image/webp"].includes(file.type),
      "Only JPEG, PNG, and WebP files are allowed"
    )
    .optional(),
  documents: z
    .array(z.instanceof(File))
    .max(5, "Maximum 5 files allowed")
    .optional(),
});

export function FileUploadForm() {
  const [previewUrl, setPreviewUrl] = React.useState<string>("");

  const form = useForm<z.infer<typeof fileUploadSchema>>({
    resolver: zodResolver(fileUploadSchema),
  });

  const handleImageChange = (file: File | undefined) => {
    if (file) {
      const url = URL.createObjectURL(file);
      setPreviewUrl(url);
      form.setValue('profileImage', file);
    } else {
      setPreviewUrl("");
      form.setValue('profileImage', undefined);
    }
  };

  React.useEffect(() => {
    return () => {
      if (previewUrl) {
        URL.revokeObjectURL(previewUrl);
      }
    };
  }, [previewUrl]);

  return (
    <Form {...form}>
      <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-6">
        <FormField
          control={form.control}
          name="profileImage"
          render={({ field }) => (
            <FormItem>
              <FormLabel>Profile Image</FormLabel>
              <FormControl>
                <div className="space-y-4">
                  <Input
                    type="file"
                    accept="image/jpeg,image/png,image/webp"
                    onChange={(e) => {
                      const file = e.target.files?.[0];
                      handleImageChange(file);
                    }}
                  />
                  {previewUrl && (
                    <div className="relative w-32 h-32">
                      <img
                        src={previewUrl}
                        alt="Profile preview"
                        className="w-full h-full object-cover rounded-lg border"
                      />
                      <Button
                        type="button"
                        variant="destructive"
                        size="sm"
                        className="absolute -top-2 -right-2"
                        onClick={() => handleImageChange(undefined)}
                      >
                        ×
                      </Button>
                    </div>
                  )}
                </div>
              </FormControl>
              <FormDescription>
                Upload a profile image (JPEG, PNG, or WebP, max 5MB)
              </FormDescription>
              <FormMessage />
            </FormItem>
          )}
        />
      </form>
    </Form>
  );
}

🔗 Integration with TanStack Query

🎯 TanStack Query + Forms Use Cases:

When to integrate TanStack Query with forms:

• ✅ CRUD Operations: Create, edit, delete entities (users, devices, orgs)
• ✅ Cache Management: Automatic data synchronization after modifications
• ✅ Real-time Updates: Forms with shared data between users
• ✅ Optimistic Updates: Fast actions with rollback on error
• ✅ Complex Dependencies: Forms with related data (dynamic dropdowns)

Decision patterns:

// 🎯 Integration choice matrix
const integrationDecisionMatrix = {
  // ✅ REQUIRED - Full integration
  complexCRUD: {
    useCase: "Complete entity management (User, Device, Organization)",
    features: ["Query existing data", "Mutate", "Cache invalidation", "Error handling"],
    benefits: "Automatic synchronization, performance, optimal UX",
  },
  
  // ✅ RECOMMENDED - Partial integration  
  dataDependent: {
    useCase: "Forms with server data (dropdowns, validation)",
    features: ["useQuery for options", "useMutation for submit"],
    benefits: "Up-to-date data, loading states, error handling",
  },
  
  // ❌ NOT NECESSARY - Simple form
  simpleForm: {
    useCase: "Contact, feedback, forms without complex persistence",
    alternative: "Direct fetch() or custom hook",
    why: "No cache, no synchronization, no dependencies",
  },
};

IoT Platform specific scenarios:

// 🎯 Device Management - Complete use case
const deviceManagementForm = {
  scenario: "IoT device configuration editing",
  dataFlow: [
    "1. useQuery -> Load existing device config",
    "2. Form -> Pre-fill with existing data",
    "3. useMutation -> Save modifications",
    "4. Cache invalidation -> Sync device list",
    "5. Optimistic update -> Immediate user feedback",
  ],
  benefits: "Smooth UX, data sync, robust error handling",
};

// 🎯 Business Flow Creation - Complex validation
const businessFlowForm = {
  scenario: "Creating business rules with dynamic conditions",
  complexity: [
    "Device dropdowns (useQuery)",
    "Server condition validation (async)",
    "Real-time preview",
    "Save with rollback on failure",
  ],
};

Form with Mutation Integration:

// Form that integrates with TanStack Query mutations
export function UserFormWithQuery({ userId, onSuccess }: { userId?: string; onSuccess?: () => void }) {
  const queryClient = useQueryClient();

  // Query for existing user data (edit mode)
  const { data: existingUser, isLoading: isLoadingUser } = useQuery({
    queryKey: ['user', userId],
    queryFn: () => api.users.getById(userId!),
    enabled: !!userId,
  });

  // Mutation for creating/updating user
  const userMutation = useMutation({
    mutationFn: (data: UserFormData) => {
      return userId 
        ? api.users.update(userId, data)
        : api.users.create(data);
    },
    onSuccess: (newUser, variables) => {
      // Invalidate and refetch related queries
      queryClient.invalidateQueries({ queryKey: ['users'] });
      
      if (userId) {
        // Update specific user query cache
        queryClient.setQueryData(['user', userId], newUser);
      } else {
        // Add new user to list cache
        queryClient.setQueryData(['users'], (old: any) => ({
          ...old,
          data: [newUser, ...(old?.data || [])],
        }));
      }

      toast({
        title: "Success",
        description: userId ? "User updated successfully" : "User created successfully",
      });

      onSuccess?.();
    },
    onError: (error: any) => {
      // Handle different error scenarios
      if (error.status === 409) {
        form.setError('email', {
          type: 'server',
          message: 'Email already exists',
        });
      } else if (error.status === 422) {
        // Handle validation errors from server
        error.data?.errors?.forEach((err: any) => {
          form.setError(err.field as keyof UserFormData, {
            type: 'server',
            message: err.message,
          });
        });
      } else {
        toast({
          title: "Error",
          description: error.message || "An error occurred",
          variant: "destructive",
        });
      }
    },
  });

  const form = useForm<UserFormData>({
    resolver: zodResolver(userFormSchema),
    defaultValues: {
      email: "",
      name: "",
      // ... other defaults
    },
  });

  // Update form when existing user data loads
  React.useEffect(() => {
    if (existingUser) {
      form.reset({
        email: existingUser.email,
        name: existingUser.name,
        role: existingUser.role,
        // ... map other fields
      });
    }
  }, [existingUser, form]);

  const onSubmit = (data: UserFormData) => {
    userMutation.mutate(data);
  };

  if (isLoadingUser) {
    return <FormSkeleton />;
  }

  return (
    <Form {...form}>
      <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-6">
        {/* Form fields here */}
        
        <Button
          type="submit"
          disabled={userMutation.isPending || !form.formState.isValid}
        >
          {userMutation.isPending && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
          {userId ? "Update User" : "Create User"}
        </Button>
      </form>
    </Form>
  );
}

🏗️ Reusable Form Components

🎯 Reusable Component Creation Criteria:

When to create a custom field component:

// 🎯 Reusability decision matrix
const reusabilityMatrix = {
  // ✅ CREATE a custom component when:
  highReuse: {
    threshold: "3+ uses across the app",
    examples: ["PasswordField", "OrganizationSelect", "TagMultiSelect"],
    benefits: "DRY, UI consistency, centralized maintenance",
  },
  
  complexLogic: {
    criteria: "Repeated specific business logic",
    examples: ["DeviceSerialValidator", "BusinessRuleCondition"],
    benefits: "Logic encapsulation, testability, reusability",
  },
  
  customUI: {
    criteria: "Specialized user interface",
    examples: ["FileUploadWithPreview", "MapLocationPicker", "ColorPicker"],
    benefits: "Optimized UX, specialized business component",
  },
  
  // ❌ DO NOT create when:
  oneTimeUse: {
    criteria: "Single use or very specific use",
    alternative: "Use FormField directly",
    why: "Over-engineering, unnecessary complexity",
  },
};

Decision guide by IoT Platform use case:

Component	Use Cases	Reusability	Complexity	Create?
PasswordField	Login, registration, password change	🟢 High (5+ places)	🟡 Medium (validation + UI)	✅ YES
OrganizationSelect	User forms, device assignment	🟢 High (8+ forms)	🟡 Medium (API + search)	✅ YES
DeviceSerialInput	Device registration, configuration	🟡 Medium (3 places)	🔴 High (async validation)	✅ YES
DateRangePicker	Reports, analytics filters	🟡 Medium (4 places)	🟡 Medium (date logic)	✅ YES
SimpleEmailInput	Contact forms	🔴 Low (1-2 places)	🟢 Simple (basic validation)	❌ NO

Decision example - PasswordField:

// 🎯 PasswordField - Reusability analysis
const passwordFieldAnalysis = {
  useCases: [
    "Login form",
    "User registration", 
    "User profile edit",
    "Password reset",
    "Admin user creation",
  ],
  sharedFeatures: [
    "Show/hide toggle",
    "Strength indicator",
    "Validation rules",
    "Accessibility",
  ],
  customization: {
    showStrength: "boolean", // Optional depending on context
    label: "string",         // Customizable
    required: "boolean",     // Context-dependent
  },
  conclusion: "✅ Justifies a reusable component",
};

Custom Field Components:

// Reusable password field with strength indicator
export function PasswordField({ 
  control, 
  name, 
  label = "Password",
  showStrength = true 
}: {
  control: Control<any>;
  name: string;
  label?: string;
  showStrength?: boolean;
}) {
  const [showPassword, setShowPassword] = React.useState(false);
  const watchedPassword = useWatch({ control, name });

  const getPasswordStrength = (password: string) => {
    if (!password) return { score: 0, label: "" };
    
    let score = 0;
    if (password.length >= 8) score++;
    if (/[a-z]/.test(password)) score++;
    if (/[A-Z]/.test(password)) score++;
    if (/\d/.test(password)) score++;
    if (/[^a-zA-Z0-9]/.test(password)) score++;

    const labels = ["Very Weak", "Weak", "Fair", "Good", "Strong"];
    return { score, label: labels[score] || "" };
  };

  const strength = showStrength ? getPasswordStrength(watchedPassword || "") : null;

  return (
    <FormField
      control={control}
      name={name}
      render={({ field }) => (
        <FormItem>
          <FormLabel>{label} *</FormLabel>
          <FormControl>
            <div className="relative">
              <Input
                type={showPassword ? "text" : "password"}
                placeholder="Enter password"
                {...field}
              />
              <Button
                type="button"
                variant="ghost"
                size="sm"
                className="absolute right-0 top-0 h-full px-3 py-2 hover:bg-transparent"
                onClick={() => setShowPassword(!showPassword)}
              >
                {showPassword ? (
                  <EyeOff className="h-4 w-4" />
                ) : (
                  <Eye className="h-4 w-4" />
                )}
              </Button>
            </div>
          </FormControl>
          
          {showStrength && strength && watchedPassword && (
            <div className="mt-2">
              <div className="flex gap-1 mb-1">
                {[...Array(5)].map((_, i) => (
                  <div
                    key={i}
                    className={`h-1 w-full rounded ${
                      i < strength.score
                        ? strength.score <= 2
                          ? "bg-red-500"
                          : strength.score === 3
                          ? "bg-yellow-500"
                          : "bg-green-500"
                        : "bg-gray-200"
                    }`}
                  />
                ))}
              </div>
              <p className="text-xs text-muted-foreground">
                Strength: {strength.label}
              </p>
            </div>
          )}
          
          <FormMessage />
        </FormItem>
      )}
    />
  );
}

// Reusable organization selector with search
export function OrganizationSelectField({ 
  control, 
  name, 
  label = "Organization",
  required = false 
}: {
  control: Control<any>;
  name: string;
  label?: string;
  required?: boolean;
}) {
  const [search, setSearch] = React.useState("");

  const { data: organizations = [], isLoading } = useQuery({
    queryKey: ['organizations', search],
    queryFn: () => api.organizations.search({ q: search, limit: 20 }),
    staleTime: 5 * 60 * 1000, // 5 minutes
  });

  return (
    <FormField
      control={control}
      name={name}
      render={({ field }) => (
        <FormItem>
          <FormLabel>
            {label} {required && "*"}
          </FormLabel>
          <Popover>
            <PopoverTrigger asChild>
              <FormControl>
                <Button
                  variant="outline"
                  role="combobox"
                  className={cn(
                    "w-full justify-between",
                    !field.value && "text-muted-foreground"
                  )}
                >
                  {field.value
                    ? organizations.find((org) => org.id === field.value)?.name
                    : "Select organization..."}
                  <ChevronsUpDown className="ml-2 h-4 w-4 shrink-0 opacity-50" />
                </Button>
              </FormControl>
            </PopoverTrigger>
            <PopoverContent className="w-full p-0" align="start">
              <Command>
                <CommandInput
                  placeholder="Search organizations..."
                  value={search}
                  onValueChange={setSearch}
                />
                <CommandEmpty>
                  {isLoading ? "Loading..." : "No organizations found."}
                </CommandEmpty>
                <CommandGroup className="max-h-64 overflow-y-auto">
                  {organizations.map((org) => (
                    <CommandItem
                      key={org.id}
                      value={org.id}
                      onSelect={() => {
                        field.onChange(org.id);
                      }}
                    >
                      <Check
                        className={cn(
                          "mr-2 h-4 w-4",
                          org.id === field.value ? "opacity-100" : "opacity-0"
                        )}
                      />
                      <div>
                        <div className="font-medium">{org.name}</div>
                        {org.description && (
                          <div className="text-sm text-muted-foreground">
                            {org.description}
                          </div>
                        )}
                      </div>
                    </CommandItem>
                  ))}
                </CommandGroup>
              </Command>
            </PopoverContent>
          </Popover>
          <FormMessage />
        </FormItem>
      )}
    />
  );
}

// Reusable tag multi-select with creation
export function TagMultiSelectField({ 
  control, 
  name, 
  label = "Tags",
  allowCreate = true 
}: {
  control: Control<any>;
  name: string;
  label?: string;
  allowCreate?: boolean;
}) {
  const [search, setSearch] = React.useState("");
  const queryClient = useQueryClient();

  const { data: availableTags = [] } = useQuery({
    queryKey: ['tags', search],
    queryFn: () => api.tags.search({ q: search }),
    staleTime: 2 * 60 * 1000,
  });

  const createTagMutation = useMutation({
    mutationFn: (name: string) => api.tags.create({ name }),
    onSuccess: (newTag) => {
      // Update cache with new tag
      queryClient.setQueryData(['tags', search], (old: any) => [
        newTag,
        ...(old || []),
      ]);
    },
  });

  return (
    <FormField
      control={control}
      name={name}
      render={({ field }) => (
        <FormItem>
          <FormLabel>{label}</FormLabel>
          <FormControl>
            <MultiSelect
              options={availableTags.map(tag => ({
                value: tag.id,
                label: tag.name,
              }))}
              selected={field.value || []}
              onChange={field.onChange}
              placeholder="Select tags..."
              searchPlaceholder="Search or create tags..."
              onSearch={setSearch}
              onCreate={allowCreate ? async (name: string) => {
                const newTag = await createTagMutation.mutateAsync(name);
                return { value: newTag.id, label: newTag.name };
              } : undefined}
              loading={createTagMutation.isPending}
            />
          </FormControl>
          <FormDescription>
            Select existing tags or create new ones
          </FormDescription>
          <FormMessage />
        </FormItem>
      )}
    />
  );
}

📱 Accessibility & Internationalization

🎯 When to implement full accessibility:

Accessibility decision criteria:

// 🎯 Accessibility requirements matrix
const accessibilityRequirements = {
  // 🚨 REQUIRED - Legal compliance
  legalRequirements: {
    sectors: ["Public", "Healthcare", "Finance", "Education"],
    standards: ["WCAG 2.1 AA", "ADA compliance", "Section 508"],
    consequences: "Legal risks, user exclusion, reputation damage",
  },
  
  // ✅ RECOMMENDED - Business case
  businessValue: {
    userBase: "15-20% of users have accessibility needs",
    marketExpansion: "Access to new markets and customers",
    innovation: "Improves UX for all users",
  },
  
  // 🎯 SPECIFIC - IoT Platform context
  iotContext: {
    industrialUsers: "Noisy environments, variable lighting",
    mobileWorkers: "Mobile usage, wearing gloves",
    diverseUsers: "Technicians, managers, different technical levels",
  },
};

Implementation levels by context:

Context	Accessibility Level	Justification	Effort
Admin/config forms	🔴 Complete (WCAG AA)	Critical professional usage	🟡 High
IoT dashboards	🟡 Standard (WCAG A)	Data reading, navigation	🟡 Medium
User forms	🔴 Complete (WCAG AA)	Frequent interaction, critical UX	🟡 High
Information pages	🟢 Basic (semantic)	Consultation, low interaction	🟢 Low

IoT internationalization contexts:

// 🌍 i18n use cases for IoT Platform
const i18nUseCases = {
  // ✅ CRITICAL - User interface
  userFacing: {
    components: ["Forms", "Error messages", "Labels", "Notifications"],
    languages: ["FR", "EN", "NL"], // Belgian markets
    dynamic: "Real-time language switching",
  },
  
  // ✅ IMPORTANT - Business data
  businessData: {
    components: ["Device types", "Error messages", "Status labels"],
    challenge: "Translating dynamic data from API",
    solution: "Translation keys + fallbacks",
  },
  
  // 🎯 SPECIFIC IoT - Technical terminology
  technicalContent: {
    challenge: "Specialized IoT terminology",
    approach: "Multilingual technical glossary",
    examples: ["Sensor types", "Connectivity protocols", "Alert levels"],
  },
};

Priority implementation scenarios:

• ✅ Device configuration forms: Critical usage, expensive errors
• ✅ Monitoring dashboards: Fast reading, efficient navigation required
• ✅ Organization onboarding: First impression, user diversity
• ✅ Alert management: Emergency situations, user stress
• 🟡 Reports and analytics: Consultation, less critical for accessibility

Accessible Form Pattern:

// Form with comprehensive accessibility support
export function AccessibleUserForm({ lang }: { lang: Locale }) {
  const t = useTranslations('userForm'); // i18n hook
  
  const form = useForm<UserFormData>({
    resolver: zodResolver(userFormSchema),
    defaultValues: {
      email: "",
      name: "",
    },
  });

  // Announce form errors to screen readers
  const errors = form.formState.errors;
  React.useEffect(() => {
    if (Object.keys(errors).length > 0) {
      const errorMessage = t('validation.formHasErrors', {
        count: Object.keys(errors).length
      });
      
      // Announce to screen readers
      const announcement = document.createElement('div');
      announcement.setAttribute('aria-live', 'polite');
      announcement.setAttribute('aria-atomic', 'true');
      announcement.className = 'sr-only';
      announcement.textContent = errorMessage;
      document.body.appendChild(announcement);
      
      setTimeout(() => document.body.removeChild(announcement), 1000);
    }
  }, [errors, t]);

  return (
    <Form {...form}>
      <form 
        onSubmit={form.handleSubmit(onSubmit)} 
        className="space-y-6"
        noValidate // We handle validation with Zod
        aria-label={t('form.title')}
      >
        {/* Form error summary for screen readers */}
        {Object.keys(errors).length > 0 && (
          <div 
            role="alert" 
            aria-label={t('validation.errorSummary')}
            className="rounded-md border border-red-200 bg-red-50 p-4"
          >
            <div className="flex">
              <AlertCircle className="h-5 w-5 text-red-400" />
              <div className="ml-3">
                <h3 className="text-sm font-medium text-red-800">
                  {t('validation.pleaseFixErrors')}
                </h3>
                <div className="mt-2 text-sm text-red-700">
                  <ul className="list-disc pl-5 space-y-1">
                    {Object.entries(errors).map(([field, error]) => (
                      <li key={field}>
                        <a 
                          href={`#${field}`}
                          className="underline hover:no-underline"
                          onClick={(e) => {
                            e.preventDefault();
                            const element = document.getElementById(field);
                            element?.focus();
                          }}
                        >
                          {t(`fields.${field}.label`)}: {error?.message}
                        </a>
                      </li>
                    ))}
                  </ul>
                </div>
              </div>
            </div>
          </div>
        )}

        <FormField
          control={form.control}
          name="email"
          render={({ field, fieldState }) => (
            <FormItem>
              <FormLabel htmlFor="email">
                {t('fields.email.label')} *
              </FormLabel>
              <FormControl>
                <Input
                  id="email"
                  type="email"
                  placeholder={t('fields.email.placeholder')}
                  aria-describedby={fieldState.error ? "email-error" : "email-description"}
                  aria-invalid={!!fieldState.error}
                  {...field}
                />
              </FormControl>
              <FormDescription id="email-description">
                {t('fields.email.description')}
              </FormDescription>
              {fieldState.error && (
                <FormMessage 
                  id="email-error" 
                  role="alert"
                  aria-live="polite"
                />
              )}
            </FormItem>
          )}
        />

        <div className="flex justify-between">
          <Button
            type="button"
            variant="outline"
            onClick={() => form.reset()}
          >
            {t('actions.reset')}
          </Button>
          
          <Button
            type="submit"
            disabled={form.formState.isSubmitting}
            aria-describedby={form.formState.isSubmitting ? "submit-status" : undefined}
          >
            {form.formState.isSubmitting && (
              <Loader2 className="mr-2 h-4 w-4 animate-spin" />
            )}
            {t('actions.submit')}
          </Button>
        </div>

        {/* Screen reader status update */}
        {form.formState.isSubmitting && (
          <div id="submit-status" className="sr-only" aria-live="polite">
            {t('status.submitting')}
          </div>
        )}
      </form>
    </Form>
  );
}

⚡ Performance Optimization

🎯 When to optimize form performance:

Performance thresholds and indicators:

// 🎯 Decision criteria for optimization
const performanceThresholds = {
  // ⚠️ OPTIMIZATION REQUIRED when:
  formComplexity: {
    fieldCount: "> 15 fields",
    renderTime: "> 100ms initial render",
    reRenderFreq: "> 5 re-renders per second",
    memoryUsage: "> 10MB for the form",
  },
  
  // 🔍 MONITORING REQUIRED when:
  userExperience: {
    dropdownOptions: "> 500 items",
    fileUpload: "> 10MB files",
    asyncValidation: "> 3 simultaneous API calls",
    dynamicFields: "> 10 dynamic fields",
  },
  
  // 🚨 CRITICAL OPTIMIZATION when:
  businessImpact: {
    userCompletion: "< 80% completion rate",
    performanceComplaints: "Negative user feedback",
    bounceRate: "> 30% form abandonment",
  },
};

IoT Platform use cases requiring optimization:

• ✅ IoT site configuration: 20+ sensors, multiple parameters per sensor
• ✅ Bulk device import: Validation form with 1000+ CSV lines
• ✅ Complex business rules: Multiple conditions, interdependent dropdowns
• ✅ Monitoring dashboard: Real-time filter forms with many options
• ✅ Organization configuration: Onboarding with 30+ business parameters

Optimization techniques matrix:

Problem	Technique	Use Case	Impact
Excessive re-renders	React.memo, useMemo	Fields with heavy calculations	🟢 High
Slow validation	Debouncing, async optimization	Server validation, API calls	🟢 High
Large datasets	Virtualization, pagination	Dropdowns with 1000+ options	🟡 Medium
Form persistence	localStorage, sessionStorage	Long forms, draft saving	🟡 Medium
Bundle size	Code splitting, lazy loading	Complex forms rarely used	🟡 Medium

Form Field Optimization:

// Use React.memo for expensive field components
const ExpensiveFormField = React.memo(({ control, name, options }: {
  control: Control<any>;
  name: string;
  options: Array<{ value: string; label: string }>;
}) => {
  // Expensive computation or large option lists
  const processedOptions = React.useMemo(() => {
    return options.map(option => ({
      ...option,
      searchTokens: option.label.toLowerCase().split(' '),
    }));
  }, [options]);

  return (
    <FormField
      control={control}
      name={name}
      render={({ field }) => (
        <FormItem>
          <FormLabel>Expensive Field</FormLabel>
          <FormControl>
            <Select value={field.value} onValueChange={field.onChange}>
              <SelectTrigger>
                <SelectValue placeholder="Select option..." />
              </SelectTrigger>
              <SelectContent>
                {processedOptions.map(option => (
                  <SelectItem key={option.value} value={option.value}>
                    {option.label}
                  </SelectItem>
                ))}
              </SelectContent>
            </Select>
          </FormControl>
          <FormMessage />
        </FormItem>
      )}
    />
  );
});

// Debounced validation for expensive checks
const useDebouncedValidation = (value: string, validationFn: (val: string) => Promise<boolean>, delay = 500) => {
  const [isValidating, setIsValidating] = React.useState(false);
  const [isValid, setIsValid] = React.useState<boolean | null>(null);

  const debouncedValidate = React.useCallback(
    debounce(async (val: string) => {
      if (!val) {
        setIsValid(null);
        setIsValidating(false);
        return;
      }

      setIsValidating(true);
      try {
        const result = await validationFn(val);
        setIsValid(result);
      } catch {
        setIsValid(false);
      } finally {
        setIsValidating(false);
      }
    }, delay),
    [validationFn, delay]
  );

  React.useEffect(() => {
    debouncedValidate(value);
  }, [value, debouncedValidate]);

  return { isValidating, isValid };
};

// Optimized form with controlled re-renders
const OptimizedForm = () => {
  const form = useForm({
    resolver: zodResolver(schema),
    mode: "onTouched", // Only validate after user interaction
  });

  // Split form into sections to minimize re-renders
  const BasicInfoSection = React.memo(() => (
    <>
      <FormField control={form.control} name="name" render={NameField} />
      <FormField control={form.control} name="email" render={EmailField} />
    </>
  ));

  const SecuritySection = React.memo(() => (
    <>
      <FormField control={form.control} name="password" render={PasswordField} />
      <FormField control={form.control} name="role" render={RoleField} />
    </>
  ));

  return (
    <Form {...form}>
      <form onSubmit={form.handleSubmit(onSubmit)}>
        <BasicInfoSection />
        <SecuritySection />
        <Button type="submit">Submit</Button>
      </form>
    </Form>
  );
};

Form State Persistence:

// Auto-save form data to localStorage
const useFormPersistence = <T extends Record<string, any>>(
  key: string,
  form: UseFormReturn<T>
) => {
  // Load saved data on mount
  React.useEffect(() => {
    try {
      const saved = localStorage.getItem(`form-${key}`);
      if (saved) {
        const data = JSON.parse(saved);
        form.reset(data);
      }
    } catch (error) {
      console.warn('Failed to load saved form data:', error);
    }
  }, [key, form]);

  // Save data on change (debounced)
  const watchedValues = form.watch();
  const debouncedSave = React.useCallback(
    debounce((data: T) => {
      try {
        localStorage.setItem(`form-${key}`, JSON.stringify(data));
      } catch (error) {
        console.warn('Failed to save form data:', error);
      }
    }, 1000),
    [key]
  );

  React.useEffect(() => {
    if (Object.keys(watchedValues).length > 0) {
      debouncedSave(watchedValues);
    }
  }, [watchedValues, debouncedSave]);

  // Clear saved data
  const clearSaved = React.useCallback(() => {
    localStorage.removeItem(`form-${key}`);
  }, [key]);

  return { clearSaved };
};

// Usage example
export function PersistentForm() {
  const form = useForm<UserFormData>({
    resolver: zodResolver(userFormSchema),
    defaultValues: { email: "", name: "" },
  });

  const { clearSaved } = useFormPersistence('user-registration', form);

  const onSubmit = async (data: UserFormData) => {
    try {
      await api.users.create(data);
      clearSaved(); // Clear saved data on successful submission
      toast({ title: "Success", description: "User created successfully" });
    } catch (error) {
      // Handle error, keep saved data for retry
    }
  };

  return (
    <Form {...form}>
      <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-6">
        {/* Form fields */}
        <div className="flex justify-between items-center">
          <Button
            type="button"
            variant="ghost"
            size="sm"
            onClick={clearSaved}
          >
            Clear Saved Data
          </Button>
          <Button type="submit">Submit</Button>
        </div>
      </form>
    </Form>
  );
}

🛠️ Common Solutions & Anti-patterns

❌ AVOID - Common Anti-patterns:

// 🚨 DON'T: Uncontrolled form state updates
const BadForm = () => {
  const [email, setEmail] = useState(""); // ❌ Manual state management
  
  return (
    <form>
      <input 
        value={email} 
        onChange={(e) => setEmail(e.target.value)} // ❌ Bypasses form validation
      />
    </form>
  );
};

// 🚨 DON'T: Missing error handling
const BadFormSubmit = async (data: FormData) => {
  await api.create(data); // ❌ No error handling
  // ❌ No loading state
  // ❌ No user feedback
};

// 🚨 DON'T: Inline validation functions
const BadValidation = () => (
  <FormField
    control={form.control}
    name="email"
    rules={{
      validate: (value) => value.includes('@') || 'Invalid email' // ❌ Not type-safe
    }}
  />
);

✅ DO - Correct Implementations:

// ✅ Proper form with comprehensive error handling
const GoodForm = () => {
  const form = useForm<FormData>({
    resolver: zodResolver(formSchema), // ✅ Type-safe validation
    mode: "onTouched",
  });

  const { mutate, isPending, error } = useMutation({
    mutationFn: api.users.create,
    onSuccess: () => {
      form.reset(); // ✅ Reset form on success
      toast({ title: "Success", description: "User created" });
    },
    onError: (error) => {
      // ✅ Proper error handling
      if (error.status === 409) {
        form.setError('email', { message: 'Email already exists' });
      } else {
        toast({ title: "Error", description: error.message });
      }
    },
  });

  return (
    <Form {...form}>
      <form onSubmit={form.handleSubmit((data) => mutate(data))}>
        {/* ✅ Proper field implementation */}
        <FormField
          control={form.control}
          name="email"
          render={({ field }) => (
            <FormItem>
              <FormLabel>Email *</FormLabel>
              <FormControl>
                <Input 
                  type="email" 
                  disabled={isPending} // ✅ Disable during submission
                  {...field} 
                />
              </FormControl>
              <FormMessage />
            </FormItem>
          )}
        />
        
        <Button type="submit" disabled={isPending || !form.formState.isValid}>
          {isPending && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
          Create User
        </Button>
      </form>
    </Form>
  );
};

🔧 Common Problem Solutions:

// Problem: Form doesn't reset after successful submission
// Solution: Use form.reset() in mutation onSuccess

// Problem: Form validation runs on every keystroke
// Solution: Use mode: "onTouched" or "onBlur"

// Problem: Complex async validation is slow
// Solution: Debounce validation and show loading states

// Problem: Form data is lost on page refresh
// Solution: Implement form persistence with localStorage

// Problem: Large forms cause performance issues
// Solution: Split into sections with React.memo, use controlled re-renders

// Problem: File uploads not working with validation
// Solution: Use custom validation for File objects
const fileSchema = z.object({
  file: z
    .instanceof(File)
    .refine((file) => file.size <= 5000000, "File too large")
    .refine((file) => file.type.startsWith("image/"), "Must be an image"),
});

// Problem: Form fields not accessible
// Solution: Always use proper labels, descriptions, and ARIA attributes

📋 Form Checklist:

## Pre-submission Checklist

✅ **Schema & Validation:**
- [ ] Zod schema defined with proper error messages
- [ ] Cross-field validation implemented where needed
- [ ] Client and server validation aligned

✅ **User Experience:**
- [ ] Loading states during submission
- [ ] Success/error feedback with toasts
- [ ] Form disabled during submission
- [ ] Reset form after successful submission

✅ **Performance:**
- [ ] Expensive fields memoized
- [ ] Validation mode optimized (onTouched/onBlur)
- [ ] Async validation debounced
- [ ] Large forms split into sections

✅ **Accessibility:**
- [ ] Proper labels and descriptions
- [ ] Error messages linked to fields
- [ ] Form has descriptive aria-label
- [ ] Keyboard navigation works
- [ ] Screen reader announcements

✅ **Error Handling:**
- [ ] Server errors mapped to form fields
- [ ] Network errors handled gracefully
- [ ] Validation errors user-friendly
- [ ] Error summary for multiple errors

✅ **Integration:**
- [ ] TanStack Query cache invalidation
- [ ] Optimistic updates where appropriate
- [ ] Form data transformation handled
- [ ] File uploads working correctly

Radix UI + Tailwind Pattern

✅ DO - Consistent component composition:

// components/ui/dialog.tsx (following our pattern)
const Dialog = DialogPrimitive.Root;
const DialogTrigger = DialogPrimitive.Trigger;

const DialogContent = React.forwardRef<
  React.ElementRef<typeof DialogPrimitive.Content>,
  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Content>
>(({ className, children, ...props }, ref) => (
  <DialogPortal>
    <DialogOverlay />
    <DialogPrimitive.Content
      ref={ref}
      className={cn(
        "fixed left-[50%] top-[50%] z-50 grid w-full max-w-lg translate-x-[-50%] translate-y-[-50%] gap-4 border bg-background p-6 shadow-lg duration-200 data-[state=open]:animate-in data-[state=closed]:animate-out",
        className
      )}
      {...props}
    >
      {children}
      <DialogPrimitive.Close className="absolute right-4 top-4 rounded-sm opacity-70 ring-offset-background transition-opacity hover:opacity-100">
        <X className="h-4 w-4" />
      </DialogPrimitive.Close>
    </DialogPrimitive.Content>
  </DialogPortal>
));

Loading States Pattern

// ✅ DO - Consistent loading UI
const LoadingSkeleton = () => (
  <div className="animate-pulse space-y-4">
    <div className="h-4 bg-gray-200 rounded w-3/4"></div>
    <div className="h-4 bg-gray-200 rounded w-1/2"></div>
    <div className="h-32 bg-gray-200 rounded"></div>
  </div>
);

// Usage in Suspense boundaries
<Suspense fallback={<LoadingSkeleton />}>
  <LazyComponent />
</Suspense>

---

🔍 Code Quality Standards

TypeScript Configuration

Our strict TypeScript setup in tsconfig.json:

{
  "extends": "tsconfig/nextjs.json",
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"],
      "@components/*": ["./src/app/[lang]/*"]
    },
    "strictNullChecks": true
  }
}

ESLint & Prettier Rules

# Code quality commands
npm run lint        # Check linting issues
npm run lint:fix    # Fix auto-fixable issues
npm run check-types # TypeScript type checking
npm run format:write # Format code
npm run format:check # Check formatting

Testing Strategy ⚠️ Implementation in Progress

🚧 Testing Setup Status: Like our TanStack Query integration, our comprehensive testing strategy is currently being implemented. The foundation is in place with Jest + Playwright, but advanced patterns and complete coverage are being rolled out progressively.

Our testing approach follows industry best practices adapted for IoT applications, ensuring reliability, performance, and maintainability across the entire platform.

---

Testing Architecture Overview

🏗️ Test Stack Integration with Your Monorepo:

# Your current testing setup:
apps/backoffice-frontend/
├── __tests__/                    # Unit tests
│   ├── components/              # Component tests
│   ├── hooks/                   # Custom hooks tests
│   ├── lib/                     # Utility function tests
│   └── api/                     # API layer tests
├── e2e/                         # Playwright E2E tests
├── jest.config.js              # Jest configuration
└── playwright.config.ts        # Playwright configuration

# Shared testing utilities from workspace:
packages/
├── @pxs/database/              # Shared DTOs for type-safe tests  
├── @pxs/common/                # Shared test utilities
└── @pxs/ui/                    # Component testing library

🎯 Testing Philosophy:

• Type Safety First: All tests use your real DTOs from @pxs/database
• Real API Integration: Tests work with your actual API classes (APIDevice, APITag, etc.)
• IoT Domain Focus: Test patterns designed for device management, real-time data, and complex business flows
• Progressive Implementation: Starting with critical paths, expanding coverage iteratively

---

Types of Testing

1. 🧪 Unit Testing (Jest + React Testing Library)

Current Status: ✅ Active - Basic setup complete, expanding coverage

# Unit testing commands
npm run test                    # Run all unit tests
npm run test:watch             # Watch mode for development  
npm run test:coverage          # Generate coverage report
npm run test:update-snapshots  # Update component snapshots
npm run test:debug             # Run with debugging enabled

What we test:

• Custom Hooks: TanStack Query hooks, Zustand stores
• Components: UI components with props and interactions
• API Layer: Your API classes with mocked responses
• Business Logic: Form validation, data transformations
• Type Safety: DTO integrations and type correctness

2. 🎭 End-to-End Testing (Playwright)

Current Status: 🚧 Setup in Progress - Infrastructure ready, test suites being created

# E2E testing commands  
npx playwright test                    # Run all E2E tests
npx playwright test --ui              # Interactive mode with UI
npx playwright test --headed          # Run with visible browser
npx playwright test --project=chromium # Test specific browser
npx playwright show-report           # View test reports
npx playwright codegen              # Generate test code interactively

What we test:

• Complete User Flows: Device registration → Configuration → Monitoring
• Authentication: Login, logout, session management
• Real-time Features: Live dashboards, device status updates
• Cross-browser Compatibility: Chrome, Firefox, Safari
• Mobile Responsiveness: IoT dashboards on mobile devices

3. 👁️ Visual Regression Testing

Current Status: 📋 Planned - Will be implemented with Playwright Screenshots + Percy/Chromatic

# Visual testing commands (coming soon)
npx playwright test --grep="visual"   # Run visual tests only
npm run test:visual:update           # Update visual baselines
npm run test:visual:review          # Review visual changes

What we'll test:

• Component Library: @pxs/ui components consistency
• Dashboards: IoT dashboards layout and styling
• Charts & Maps: Azure Maps rendering, telemetry charts
• Responsive Design: Mobile vs desktop layouts
• Theme Consistency: Light/dark themes, brand colors

4. ⚡ Performance Testing

Current Status: 📋 Planned - Bundle analysis active, runtime performance testing coming

# Performance testing commands (coming soon)
npm run test:performance           # Run performance tests
npm run test:lighthouse           # Lighthouse CI integration
npm run test:bundle-size          # Bundle size regression tests

What we'll test:

• Loading Performance: Critical IoT dashboards load times
• Runtime Performance: Real-time data updates, large device lists
• Bundle Size: Prevent regression in JavaScript bundle sizes
• Memory Usage: Long-running dashboard memory leaks
• Network Efficiency: API call optimization, caching effectiveness

---

Concrete Testing Patterns with Your Real API

🧪 Unit Testing Patterns

Testing TanStack Query Hooks with Your Real API Classes:

// __tests__/hooks/useDevices.test.ts
import { renderHook, waitFor } from '@testing-library/react';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { useDevices } from '@/hooks/useDevices';
import api from '@/lib/api';
import { DeviceDTO } from '@pxs/database';

// Mock your real API class
jest.mock('@/lib/api');
const mockApi = api as jest.Mocked<typeof api>;

const createWrapper = () => {
  const queryClient = new QueryClient({
    defaultOptions: { queries: { retry: false }, mutations: { retry: false } },
  });
  
  return ({ children }: { children: React.ReactNode }) => (
    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
  );
};

describe('useDevices', () => {
  beforeEach(() => {
    jest.clearAllMocks();
  });

  it('should fetch devices using real APIDevice.list method', async () => {
    // Mock response with real DTO structure
    const mockDevicesResponse = {
      data: [
        { id: 'device-1', name: 'Sensor 01', status: 'online', batteryLevel: 85 },
        { id: 'device-2', name: 'Gateway 01', status: 'maintenance', batteryLevel: 92 }
      ] as DeviceDTO[],
      meta: { totalPages: 1, totalItems: 2, currentPage: 1 }
    };

    mockApi.device.list.mockResolvedValue(mockDevicesResponse);

    const { result } = renderHook(() => useDevices('test-token'), {
      wrapper: createWrapper(),
    });

    await waitFor(() => {
      expect(result.current.isSuccess).toBe(true);
    });

    // Verify real API method was called with correct parameters
    expect(mockApi.device.list).toHaveBeenCalledWith('test-token', 1, 10, 'DESC', '', undefined, {});
    expect(result.current.data?.data).toHaveLength(2);
    expect(result.current.data?.data[0].name).toBe('Sensor 01');
  });

  it('should handle AbstractAPI errors correctly', async () => {
    // Mock your AbstractAPI error format
    const mockError = new Error('Device not found');
    mockError.status = 404;
    mockApi.device.list.mockRejectedValue(mockError);

    const { result } = renderHook(() => useDevices('test-token'), {
      wrapper: createWrapper(),
    });

    await waitFor(() => {
      expect(result.current.isError).toBe(true);
    });

    expect(result.current.error).toEqual(mockError);
  });
});

Testing Components with Real DTOs:

// __tests__/components/DeviceCard.test.tsx  
import { render, screen } from '@testing-library/react';
import { DeviceCard } from '@/components/DeviceCard';
import { DeviceDTO } from '@pxs/database';

describe('DeviceCard', () => {
  const mockDevice: DeviceDTO = {
    id: 'device-123',
    name: 'Temperature Sensor 01', 
    serialNumber: 'TS-001-2024',
    status: 'online',
    batteryLevel: 78,
    lastSeenAt: new Date('2024-01-15T10:30:00Z'),
    tags: [
      { id: 'tag-1', name: 'Critical', color: '#ff4444' },
      { id: 'tag-2', name: 'Building A', color: '#4444ff' }
    ]
  };

  it('should display device information correctly', () => {
    render(<DeviceCard device={mockDevice} />);

    // Test real DTO properties
    expect(screen.getByText('Temperature Sensor 01')).toBeInTheDocument();
    expect(screen.getByText('TS-001-2024')).toBeInTheDocument();
    expect(screen.getByText('78%')).toBeInTheDocument();
    expect(screen.getByText('Critical')).toBeInTheDocument();
    expect(screen.getByText('Building A')).toBeInTheDocument();

    // Test computed values
    expect(screen.getByText(/online/i)).toBeInTheDocument();
    expect(screen.getByText(/Jan 15, 2024/)).toBeInTheDocument();
  });

  it('should handle missing optional properties', () => {
    const deviceWithoutTags: DeviceDTO = {
      ...mockDevice,
      tags: undefined,
      batteryLevel: null,
    };

    render(<DeviceCard device={deviceWithoutTags} />);

    expect(screen.getByText('Temperature Sensor 01')).toBeInTheDocument();
    expect(screen.queryByText('Critical')).not.toBeInTheDocument();
    expect(screen.queryByText(/\d+%/)).not.toBeInTheDocument();
  });
});

Testing Your API Classes Directly:

// __tests__/api/device.test.ts
import { APIDevice } from '@/lib/api/device';
import { DeviceDTO } from '@pxs/database';

// Mock fetch and next/navigation for AbstractAPI
global.fetch = jest.fn();
jest.mock('next/navigation', () => ({
  redirect: jest.fn(),
}));

describe('APIDevice', () => {
  let apiDevice: APIDevice;

  beforeEach(() => {
    apiDevice = new APIDevice();
    jest.clearAllMocks();
  });

  it('should call correct endpoint for device list', async () => {
    const mockResponse = {
      data: [{ id: 'device-1', name: 'Test Device' }] as DeviceDTO[],
      meta: { totalPages: 1, totalItems: 1, currentPage: 1 }
    };

    (global.fetch as jest.Mock).mockResolvedValue({
      status: 200,
      headers: { get: jest.fn().mockReturnValue('application/json') },
      json: jest.fn().mockResolvedValue(mockResponse),
    });

    const result = await apiDevice.list('test-token', 1, 20, 'DESC', 'sensor');

    expect(global.fetch).toHaveBeenCalledWith(
      expect.stringContaining('/device?page=1&take=20&orderBy=DESC'),
      expect.objectContaining({
        method: 'GET',
        headers: expect.objectContaining({
          'Authorization': 'Bearer test-token',
          'Content-Type': 'application/json',
        }),
      })
    );

    expect(result.data).toHaveLength(1);
    expect(result.data[0].name).toBe('Test Device');
  });
});

🎭 End-to-End Testing Patterns

Complete User Flow Testing:

// e2e/device-management.spec.ts
import { test, expect } from '@playwright/test';

test.describe('Device Management Flow', () => {
  test.beforeEach(async ({ page }) => {
    // Login with test user
    await page.goto('/auth/login');
    await page.fill('[data-testid="email"]', 'test@iot-platform.com');
    await page.fill('[data-testid="password"]', 'testpass123');
    await page.click('[data-testid="login-button"]');
    
    // Wait for redirect to dashboard
    await expect(page).toHaveURL('/dashboard');
  });

  test('should register and configure a new IoT device', async ({ page }) => {
    // Navigate to device management
    await page.click('[data-testid="devices-nav"]');
    await expect(page).toHaveURL('/devices');

    // Open device registration modal
    await page.click('[data-testid="add-device-button"]');
    await expect(page.locator('[data-testid="device-modal"]')).toBeVisible();

    // Fill device information
    await page.fill('[data-testid="device-name"]', 'Test Sensor 001');
    await page.fill('[data-testid="device-serial"]', 'TS-001-2024');
    await page.selectOption('[data-testid="device-type"]', 'temperature-sensor');
    
    // Configure device settings
    await page.fill('[data-testid="sampling-rate"]', '30');
    await page.selectOption('[data-testid="location"]', 'building-a-floor-1');
    
    // Add tags
    await page.click('[data-testid="add-tag-button"]');
    await page.selectOption('[data-testid="tag-select"]', 'critical');
    
    // Submit form
    await page.click('[data-testid="save-device-button"]');
    
    // Verify device appears in list
    await expect(page.locator('[data-testid="device-list"]')).toContainText('Test Sensor 001');
    await expect(page.locator('[data-testid="device-list"]')).toContainText('TS-001-2024');
    await expect(page.locator('[data-testid="device-list"]')).toContainText('Critical');

    // Test device detail view
    await page.click('[data-testid="device-Test Sensor 001"]');
    await expect(page.locator('[data-testid="device-details"]')).toContainText('Test Sensor 001');
    await expect(page.locator('[data-testid="device-serial"]')).toContainText('TS-001-2024');
    await expect(page.locator('[data-testid="sampling-rate"]')).toContainText('30 seconds');
  });

  test('should handle real-time device updates', async ({ page }) => {
    await page.goto('/devices/device-123');
    
    // Check initial device status
    await expect(page.locator('[data-testid="device-status"]')).toContainText('Online');
    
    // Simulate real-time update (mock WebSocket or polling)
    await page.evaluate(() => {
      // Trigger real-time update via your WebSocket/polling mechanism
      window.dispatchEvent(new CustomEvent('device-update', {
        detail: { deviceId: 'device-123', status: 'maintenance', batteryLevel: 45 }
      }));
    });

    // Verify UI updates in real-time
    await expect(page.locator('[data-testid="device-status"]')).toContainText('Maintenance');
    await expect(page.locator('[data-testid="battery-level"]')).toContainText('45%');
  });

  test('should validate form with business rules', async ({ page }) => {
    await page.goto('/devices/new');
    
    // Test required fields
    await page.click('[data-testid="save-device-button"]');
    await expect(page.locator('[data-testid="name-error"]')).toContainText('Device name is required');
    
    // Test serial number uniqueness (mocked backend validation)
    await page.fill('[data-testid="device-name"]', 'Test Device');
    await page.fill('[data-testid="device-serial"]', 'DUPLICATE-SERIAL');
    await page.click('[data-testid="save-device-button"]');
    
    // Should show server validation error
    await expect(page.locator('[data-testid="serial-error"]')).toContainText('Serial number already exists');
  });
});

📊 IoT-Specific Testing Patterns

Azure Maps Integration Testing:

// __tests__/components/DeviceMap.test.tsx
import { render, screen, waitFor } from '@testing-library/react';
import { DeviceMap } from '@/components/DeviceMap';

// Mock Azure Maps
jest.mock('azure-maps-control', () => ({
  Map: jest.fn(() => ({
    markers: { add: jest.fn(), remove: jest.fn() },
    setCamera: jest.fn(),
  })),
  HtmlMarker: jest.fn(),
}));

describe('DeviceMap', () => {
  const mockDevices = [
    { id: 'device-1', name: 'Sensor A', latitude: 50.8503, longitude: 4.3517 },
    { id: 'device-2', name: 'Gateway B', latitude: 50.8513, longitude: 4.3527 },
  ];

  it('should render map with device markers', async () => {
    render(<DeviceMap devices={mockDevices} />);
    
    await waitFor(() => {
      expect(screen.getByTestId('device-map')).toBeInTheDocument();
    });

    // Verify map initialization
    const { Map } = require('azure-maps-control');
    expect(Map).toHaveBeenCalledWith(
      expect.any(HTMLElement),
      expect.objectContaining({
        authOptions: expect.objectContaining({
          authType: 'subscriptionKey',
        }),
      })
    );
  });
});

Real-time Data Testing:

// __tests__/hooks/useRealtimeDeviceData.test.tsx
import { renderHook, act } from '@testing-library/react';
import { useRealtimeDeviceData } from '@/hooks/useRealtimeDeviceData';

// Mock WebSocket or polling mechanism
jest.mock('@/lib/realtime', () => ({
  subscribeToDevice: jest.fn(),
  unsubscribeFromDevice: jest.fn(),
}));

describe('useRealtimeDeviceData', () => {
  it('should update device data in real-time', async () => {
    const { subscribeToDevice } = require('@/lib/realtime');
    let mockCallback: (data: any) => void;
    
    subscribeToDevice.mockImplementation((deviceId: string, callback: (data: any) => void) => {
      mockCallback = callback;
    });

    const { result } = renderHook(() => useRealtimeDeviceData('device-123'));

    // Simulate real-time update
    act(() => {
      mockCallback({
        deviceId: 'device-123',
        batteryLevel: 65,
        lastSeen: new Date().toISOString(),
        telemetry: { temperature: 22.5, humidity: 58 }
      });
    });

    expect(result.current.batteryLevel).toBe(65);
    expect(result.current.telemetry.temperature).toBe(22.5);
  });
});

---

Comprehensive Test Commands & Workflows

📋 Complete Command Reference

Development & Testing Commands:

# 🧪 Unit Testing (Jest)
npm run test                      # Run all tests once  
npm run test:watch               # Run tests in watch mode
npm run test:coverage           # Generate coverage report
npm run test:update-snapshots   # Update component snapshots
npm run test:debug              # Run tests with debugging enabled
npm run test:ci                 # Run tests with CI configuration
npm run test:changed            # Test only changed files (Git)
npm run test:verbose            # Run with verbose output

# 🎭 E2E Testing (Playwright)  
npx playwright test                    # Run all E2E tests
npx playwright test --ui              # Interactive mode with browser
npx playwright test --headed          # Run with visible browser
npx playwright test --debug          # Run in debug mode
npx playwright test --project=chromium # Test specific browser
npx playwright test devices/          # Test specific directory
npx playwright test --grep="device"   # Test matching pattern
npx playwright show-report           # View test reports
npx playwright codegen              # Generate test code

# 👁️ Visual Testing (Future)
npm run test:visual                  # Run visual regression tests
npm run test:visual:update          # Update visual baselines  
npm run test:visual:approve         # Approve visual changes
npm run test:screenshots           # Generate component screenshots

# ⚡ Performance Testing (Future)
npm run test:lighthouse            # Run Lighthouse CI
npm run test:bundle-size          # Check bundle size regression
npm run test:load                 # Load testing with K6
npm run test:memory              # Memory leak detection

# 🔧 Utility Commands
npm run test:setup               # Setup test databases & mocks
npm run test:cleanup            # Clean test artifacts
npm run test:seed              # Seed test data

🔄 CI/CD Integration

GitHub Actions Workflow Example:

# .github/workflows/test.yml
name: Test Suite

on: [push, pull_request]

jobs:
  unit-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '18'
          cache: 'npm'
      
      - run: npm ci
      - run: npm run test:ci
      - run: npm run test:coverage
      
      # Upload coverage to Codecov
      - uses: codecov/codecov-action@v3
        with:
          file: ./coverage/lcov.info

  e2e-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '18'
      
      - run: npm ci
      - run: npx playwright install
      - run: npm run build
      
      # Start backend for E2E tests
      - run: npm run start:test &
      - run: npx playwright test
      
      # Upload test results
      - uses: actions/upload-artifact@v3
        if: always()
        with:
          name: playwright-report
          path: playwright-report/

🗂️ Test Organization & Structure

Recommended Directory Structure:

apps/backoffice-frontend/
├── __tests__/                        # Unit tests
│   ├── __mocks__/                    # Global mocks
│   │   ├── api.ts                   # API mocks
│   │   ├── azure-maps.ts           # Azure Maps mocks
│   │   └── websocket.ts            # WebSocket mocks
│   ├── components/                  # Component tests
│   │   ├── DeviceCard.test.tsx
│   │   ├── DeviceList.test.tsx
│   │   └── TagManager.test.tsx
│   ├── hooks/                       # Custom hooks tests
│   │   ├── useDevices.test.ts
│   │   ├── useRealtimeData.test.ts
│   │   └── useTags.test.ts
│   ├── lib/                         # Utility tests
│   │   ├── api/                     # API class tests
│   │   ├── utils/                   # Helper function tests
│   │   └── validation/              # Form validation tests
│   └── setup.ts                     # Test setup configuration

├── e2e/                             # Playwright E2E tests
│   ├── auth.spec.ts                # Authentication flows
│   ├── device-management.spec.ts   # Device CRUD operations  
│   ├── dashboard.spec.ts           # Dashboard interactions
│   ├── real-time.spec.ts          # Real-time features
│   └── mobile.spec.ts             # Mobile responsiveness

├── fixtures/                        # Test data
│   ├── devices.json                # Sample device data
│   ├── users.json                  # Sample user data
│   └── telemetry.json             # Sample telemetry data

└── utils/                           # Test utilities
    ├── test-utils.tsx              # Custom render functions
    ├── mock-server.ts             # MSW mock server
    └── playwright-utils.ts        # E2E helpers

⚙️ Configuration Examples

Jest Configuration (jest.config.js):

const nextJest = require('next/jest');

const createJestConfig = nextJest({
  dir: './',
});

const customJestConfig = {
  setupFilesAfterEnv: ['<rootDir>/__tests__/setup.ts'],
  testEnvironment: 'jest-environment-jsdom',
  moduleNameMapping: {
    '^@/(.*)$': '<rootDir>/src/$1',
    '^@pxs/database$': '<rootDir>/../../packages/database/src',
    '^@pxs/common$': '<rootDir>/../../packages/common/src',
  },
  testPathIgnorePatterns: ['<rootDir>/e2e/'],
  coverageDirectory: 'coverage',
  coverageReporters: ['text', 'lcov', 'html'],
  coverageThreshold: {
    global: {
      branches: 70,
      functions: 70,
      lines: 70,
      statements: 70,
    },
  },
  collectCoverageFrom: [
    'src/**/*.{ts,tsx}',
    '!src/**/*.d.ts',
    '!src/**/*.stories.tsx',
  ],
};

module.exports = createJestConfig(customJestConfig);

Playwright Configuration (playwright.config.ts):

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './e2e',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: 'html',
  
  use: {
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
    video: 'retain-on-failure',
  },

  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
    {
      name: 'firefox',
      use: { ...devices['Desktop Firefox'] },
    },
    {
      name: 'webkit',
      use: { ...devices['Desktop Safari'] },
    },
    {
      name: 'mobile-chrome',
      use: { ...devices['Pixel 5'] },
    },
    {
      name: 'mobile-safari',
      use: { ...devices['iPhone 12'] },
    },
  ],

  webServer: {
    command: 'npm run start:test',
    port: 3000,
    reuseExistingServer: !process.env.CI,
  },
});

🛠️ Testing Best Practices for Your IoT Platform

1. Test Data Management:

// utils/test-fixtures.ts
export const createMockDevice = (overrides?: Partial<DeviceDTO>): DeviceDTO => ({
  id: 'device-test-123',
  name: 'Test Temperature Sensor',
  serialNumber: 'TS-TEST-001',
  status: 'online',
  batteryLevel: 85,
  lastSeenAt: new Date(),
  tags: [],
  ...overrides,
});

export const createMockPaginatedDevices = (count = 5) => ({
  data: Array.from({ length: count }, (_, i) => 
    createMockDevice({ id: `device-${i}`, name: `Device ${i}` })
  ),
  meta: { totalPages: 1, totalItems: count, currentPage: 1 }
});

2. API Mocking Strategy:

// __mocks__/api.ts - Mock your entire API structure
export const mockApi = {
  device: {
    list: jest.fn().mockResolvedValue(createMockPaginatedDevices()),
    get: jest.fn().mockResolvedValue(createMockDevice()),
    create: jest.fn().mockResolvedValue(createMockDevice()),
    update: jest.fn().mockResolvedValue(createMockDevice()),
    delete: jest.fn().mockResolvedValue(undefined),
  },
  tag: {
    list: jest.fn().mockResolvedValue([]),
    get: jest.fn().mockResolvedValue({}),
    create: jest.fn().mockResolvedValue({}),
    update: jest.fn().mockResolvedValue({}),
    delete: jest.fn().mockResolvedValue(undefined),
  },
  // ... other API classes
};

3. Component Testing Standards:

// utils/test-utils.tsx - Custom render with providers
export const renderWithProviders = (
  ui: React.ReactElement,
  { 
    queryClient = createTestQueryClient(),
    ...renderOptions 
  } = {}
) => {
  const Wrapper = ({ children }: { children: React.ReactNode }) => (
    <QueryClientProvider client={queryClient}>
      <ThemeProvider>
        {children}
      </ThemeProvider>
    </QueryClientProvider>
  );

  return render(ui, { wrapper: Wrapper, ...renderOptions });
};

Error Handling Pattern

// Global error boundary
export function ErrorBoundary({ children }: { children: React.ReactNode }) {
  return (
    <Suspense fallback={<LoadingSpinner />}>
      <ErrorBoundaryProvider>
        {children}
      </ErrorBoundaryProvider>
    </Suspense>
  );
}

// API error handling
try {
  const result = await api.getData();
  return result;
} catch (error) {
  if (error instanceof ApiError) {
    toast({ 
      title: "API Error", 
      content: error.message,
      variant: "destructive" 
    });
  } else {
    console.error("Unexpected error:", error);
    toast({ 
      title: "Error", 
      content: "Something went wrong" 
    });
  }
  throw error;
}

---

🛠️ Development Workflow

Essential NPM Scripts

# Development
npm run dev                # Start development server
npm run build             # Production build
npm run start             # Start production server
npm run preview           # Build and preview

# Code Quality
npm run lint              # Run Next.js linter
npm run lint:fix          # Fix linting issues
npm run check-types       # TypeScript checking
npm run format:write      # Format with Prettier

# Testing
npm run test             # Jest unit tests
npm run test:watch       # Watch mode
npm run test:coverage    # Coverage report

Development Tools

Bundle Analyzer:

ANALYZE=true npm run build

React Query DevTools:

• Automatically available in development
• Shows cache state, queries, and mutations
• Access via browser DevTools

Debug Configuration:

// Enable in development only
if (process.env.NODE_ENV === 'development') {
  import('@tanstack/react-query-devtools').then(({ ReactQueryDevtools }) => {
    // DevTools available
  });
}

Environment Management

# Environment files
.env.local          # Local development
.env.development    # Development environment
.env.production     # Production environment

Environment variables pattern:

# Database
DATABASE_URL="postgresql://..."

# Azure
AZURE_MAPS_CLIENT_ID="..."
AZURE_AD_CLIENT_ID="..."

# Next.js
NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET="..."

---

🔒 Security Best Practices

Content Security Policy

Our CSP configuration in next.config.js:

headers: [
  {
    key: "Content-Security-Policy",
    value: "default-src 'self' 'unsafe-inline' https: data:; script-src 'self' 'unsafe-inline' 'unsafe-eval' blob:; object-src 'none'; style-src 'self' 'unsafe-inline' data:; connect-src 'self' ws: wss: http: https:;"
  }
]

Authentication Patterns

// Server component authentication
export default async function ProtectedPage() {
  const session = await getSession();

  if (!session) {
    return redirect('/auth/login');
  }

  // Proceed with authenticated logic
}

// Client component authentication
export function useRequireAuth() {
  const { data: session, status } = useSession();
  const router = useRouter();

  useEffect(() => {
    if (status === 'loading') return; // Still loading

    if (!session) {
      router.push('/auth/login');
    }
  }, [session, status, router]);

  return session;
}

API Security

// API route protection
export async function GET(request: Request) {
  const session = await getServerSession(authOptions);

  if (!session) {
    return new Response('Unauthorized', { status: 401 });
  }

  // Proceed with logic
}

---

❌ Anti-patterns to Avoid

Understanding why these patterns are problematic helps make better architectural decisions. Here are the most critical anti-patterns with real-world impact analysis.

---

🚨 CRITICAL: Synchronous Heavy Imports

❌ THE PROBLEM:

// ❌ BAD - Synchronous import adds 3.6MB to initial bundle
import { io } from 'socket.io-client';
import 'azure-maps-control';
import { ReactFlowProvider } from 'reactflow';

export default function MyPage() {
  return <div>Page content</div>;
}

📊 REAL IMPACT FROM OUR CODEBASE:

• Before: Device Events page was 3.6MB (15+ second load time)
• After: Dynamic imports reduced it to 12KB (0.5 second load time)
• Performance gain: 99.7% reduction in bundle size

🔧 THE SOLUTION:

// ✅ GOOD - Dynamic import with loading state
const SocketComponent = dynamic(() => 
  import('./SocketComponent').then(mod => ({ default: mod.SocketComponent })), 
  { 
    ssr: false,
    loading: () => <div className="animate-pulse">Connecting...</div>
  }
);

const AzureMapComponent = dynamic(() => 
  import('./MapComponent'), 
  { 
    ssr: false,
    loading: () => <div className="h-64 bg-gray-200 animate-pulse">Loading map...</div>
  }
);

🔗 DOCUMENTATION:

• Next.js Dynamic Imports
• Bundle Analyzer Guide

---

📦 CRITICAL: Barrel Exports Causing Bundle Bloat

❌ THE PROBLEM:

// ❌ BAD - Imports entire @pxs/ui library even if you only need Button
import { Button, Input, Dialog, Table } from '@pxs/ui';

// This can add 500KB+ to your bundle even for simple components

📊 REAL IMPACT:

• Bundle bloat: Importing entire libraries when only using 1-2 components
• Tree shaking failure: Bundler can't eliminate unused code effectively
• Development slow-down: Slower builds and HMR (Hot Module Replacement)

🔧 THE SOLUTION:

// ✅ GOOD - Specific imports enable tree shaking
import { Button } from '@pxs/ui/button';
import { Input } from '@pxs/ui/input';
import { Dialog } from '@pxs/ui/dialog';

// OR use direct paths
import Button from '@pxs/ui/src/components/Button';

🔍 HOW TO DEBUG:

# Analyze what's actually being imported
ANALYZE=true npm run build
# Check the bundle analyzer for unexpected large chunks

🔗 DOCUMENTATION:

• Tree Shaking in Webpack
• ESM and Tree Shaking

---

🏗️ ARCHITECTURE: Heavy Components in Shared Layouts

❌ THE PROBLEM:

// ❌ BAD - Heavy component loads on EVERY page navigation
export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <Navigation />
        <ChatWidget />        {/* 500KB+ loads on every page */}
        <MapProvider />       {/* 1.6MB Azure Maps loads everywhere */}
        <AnalyticsProvider /> {/* Analytics tracking loads universally */}
        {children}
      </body>
    </html>
  );
}

📊 REAL IMPACT:

• Every page navigation: Users download heavy components they might not use
• Memory usage: Heavy components stay mounted across all routes
• Initial load time: First page takes longer due to unnecessary components

🔧 THE SOLUTION:

// ✅ GOOD - Layout only contains truly global elements
export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <Navigation />  {/* Lightweight, truly global */}
        {children}
      </body>
    </html>
  );
}

// ✅ GOOD - Heavy components loaded per route
export default function ChatPage() {
  return (
    <div>
      <PageContent />
      <Suspense fallback={<div>Loading chat...</div>}>
        <ChatWidget />
      </Suspense>
    </div>
  );
}

export default function MapPage() {
  return (
    <div>
      <Suspense fallback={<MapSkeleton />}>
        <MapProvider>
          <MapComponent />
        </MapProvider>
      </Suspense>
    </div>
  );
}

---

🎨 PERFORMANCE: CSS-in-JS for Repetitive Styling

❌ THE PROBLEM:

// ❌ BAD - Runtime style calculation on every render
const MyComponent = () => {
  const dynamicStyles = {
    padding: '16px',
    backgroundColor: isActive ? '#3b82f6' : '#6b7280',
    borderRadius: '8px',
    fontSize: '14px',
    fontWeight: 'bold',
  };

  return <div style={dynamicStyles}>Content</div>;
};

📊 REAL IMPACT:

• Runtime performance: Style calculations on every render
• Bundle size: CSS strings in JavaScript bundle
• Rehydration: Client-server style mismatches

🔧 THE SOLUTION:

// ✅ GOOD - Tailwind classes (compile-time optimized)
const MyComponent = () => {
  return (
    <div className={cn(
      "p-4 rounded-lg text-sm font-bold",
      isActive ? "bg-blue-500" : "bg-gray-500"
    )}>
      Content
    </div>
  );
};

// ✅ GOOD - CSS Variables for dynamic values
const MyComponent = () => {
  return (
    <div 
      className="dynamic-component"
      style={{ '--dynamic-color': backgroundColor } as React.CSSProperties}
    >
      Content
    </div>
  );
};

---

🔄 TANSTACK QUERY: Poor Query Management

❌ THE PROBLEM:

// ❌ BAD - No caching strategy, refetches constantly
const { data } = useQuery({
  queryKey: ['data'], // Too generic
  queryFn: fetchData,
  staleTime: 0,      // Always stale
  gcTime: 0,         // No caching
  refetchOnWindowFocus: true, // Excessive refetching
});

// ❌ BAD - Missing error handling
const { data } = useQuery({
  queryKey: ['users'],
  queryFn: () => api.getUsers(), // Can throw, not handled
});

// ❌ BAD - Not invalidating related queries after mutation
const mutation = useMutation({
  mutationFn: updateUser,
  // Missing onSuccess to update cache
});

📊 REAL IMPACT:

• Network overhead: Unnecessary API calls
• Poor UX: Loading states when data should be cached
• Stale data: Users see outdated information
• Server load: Excessive requests to backend

🔧 THE SOLUTION:

// ✅ GOOD - Strategic caching with proper invalidation
const { data, error, isLoading } = useQuery({
  queryKey: ['users', { filters, page }], // Specific, hierarchical keys
  queryFn: () => api.getUsers({ filters, page }),
  staleTime: 60 * 1000,        // 1 minute fresh
  gcTime: 5 * 60 * 1000,       // 5 minutes cached
  refetchOnWindowFocus: false, // Controlled refetching
  retry: (failureCount, error) => {
    if (error?.status === 404) return false;
    return failureCount < 2;
  },
});

// ✅ GOOD - Proper mutation with cache updates
const updateUserMutation = useMutation({
  mutationFn: updateUser,
  onSuccess: (updatedUser) => {
    queryClient.setQueryData(['users', updatedUser.id], updatedUser);
    queryClient.invalidateQueries({ queryKey: ['users'] });
  },
  onError: (error) => {
    toast({ title: "Error", content: error.message });
  },
});

🔗 DOCUMENTATION:

• TanStack Query Caching
• Query Invalidation

---

🔒 SECURITY: Client-Side Only Form Validation

❌ THE PROBLEM:

// ❌ BAD - Only client-side validation
const handleSubmit = (data) => {
  if (!data.email || !data.password) {
    setError("Fields required");
    return;
  }
  
  // Direct API call without server-side validation
  api.login(data); 
};

📊 REAL IMPACT:

• Security vulnerability: Easy to bypass with dev tools
• Data corruption: Invalid data reaches database
• Poor UX: Server errors without proper handling

🔧 THE SOLUTION:

// ✅ GOOD - Zod schema validation (client + server)
const loginSchema = z.object({
  email: z.string().email("Invalid email"),
  password: z.string().min(8, "Password too short"),
});

const form = useForm({
  resolver: zodResolver(loginSchema),
});

const handleSubmit = async (data) => {
  try {
    // Client-side validation already done by Zod
    const result = await api.login(data);
    // Server also validates with same schema
  } catch (error) {
    // Handle server validation errors
    if (error.validation) {
      Object.entries(error.validation).forEach(([field, message]) => {
        form.setError(field, { message });
      });
    }
  }
};

---

⚡ REACT HOOKS: Uncontrolled useEffect Dependencies

❌ THE PROBLEM:

// ❌ BAD - Missing dependencies cause stale closures
const [userId, setUserId] = useState('');
const [userData, setUserData] = useState(null);

useEffect(() => {
  fetchUserData(userId).then(setUserData); // userId could be stale
}, []); // Missing userId dependency

// ❌ BAD - Infinite loop potential
useEffect(() => {
  setData(processData(data));
}, [data]); // data changes trigger effect, which changes data

📊 REAL IMPACT:

• Stale closure bugs: Functions capture old values
• Infinite loops: Component re-renders constantly
• Memory leaks: Subscriptions not cleaned up properly
• Inconsistent state: Data gets out of sync

🔧 THE SOLUTION:

// ✅ GOOD - Correct dependencies
useEffect(() => {
  if (!userId) return;
  
  let cancelled = false;
  
  fetchUserData(userId).then(data => {
    if (!cancelled) {
      setUserData(data);
    }
  });
  
  return () => { cancelled = true; }; // Cleanup
}, [userId]); // Correct dependency

// ✅ GOOD - Stable reference to prevent loops
const processUserData = useCallback((rawData) => {
  return rawData.map(item => ({ ...item, processed: true }));
}, []); // No dependencies needed

useEffect(() => {
  setProcessedData(processUserData(rawData));
}, [rawData, processUserData]);

🔍 HOW TO DEBUG:

# Enable React strict mode to catch effects issues
# In next.config.js:
reactStrictMode: true

# Use ESLint plugin for hooks
npm install eslint-plugin-react-hooks

🔗 DOCUMENTATION:

• React useEffect Guide
• ESLint Plugin for Hooks

---

🚨 Real Impact Examples from Our Codebase

Success Story: Device Events Page Optimization

BEFORE (Anti-pattern):

// Synchronous imports caused massive bundle
import { io } from 'socket.io-client';
import { DeviceEventFactory } from './components';
// Result: 3.6MB initial bundle

AFTER (Best practice):

// Dynamic imports with proper loading states
const DeviceEventList = dynamic(() => import('./DeviceEventList'), {
  loading: () => <EventSkeleton />
});
// Result: 12KB initial bundle

📊 METRICS:

• Bundle size: 3.6MB → 12KB (-99.7%)
• Load time: 15 seconds → 0.5 seconds (-97%)
• User satisfaction: Dramatically improved

Success Story: react-world-flags Elimination

BEFORE (Anti-pattern):

import { Flag } from 'react-world-flags';
// Added 3.7MB to bundle for flag icons

AFTER (Best practice):

// Native emoji flags (0KB bundle cost)
const countryFlags = {
  'BE': '🇧🇪',
  'FR': '🇫🇷',
  'NL': '🇳🇱'
};

📊 METRICS:

• Bundle size: 3.7MB → 0KB (-100%)
• Dependency count: 120 → 116 (-4 packages)

---

🔧 How to Debug These Issues

Bundle Analysis Commands

# Generate detailed bundle analysis
ANALYZE=true npm run build

# View client-side bundle breakdown
open .next/analyze/client.html

# View server-side bundle breakdown  
open .next/analyze/server.html

# Check for specific heavy packages
npm ls --depth=0 --package-lock-only

Performance Monitoring

// Add performance monitoring to your app
import { getCLS, getFID, getFCP, getLCP, getTTFB } from 'web-vitals';

function sendToAnalytics(metric) {
  console.log('Web Vital:', metric);
  // Send to your analytics service
}

getCLS(sendToAnalytics);
getFID(sendToAnalytics);  
getFCP(sendToAnalytics);
getLCP(sendToAnalytics);
getTTFB(sendToAnalytics);

Runtime Performance Debugging

// React DevTools Profiler integration
if (process.env.NODE_ENV === 'development') {
  import('react-dom').then(ReactDOM => {
    // Enable profiler in dev mode
    ReactDOM.unstable_trace('page-load', performance.now(), () => {
      // Your component rendering
    });
  });
}

---

🏥 Migration Strategies

Fixing Synchronous Imports

Step 1: Identify heavy imports

ANALYZE=true npm run build
# Look for chunks > 500KB in the analyzer

Step 2: Convert to dynamic imports

// Replace synchronous import
const HeavyComponent = dynamic(() => import('./Heavy'), {
  loading: () => <Skeleton />
});

Step 3: Measure improvement

ANALYZE=true npm run build
# Compare before/after bundle sizes

Fixing TanStack Query Issues

Step 1: Audit existing queries

// Add debugging to see query behavior
const queryClient = new QueryClient({
  logger: {
    log: console.log,
    warn: console.warn,
    error: console.error,
  },
});

Step 2: Implement proper caching

// Replace poorly cached queries
const { data } = useQuery({
  queryKey: ['users', filters], // Specific keys
  staleTime: 60 * 1000,        // Add appropriate stale time
  gcTime: 5 * 60 * 1000,       // Add garbage collection time
});

Step 3: Monitor query performance

// Enable React Query DevTools
import { ReactQueryDevtools } from '@tanstack/react-query-devtools';

// In your app
<ReactQueryDevtools initialIsOpen={false} />

Remember: Always measure before and after when fixing anti-patterns. Use the tools provided to validate your optimizations! 📊

---

📚 Quick Reference

Performance Checklist

• Use dynamic() for components > 50KB
• Implement loading states with Suspense
• Lazy load third-party libraries (maps, charts)
• Run ANALYZE=true npm run build before releases
• Prefer specific imports over barrel exports
• Use conditional rendering for heavy components

Code Quality Checklist

• Run npm run check-types before commits
• Use React Hook Form + Zod for forms
• Implement proper error boundaries
• Follow consistent naming conventions
• Write unit tests for custom hooks
• Use TypeScript strict mode

TanStack Query Checklist

• Configure appropriate staleTime and gcTime
• Use optimistic updates for mutations
• Implement proper error handling
• Invalidate related queries after mutations
• Use query keys consistently
• Enable React Query DevTools in development

Security Checklist

• Validate all forms with Zod schemas
• Protect API routes with authentication
• Use environment variables for secrets
• Implement proper CSP headers
• Sanitize user inputs
• Use HTTPS in production

---

🔗 Resources

Documentation

• Next.js App Router
• TanStack Query
• React Hook Form
• Radix UI
• Tailwind CSS

---

📞 Support & Feedback

For questions about these guidelines or suggestions for improvements:

1. Code Reviews: Discuss during PR reviews
2. Team Meetings: Bring up in sprint planning
3. Documentation Updates: Submit PRs for guideline improvements
4. Architecture Decisions: Discuss with the team

---

🔄 Last Updated: August 2025
📝 Version: 1.0
👥 Maintainers: Iot DE team

Remember: These guidelines evolve with our codebase. When you discover better patterns or encounter edge cases, update this document and share with the team! 🚀