🏗️ Lesson 8.5: Architecture Best Practices

🎯 Principles of Good Architecture

Before diving into specific patterns, let's understand the fundamental principles that guide architectural decisions in React applications. These principles apply regardless of project size or specific technologies used.

The Core Principles

1. Separation of Concerns

Each part of your application should have a single, well-defined responsibility. When components, hooks, and utilities each focus on one thing, they become easier to understand, test, and reuse.

// ❌ BAD - Component doing too much
function UserProfile() {
  const [user, setUser] = useState(null);
  const [loading, setLoading] = useState(true);
  
  useEffect(() => {
    fetch('/api/user')
      .then(res => res.json())
      .then(data => {
        setUser(data);
        setLoading(false);
      });
  }, []);
  
  const saveUser = (data) => {
    fetch('/api/user', {
      method: 'PUT',
      body: JSON.stringify(data)
    }).then(/* ... */);
  };
  
  return (
    <div>
      {loading ? <Spinner /> : (
        <form onSubmit={/* validation logic */}>
          {/* lots of form fields and UI logic */}
        </form>
      )}
    </div>
  );
}

// ✅ GOOD - Separated concerns
function UserProfile() {
  const { user, isLoading } = useUser();
  
  return (
    <div>
      {isLoading ? <Spinner /> : <UserForm user={user} />}
    </div>
  );
}

// Custom hook handles data fetching
function useUser() {
  return useQuery({
    queryKey: ['user'],
    queryFn: userService.getProfile
  });
}

// Service handles API calls
const userService = {
  getProfile: () => fetch('/api/user').then(r => r.json()),
  updateProfile: (data) => fetch('/api/user', { 
    method: 'PUT', 
    body: JSON.stringify(data) 
  })
};

// Component handles only UI and user interactions
function UserForm({ user }: { user: User }) {
  const updateMutation = useUpdateUser();
  // Form logic...
}

2. DRY (Don't Repeat Yourself)

Duplicated code multiplies maintenance work and increases the chance of bugs. Extract common logic into reusable functions, hooks, and components.

// ❌ BAD - Repeated logic
function UsersList() {
  const [users, setUsers] = useState([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);
  
  useEffect(() => {
    setLoading(true);
    fetch('/api/users')
      .then(res => res.json())
      .then(data => {
        setUsers(data);
        setLoading(false);
      })
      .catch(err => {
        setError(err);
        setLoading(false);
      });
  }, []);
  
  // ... component JSX
}

function PostsList() {
  const [posts, setPosts] = useState([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);
  
  useEffect(() => {
    setLoading(true);
    fetch('/api/posts')
      .then(res => res.json())
      .then(data => {
        setPosts(data);
        setLoading(false);
      })
      .catch(err => {
        setError(err);
        setLoading(false);
      });
  }, []);
  
  // ... component JSX
}

// ✅ GOOD - Reusable hook
function useFetch<T>(url: string) {
  const [data, setData] = useState<T | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<Error | null>(null);
  
  useEffect(() => {
    let cancelled = false;
    
    setLoading(true);
    fetch(url)
      .then(res => res.json())
      .then(data => {
        if (!cancelled) {
          setData(data);
          setLoading(false);
        }
      })
      .catch(err => {
        if (!cancelled) {
          setError(err);
          setLoading(false);
        }
      });
    
    return () => { cancelled = true; };
  }, [url]);
  
  return { data, loading, error };
}

// Now both components are simple
function UsersList() {
  const { data: users, loading, error } = useFetch<User[]>('/api/users');
  // ... component JSX
}

function PostsList() {
  const { data: posts, loading, error } = useFetch<Post[]>('/api/posts');
  // ... component JSX
}

3. KISS (Keep It Simple, Stupid)

Simple solutions are easier to understand, test, and maintain. Avoid over-engineering and premature optimization.

4. Single Responsibility Principle

Each component, function, or module should have one reason to change. This makes code predictable and reduces the ripple effect of modifications.

// ❌ BAD - Component has multiple responsibilities
function UserDashboard() {
  return (
    <div>
      {/* Analytics tracking logic */}
      {/* User data fetching */}
      {/* Navigation rendering */}
      {/* User profile display */}
      {/* Settings management */}
      {/* Notifications handling */}
    </div>
  );
}

// ✅ GOOD - Each component has one responsibility
function UserDashboard() {
  useAnalytics('dashboard-view');
  const { user } = useUser();
  
  return (
    <DashboardLayout>
      <UserHeader user={user} />
      <UserStats userId={user.id} />
      <RecentActivity userId={user.id} />
      <QuickActions />
    </DashboardLayout>
  );
}

5. Composition Over Inheritance

React's component model encourages composition. Build complex UIs by combining simple, focused components rather than creating deep inheritance hierarchies.

// ✅ GOOD - Composition pattern
function Card({ children }: { children: React.ReactNode }) {
  return <div className="card">{children}</div>;
}

function CardHeader({ children }: { children: React.ReactNode }) {
  return <div className="card-header">{children}</div>;
}

function CardBody({ children }: { children: React.ReactNode }) {
  return <div className="card-body">{children}</div>;
}

// Compose them together
function UserCard({ user }: { user: User }) {
  return (
    <Card>
      <CardHeader>
        <h2>{user.name}</h2>
      </CardHeader>
      <CardBody>
        <p>{user.bio}</p>
      </CardBody>
    </Card>
  );
}

Architecture Anti-Patterns to Avoid

📁 Feature-Based Folder Structure

As applications grow, organizing files by type (all components together, all hooks together) becomes unwieldy. A feature-based structure groups related files together, making it easier to understand and modify features as complete units.

Traditional vs Feature-Based Structure

src/
├── components/
│   ├── UserList.tsx
│   ├── UserCard.tsx
│   ├── UserForm.tsx
│   ├── PostList.tsx
│   ├── PostCard.tsx
│   ├── PostForm.tsx
│   ├── CommentList.tsx
│   └── ...50+ more
├── hooks/
│   ├── useUsers.ts
│   ├── usePosts.ts
│   ├── useComments.ts
│   └── ...30+ more
├── services/
│   ├── userService.ts
│   ├── postService.ts
│   └── ...20+ more
└── types/
    ├── user.ts
    ├── post.ts
    └── ...20+ more

src/
├── features/
│   ├── users/
│   │   ├── components/
│   │   │   ├── UserList.tsx
│   │   │   ├── UserCard.tsx
│   │   │   └── UserForm.tsx
│   │   ├── hooks/
│   │   │   └── useUsers.ts
│   │   ├── api/
│   │   │   └── userService.ts
│   │   ├── types/
│   │   │   └── user.ts
│   │   └── index.ts
│   ├── posts/
│   │   ├── components/
│   │   ├── hooks/
│   │   ├── api/
│   │   └── types/
│   └── comments/
│       └── ...
└── shared/
    ├── components/
    ├── hooks/
    └── utils/

Complete Feature-Based Architecture

src/
├── features/                    # Feature modules
│   ├── auth/                   # Authentication feature
│   │   ├── components/
│   │   │   ├── LoginForm.tsx
│   │   │   ├── RegisterForm.tsx
│   │   │   └── ProtectedRoute.tsx
│   │   ├── hooks/
│   │   │   ├── useAuth.ts
│   │   │   └── useLogin.ts
│   │   ├── api/
│   │   │   └── authService.ts
│   │   ├── store/             # Feature-specific state
│   │   │   └── authStore.ts
│   │   ├── types/
│   │   │   └── auth.types.ts
│   │   ├── utils/
│   │   │   └── tokenManager.ts
│   │   └── index.ts           # Public API
│   │
│   ├── users/                 # Users feature
│   │   ├── components/
│   │   │   ├── UserList/
│   │   │   │   ├── UserList.tsx
│   │   │   │   ├── UserList.test.tsx
│   │   │   │   └── UserList.module.css
│   │   │   ├── UserCard/
│   │   │   └── UserProfile/
│   │   ├── hooks/
│   │   │   ├── useUsers.ts
│   │   │   ├── useUser.ts
│   │   │   └── useUpdateUser.ts
│   │   ├── api/
│   │   │   └── userService.ts
│   │   ├── types/
│   │   │   └── user.types.ts
│   │   └── index.ts
│   │
│   ├── posts/
│   ├── comments/
│   └── dashboard/
│
├── shared/                     # Shared across features
│   ├── components/            # Reusable UI components
│   │   ├── Button/
│   │   ├── Input/
│   │   ├── Card/
│   │   └── Modal/
│   ├── hooks/                 # Reusable hooks
│   │   ├── useLocalStorage.ts
│   │   ├── useDebounce.ts
│   │   └── useMediaQuery.ts
│   ├── utils/                 # Utility functions
│   │   ├── formatters.ts
│   │   ├── validators.ts
│   │   └── helpers.ts
│   ├── types/                 # Shared types
│   │   └── common.types.ts
│   └── constants/
│       └── config.ts
│
├── lib/                       # Third-party setup
│   ├── react-query.ts        # React Query config
│   ├── axios.ts              # Axios instance
│   └── i18n.ts               # Internationalization
│
├── pages/                     # Route components (or routes/)
│   ├── HomePage.tsx
│   ├── UsersPage.tsx
│   ├── UserDetailPage.tsx
│   └── NotFoundPage.tsx
│
├── layouts/                   # Layout components
│   ├── MainLayout.tsx
│   ├── AuthLayout.tsx
│   └── DashboardLayout.tsx
│
├── styles/                    # Global styles
│   ├── globals.css
│   ├── variables.css
│   └── theme.css
│
├── App.tsx                    # Root component
├── main.tsx                   # Entry point
└── vite-env.d.ts             # Vite types

Feature Module Example

// features/users/index.ts - Public API
export { UserList } from './components/UserList';
export { UserCard } from './components/UserCard';
export { useUsers, useUser } from './hooks';
export type { User, UserFilters } from './types/user.types';

// Other files import from the feature
import { UserList, useUsers, User } from '@/features/users';

// NOT from internal paths
// ❌ DON'T: import { UserList } from '@/features/users/components/UserList';

Shared vs Feature-Specific

Deciding what goes in shared/ vs features/:

🧩 Component Organization Patterns

Not all components are created equal. Understanding different component types and their roles helps you organize them effectively and make better architectural decisions.

The Component Hierarchy

1. Page Components (Route Components)

Top-level components that correspond to routes. They orchestrate feature components and manage page-level concerns.

// pages/UsersPage.tsx
import { UserList } from '@/features/users';
import { PageHeader } from '@/shared/components';
import { MainLayout } from '@/layouts';

export function UsersPage() {
  return (
    <MainLayout>
      <PageHeader 
        title="Users" 
        description="Manage all users in your application"
      />
      <UserList />
    </MainLayout>
  );
}

// Characteristics:
// - Maps to a route
// - Minimal logic (mostly composition)
// - Uses layouts and features
// - Handles page-level data fetching
// - Sets page metadata (title, etc.)

2. Container Components (Smart Components)

Manage state, data fetching, and business logic. They connect to stores, hooks, and APIs, then pass data down to presentational components.

// features/users/components/UserList/UserListContainer.tsx
import { useUsers } from '../../hooks/useUsers';
import { UserListView } from './UserListView';

export function UserListContainer() {
  const { 
    users, 
    isLoading, 
    error, 
    refetch 
  } = useUsers();
  
  const [filters, setFilters] = useState<UserFilters>({});
  
  const handleFilterChange = (newFilters: UserFilters) => {
    setFilters(newFilters);
  };
  
  const filteredUsers = useMemo(() => {
    return users?.filter(user => {
      // Filtering logic
      return true;
    });
  }, [users, filters]);
  
  if (isLoading) return <LoadingSpinner />;
  if (error) return <ErrorMessage error={error} onRetry={refetch} />;
  
  return (
    <UserListView
      users={filteredUsers}
      filters={filters}
      onFilterChange={handleFilterChange}
    />
  );
}

// Characteristics:
// - Manages state and side effects
// - Connects to data sources
// - Contains business logic
// - Handles loading and error states
// - Passes data to presentational components

3. Presentational Components (Dumb Components)

Focus purely on rendering UI. They receive data through props and notify parents of user interactions through callback props.

// features/users/components/UserList/UserListView.tsx
interface UserListViewProps {
  users: User[];
  filters: UserFilters;
  onFilterChange: (filters: UserFilters) => void;
}

export function UserListView({ 
  users, 
  filters, 
  onFilterChange 
}: UserListViewProps) {
  return (
    <div className="user-list">
      <UserFilters 
        filters={filters} 
        onChange={onFilterChange} 
      />
      
      <div className="user-grid">
        {users.map(user => (
          <UserCard key={user.id} user={user} />
        ))}
      </div>
    </div>
  );
}

// Characteristics:
// - Pure presentation logic
// - No state or side effects
// - Easy to test
// - Reusable with different data
// - Can be used in Storybook

4. UI Components (Shared Components)

Generic, reusable components that have no knowledge of business logic. These live in the shared/components/ folder and can be used across features.

// shared/components/Button/Button.tsx
interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: 'primary' | 'secondary' | 'danger';
  size?: 'small' | 'medium' | 'large';
  loading?: boolean;
  children: React.ReactNode;
}

export function Button({
  variant = 'primary',
  size = 'medium',
  loading = false,
  disabled,
  children,
  className = '',
  ...props
}: ButtonProps) {
  const baseClasses = 'btn';
  const variantClass = `btn-${variant}`;
  const sizeClass = `btn-${size}`;
  
  return (
    <button
      className={`${baseClasses} ${variantClass} ${sizeClass} ${className}`}
      disabled={disabled || loading}
      {...props}
    >
      {loading ? <Spinner size="small" /> : children}
    </button>
  );
}

// Characteristics:
// - Generic and reusable
// - No business logic
// - Highly configurable through props
// - Can be documented in Storybook
// - Could be published as a library

🔀 Separation of Concerns

Separation of concerns is about organizing code so that each piece has a clear, focused responsibility. In React applications, this means separating presentation, business logic, and data fetching into distinct layers.

The Three Layers

1. Presentation Layer (Components)

Handles only rendering and user interactions. No business logic or data fetching.

// ✅ GOOD - Pure presentation
function ProductCard({ product, onAddToCart }: ProductCardProps) {
  return (
    <Card>
      <img src={product.image} alt={product.name} />
      <h3>{product.name}</h3>
      <p>${product.price.toFixed(2)}</p>
      <Button onClick={() => onAddToCart(product.id)}>
        Add to Cart
      </Button>
    </Card>
  );
}

// ❌ BAD - Mixed concerns
function ProductCard({ productId }: { productId: string }) {
  const [product, setProduct] = useState(null);
  const [cart, setCart] = useState([]);
  
  useEffect(() => {
    // Data fetching in component
    fetch(`/api/products/${productId}`)
      .then(res => res.json())
      .then(setProduct);
  }, [productId]);
  
  const addToCart = () => {
    // Business logic in component
    if (cart.length >= 10) {
      alert('Cart is full!');
      return;
    }
    
    const tax = product.price * 0.08;
    const total = product.price + tax;
    
    setCart([...cart, { ...product, total }]);
    
    // Data mutation in component
    fetch('/api/cart', {
      method: 'POST',
      body: JSON.stringify({ productId })
    });
  };
  
  return (/* ... */);
}

2. Business Logic Layer (Custom Hooks)

Encapsulates business rules, calculations, and state management logic.

// hooks/useCart.ts
export function useCart() {
  const [cart, setCart] = useState<CartItem[]>([]);
  
  const addToCart = useCallback((product: Product) => {
    // Business rule: Max 10 items
    if (cart.length >= 10) {
      throw new Error('Cart is full. Maximum 10 items allowed.');
    }
    
    // Business logic: Calculate totals
    const tax = calculateTax(product.price);
    const total = product.price + tax;
    
    const cartItem: CartItem = {
      ...product,
      tax,
      total,
      addedAt: new Date()
    };
    
    setCart(prev => [...prev, cartItem]);
    return cartItem;
  }, [cart.length]);
  
  const removeFromCart = useCallback((itemId: string) => {
    setCart(prev => prev.filter(item => item.id !== itemId));
  }, []);
  
  const cartTotal = useMemo(() => {
    return cart.reduce((sum, item) => sum + item.total, 0);
  }, [cart]);
  
  const itemCount = cart.length;
  const isFull = itemCount >= 10;
  
  return {
    cart,
    cartTotal,
    itemCount,
    isFull,
    addToCart,
    removeFromCart
  };
}

// Utility function for business logic
function calculateTax(price: number): number {
  const TAX_RATE = 0.08;
  return price * TAX_RATE;
}

3. Data Access Layer (Services)

Handles all communication with external systems (APIs, localStorage, etc.).

// services/cartService.ts
import { apiClient } from '@/lib/axios';

export const cartService = {
  async getCart(userId: string): Promise<CartItem[]> {
    const response = await apiClient.get(`/users/${userId}/cart`);
    return response.data;
  },
  
  async addToCart(userId: string, productId: string): Promise<CartItem> {
    const response = await apiClient.post(`/users/${userId}/cart`, {
      productId
    });
    return response.data;
  },
  
  async removeFromCart(userId: string, itemId: string): Promise<void> {
    await apiClient.delete(`/users/${userId}/cart/${itemId}`);
  },
  
  async clearCart(userId: string): Promise<void> {
    await apiClient.delete(`/users/${userId}/cart`);
  }
};

Putting It All Together

// Component uses hook (business logic)
function ProductPage({ productId }: { productId: string }) {
  const { product } = useProduct(productId);
  const { addToCart, isFull } = useCart();
  
  const handleAddToCart = async () => {
    try {
      await addToCart(product);
      toast.success('Added to cart!');
    } catch (error) {
      toast.error(error.message);
    }
  };
  
  return (
    <ProductCard
      product={product}
      onAddToCart={handleAddToCart}
      disabled={isFull}
    />
  );
}

// Hook uses service (data access)
function useCart() {
  const { user } = useAuth();
  const queryClient = useQueryClient();
  
  const { data: cart = [] } = useQuery({
    queryKey: ['cart', user?.id],
    queryFn: () => cartService.getCart(user!.id),
    enabled: !!user
  });
  
  const addMutation = useMutation({
    mutationFn: (product: Product) => {
      // Business logic first
      if (cart.length >= 10) {
        throw new Error('Cart is full');
      }
      
      // Then data access
      return cartService.addToCart(user!.id, product.id);
    },
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['cart'] });
    }
  });
  
  const addToCart = async (product: Product) => {
    return addMutation.mutateAsync(product);
  };
  
  return {
    cart,
    addToCart,
    isFull: cart.length >= 10
  };
}

// Service handles API calls
const cartService = {
  async addToCart(userId: string, productId: string) {
    const response = await apiClient.post(`/users/${userId}/cart`, {
      productId
    });
    return response.data;
  }
};

🪝 Custom Hooks for Business Logic

Custom hooks are the perfect place to encapsulate business logic in React applications. They keep components clean and focused on rendering while making logic reusable and testable.

When to Create a Custom Hook

Hook Patterns and Examples

1. Data Fetching Hooks

// hooks/useUser.ts
export function useUser(userId: string) {
  return useQuery({
    queryKey: ['users', userId],
    queryFn: () => userService.getById(userId),
    staleTime: 1000 * 60 * 5
  });
}

// Usage
function UserProfile({ userId }: { userId: string }) {
  const { data: user, isLoading, error } = useUser(userId);
  
  if (isLoading) return <Spinner />;
  if (error) return <ErrorMessage error={error} />;
  
  return <div>{user.name}</div>;
}

2. Form Handling Hooks

// hooks/useForm.ts
interface UseFormOptions<T> {
  initialValues: T;
  onSubmit: (values: T) => void | Promise<void>;
  validate?: (values: T) => Record<string, string>;
}

export function useForm<T extends Record<string, any>>({
  initialValues,
  onSubmit,
  validate
}: UseFormOptions<T>) {
  const [values, setValues] = useState<T>(initialValues);
  const [errors, setErrors] = useState<Record<string, string>>({});
  const [isSubmitting, setIsSubmitting] = useState(false);
  
  const handleChange = (name: keyof T, value: any) => {
    setValues(prev => ({ ...prev, [name]: value }));
    // Clear error when user starts typing
    if (errors[name as string]) {
      setErrors(prev => {
        const newErrors = { ...prev };
        delete newErrors[name as string];
        return newErrors;
      });
    }
  };
  
  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    
    // Validate
    if (validate) {
      const validationErrors = validate(values);
      if (Object.keys(validationErrors).length > 0) {
        setErrors(validationErrors);
        return;
      }
    }
    
    // Submit
    setIsSubmitting(true);
    try {
      await onSubmit(values);
      setValues(initialValues); // Reset form
    } catch (error) {
      setErrors({ submit: error.message });
    } finally {
      setIsSubmitting(false);
    }
  };
  
  const reset = () => {
    setValues(initialValues);
    setErrors({});
  };
  
  return {
    values,
    errors,
    isSubmitting,
    handleChange,
    handleSubmit,
    reset
  };
}

// Usage
function LoginForm() {
  const { values, errors, handleChange, handleSubmit, isSubmitting } = useForm({
    initialValues: { email: '', password: '' },
    onSubmit: async (values) => {
      await authService.login(values);
    },
    validate: (values) => {
      const errors: Record<string, string> = {};
      if (!values.email) errors.email = 'Email is required';
      if (!values.password) errors.password = 'Password is required';
      return errors;
    }
  });
  
  return (
    <form onSubmit={handleSubmit}>
      <Input
        value={values.email}
        onChange={(e) => handleChange('email', e.target.value)}
        error={errors.email}
      />
      <Button type="submit" loading={isSubmitting}>
        Login
      </Button>
    </form>
  );
}

3. Business Logic Hooks

// hooks/useShoppingCart.ts
export function useShoppingCart() {
  const [items, setItems] = useState<CartItem[]>([]);
  
  const addItem = useCallback((product: Product, quantity = 1) => {
    setItems(prev => {
      const existing = prev.find(item => item.product.id === product.id);
      
      if (existing) {
        // Update quantity if item exists
        return prev.map(item =>
          item.product.id === product.id
            ? { ...item, quantity: item.quantity + quantity }
            : item
        );
      }
      
      // Add new item
      return [...prev, { product, quantity }];
    });
  }, []);
  
  const removeItem = useCallback((productId: string) => {
    setItems(prev => prev.filter(item => item.product.id !== productId));
  }, []);
  
  const updateQuantity = useCallback((productId: string, quantity: number) => {
    if (quantity <= 0) {
      removeItem(productId);
      return;
    }
    
    setItems(prev =>
      prev.map(item =>
        item.product.id === productId
          ? { ...item, quantity }
          : item
      )
    );
  }, [removeItem]);
  
  const clearCart = useCallback(() => {
    setItems([]);
  }, []);
  
  // Computed values
  const subtotal = useMemo(() => {
    return items.reduce((sum, item) => {
      return sum + (item.product.price * item.quantity);
    }, 0);
  }, [items]);
  
  const tax = useMemo(() => subtotal * 0.08, [subtotal]);
  const total = subtotal + tax;
  const itemCount = items.reduce((sum, item) => sum + item.quantity, 0);
  
  return {
    items,
    itemCount,
    subtotal,
    tax,
    total,
    addItem,
    removeItem,
    updateQuantity,
    clearCart
  };
}

4. Utility Hooks

// hooks/useDebounce.ts
export function useDebounce<T>(value: T, delay: number): T {
  const [debouncedValue, setDebouncedValue] = useState<T>(value);
  
  useEffect(() => {
    const handler = setTimeout(() => {
      setDebouncedValue(value);
    }, delay);
    
    return () => clearTimeout(handler);
  }, [value, delay]);
  
  return debouncedValue;
}

// hooks/useLocalStorage.ts
export function useLocalStorage<T>(key: string, initialValue: T) {
  const [storedValue, setStoredValue] = useState<T>(() => {
    try {
      const item = window.localStorage.getItem(key);
      return item ? JSON.parse(item) : initialValue;
    } catch (error) {
      console.error(error);
      return initialValue;
    }
  });
  
  const setValue = (value: T | ((val: T) => T)) => {
    try {
      const valueToStore = value instanceof Function ? value(storedValue) : value;
      setStoredValue(valueToStore);
      window.localStorage.setItem(key, JSON.stringify(valueToStore));
    } catch (error) {
      console.error(error);
    }
  };
  
  return [storedValue, setValue] as const;
}

// hooks/useMediaQuery.ts
export function useMediaQuery(query: string): boolean {
  const [matches, setMatches] = useState(() => {
    return window.matchMedia(query).matches;
  });
  
  useEffect(() => {
    const mediaQuery = window.matchMedia(query);
    
    const handleChange = (e: MediaQueryListEvent) => {
      setMatches(e.matches);
    };
    
    mediaQuery.addEventListener('change', handleChange);
    return () => mediaQuery.removeEventListener('change', handleChange);
  }, [query]);
  
  return matches;
}

// Usage
function SearchBar() {
  const [search, setSearch] = useState('');
  const debouncedSearch = useDebounce(search, 500);
  const [theme, setTheme] = useLocalStorage('theme', 'light');
  const isMobile = useMediaQuery('(max-width: 768px)');
  
  // Use debouncedSearch for API calls
  const { data } = useQuery({
    queryKey: ['search', debouncedSearch],
    queryFn: () => searchApi(debouncedSearch),
    enabled: debouncedSearch.length > 0
  });
  
  return (/* ... */);
}

🔌 Service Layer Pattern

The service layer is a dedicated abstraction for all external communication. It centralizes API calls, error handling, and data transformation, making your application easier to maintain and test.

Why Use a Service Layer?

Service Structure

// lib/axios.ts - Configure axios instance
import axios from 'axios';

export const apiClient = axios.create({
  baseURL: import.meta.env.VITE_API_URL,
  timeout: 10000,
  headers: {
    'Content-Type': 'application/json'
  }
});

// Request interceptor - Add auth token
apiClient.interceptors.request.use(
  (config) => {
    const token = localStorage.getItem('authToken');
    if (token) {
      config.headers.Authorization = `Bearer ${token}`;
    }
    return config;
  },
  (error) => Promise.reject(error)
);

// Response interceptor - Handle errors
apiClient.interceptors.response.use(
  (response) => response,
  (error) => {
    if (error.response?.status === 401) {
      // Redirect to login
      window.location.href = '/login';
    }
    return Promise.reject(error);
  }
);

Creating Services

// services/userService.ts
import { apiClient } from '@/lib/axios';
import type { User, CreateUserDto, UpdateUserDto } from '@/types';

export const userService = {
  /**
   * Get all users
   */
  async getAll(): Promise<User[]> {
    const response = await apiClient.get<User[]>('/users');
    return response.data;
  },

  /**
   * Get user by ID
   */
  async getById(id: string): Promise<User> {
    const response = await apiClient.get<User>(`/users/${id}`);
    return response.data;
  },

  /**
   * Create new user
   */
  async create(data: CreateUserDto): Promise<User> {
    const response = await apiClient.post<User>('/users', data);
    return response.data;
  },

  /**
   * Update existing user
   */
  async update(id: string, data: UpdateUserDto): Promise<User> {
    const response = await apiClient.patch<User>(`/users/${id}`, data);
    return response.data;
  },

  /**
   * Delete user
   */
  async delete(id: string): Promise<void> {
    await apiClient.delete(`/users/${id}`);
  },

  /**
   * Search users by query
   */
  async search(query: string): Promise<User[]> {
    const response = await apiClient.get<User[]>('/users/search', {
      params: { q: query }
    });
    return response.data;
  }
};

Advanced Service Patterns

// services/baseService.ts - Generic base service
export class BaseService<T> {
  constructor(private endpoint: string) {}

  async getAll(): Promise<T[]> {
    const response = await apiClient.get<T[]>(this.endpoint);
    return response.data;
  }

  async getById(id: string): Promise<T> {
    const response = await apiClient.get<T>(`${this.endpoint}/${id}`);
    return response.data;
  }

  async create(data: Partial<T>): Promise<T> {
    const response = await apiClient.post<T>(this.endpoint, data);
    return response.data;
  }

  async update(id: string, data: Partial<T>): Promise<T> {
    const response = await apiClient.patch<T>(`${this.endpoint}/${id}`, data);
    return response.data;
  }

  async delete(id: string): Promise<void> {
    await apiClient.delete(`${this.endpoint}/${id}`);
  }
}

// services/userService.ts - Extend base service
class UserService extends BaseService<User> {
  constructor() {
    super('/users');
  }

  // Add user-specific methods
  async getProfile(): Promise<User> {
    const response = await apiClient.get<User>('/users/profile');
    return response.data;
  }

  async updateProfile(data: UpdateProfileDto): Promise<User> {
    const response = await apiClient.patch<User>('/users/profile', data);
    return response.data;
  }

  async changePassword(data: ChangePasswordDto): Promise<void> {
    await apiClient.post('/users/change-password', data);
  }
}

export const userService = new UserService();

Service with React Query

// hooks/useUsers.ts
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
import { userService } from '@/services/userService';

export const userKeys = {
  all: ['users'] as const,
  lists: () => [...userKeys.all, 'list'] as const,
  list: (filters: string) => [...userKeys.lists(), { filters }] as const,
  details: () => [...userKeys.all, 'detail'] as const,
  detail: (id: string) => [...userKeys.details(), id] as const,
};

export function useUsers() {
  return useQuery({
    queryKey: userKeys.lists(),
    queryFn: userService.getAll
  });
}

export function useUser(id: string) {
  return useQuery({
    queryKey: userKeys.detail(id),
    queryFn: () => userService.getById(id)
  });
}

export function useCreateUser() {
  const queryClient = useQueryClient();
  
  return useMutation({
    mutationFn: userService.create,
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: userKeys.lists() });
    }
  });
}

export function useUpdateUser() {
  const queryClient = useQueryClient();
  
  return useMutation({
    mutationFn: ({ id, data }: { id: string; data: UpdateUserDto }) =>
      userService.update(id, data),
    onSuccess: (_, variables) => {
      queryClient.invalidateQueries({ queryKey: userKeys.detail(variables.id) });
      queryClient.invalidateQueries({ queryKey: userKeys.lists() });
    }
  });
}

📐 Type Organization

Proper TypeScript type organization makes your codebase more maintainable and helps developers understand data structures quickly.

Type Organization Strategies

1. Feature-Based Types

// features/users/types/user.types.ts
export interface User {
  id: string;
  email: string;
  name: string;
  avatar?: string;
  createdAt: string;
  updatedAt: string;
}

export interface CreateUserDto {
  email: string;
  name: string;
  password: string;
}

export interface UpdateUserDto {
  name?: string;
  avatar?: string;
}

export interface UserFilters {
  search?: string;
  role?: UserRole;
  status?: UserStatus;
}

export type UserRole = 'admin' | 'user' | 'moderator';
export type UserStatus = 'active' | 'inactive' | 'suspended';

2. Shared/Common Types

// shared/types/common.types.ts
export interface ApiResponse<T> {
  data: T;
  message?: string;
  success: boolean;
}

export interface PaginatedResponse<T> {
  data: T[];
  total: number;
  page: number;
  pageSize: number;
  hasMore: boolean;
}

export interface ApiError {
  message: string;
  code: string;
  statusCode: number;
  details?: Record<string, any>;
}

export type Nullable<T> = T | null;
export type Optional<T> = T | undefined;
export type ID = string | number;

3. Utility Types

// shared/types/utils.types.ts

// Make all properties optional recursively
export type DeepPartial<T> = {
  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
};

// Make all properties required recursively
export type DeepRequired<T> = {
  [P in keyof T]-?: T[P] extends object ? DeepRequired<T[P]> : T[P];
};

// Extract keys of type
export type KeysOfType<T, U> = {
  [K in keyof T]: T[K] extends U ? K : never;
}[keyof T];

// Async function return type
export type AsyncReturnType<T extends (...args: any) => Promise<any>> =
  T extends (...args: any) => Promise<infer R> ? R : any;

🚨 Error Handling Architecture

Consistent, well-architected error handling improves user experience and makes debugging easier. A good error handling strategy catches errors at the right level and provides meaningful feedback.

Error Handling Layers

1. Custom Error Classes

// shared/errors/AppError.ts
export class AppError extends Error {
  constructor(
    message: string,
    public code: string,
    public statusCode: number,
    public details?: any
  ) {
    super(message);
    this.name = 'AppError';
  }
}

export class ValidationError extends AppError {
  constructor(message: string, details?: Record<string, string>) {
    super(message, 'VALIDATION_ERROR', 400, details);
    this.name = 'ValidationError';
  }
}

export class AuthenticationError extends AppError {
  constructor(message = 'Authentication required') {
    super(message, 'AUTH_ERROR', 401);
    this.name = 'AuthenticationError';
  }
}

export class AuthorizationError extends AppError {
  constructor(message = 'Insufficient permissions') {
    super(message, 'AUTHORIZATION_ERROR', 403);
    this.name = 'AuthorizationError';
  }
}

export class NotFoundError extends AppError {
  constructor(resource: string) {
    super(`${resource} not found`, 'NOT_FOUND', 404);
    this.name = 'NotFoundError';
  }
}

2. Error Handling in Services

// lib/axios.ts
import { AppError, ValidationError, AuthenticationError } from '@/shared/errors';

apiClient.interceptors.response.use(
  (response) => response,
  (error) => {
    if (axios.isAxiosError(error)) {
      const status = error.response?.status;
      const data = error.response?.data;

      switch (status) {
        case 400:
          throw new ValidationError(
            data?.message || 'Validation failed',
            data?.errors
          );
        case 401:
          throw new AuthenticationError(data?.message);
        case 403:
          throw new AuthorizationError(data?.message);
        case 404:
          throw new NotFoundError(data?.resource || 'Resource');
        default:
          throw new AppError(
            data?.message || 'An error occurred',
            'UNKNOWN_ERROR',
            status || 500,
            data
          );
      }
    }

    throw error;
  }
);

3. Error Boundaries

// shared/components/ErrorBoundary.tsx
interface ErrorBoundaryProps {
  children: React.ReactNode;
  fallback?: React.ComponentType<{ error: Error; reset: () => void }>;
}

interface ErrorBoundaryState {
  hasError: boolean;
  error: Error | null;
}

export class ErrorBoundary extends React.Component<
  ErrorBoundaryProps,
  ErrorBoundaryState
> {
  constructor(props: ErrorBoundaryProps) {
    super(props);
    this.state = { hasError: false, error: null };
  }

  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
    return { hasError: true, error };
  }

  componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
    console.error('Error caught by boundary:', error, errorInfo);
    // Log to error reporting service
    // errorReportingService.log(error, errorInfo);
  }

  reset = () => {
    this.setState({ hasError: false, error: null });
  };

  render() {
    if (this.state.hasError) {
      const FallbackComponent = this.props.fallback || DefaultErrorFallback;
      return <FallbackComponent error={this.state.error!} reset={this.reset} />;
    }

    return this.props.children;
  }
}

// Default error fallback
function DefaultErrorFallback({ error, reset }: { error: Error; reset: () => void }) {
  return (
    <div className="error-fallback">
      <h2>Something went wrong</h2>
      <p>{error.message}</p>
      <button onClick={reset}>Try again</button>
    </div>
  );
}

4. Error Handling in Components

// Component with error handling
function UserProfile({ userId }: { userId: string }) {
  const { data, error, isLoading } = useUser(userId);
  const updateMutation = useUpdateUser();

  const handleUpdate = async (data: UpdateUserDto) => {
    try {
      await updateMutation.mutateAsync({ id: userId, data });
      toast.success('Profile updated successfully!');
    } catch (error) {
      if (error instanceof ValidationError) {
        // Show field-specific errors
        Object.entries(error.details || {}).forEach(([field, message]) => {
          toast.error(`${field}: ${message}`);
        });
      } else if (error instanceof AppError) {
        toast.error(error.message);
      } else {
        toast.error('An unexpected error occurred');
      }
    }
  };

  if (isLoading) return <Spinner />;
  
  if (error) {
    if (error instanceof NotFoundError) {
      return <NotFound message="User not found" />;
    }
    if (error instanceof AuthorizationError) {
      return <Unauthorized />;
    }
    return <ErrorMessage error={error} />;
  }

  return <UserForm user={data} onSubmit={handleUpdate} />;
}

🏋️ Hands-On Exercises

// ❌ This component has multiple problems
function ProductDashboard() {
  const [products, setProducts] = useState([]);
  const [loading, setLoading] = useState(true);
  const [cart, setCart] = useState([]);
  const [search, setSearch] = useState('');
  
  useEffect(() => {
    fetch('/api/products')
      .then(res => res.json())
      .then(data => {
        setProducts(data);
        setLoading(false);
      });
  }, []);
  
  const addToCart = (product) => {
    const tax = product.price * 0.08;
    const total = product.price + tax;
    setCart([...cart, { ...product, tax, total }]);
    
    fetch('/api/cart', {
      method: 'POST',
      body: JSON.stringify({ productId: product.id })
    });
  };
  
  const filteredProducts = products.filter(p => 
    p.name.toLowerCase().includes(search.toLowerCase())
  );
  
  return (
    <div>
      <input 
        value={search} 
        onChange={(e) => setSearch(e.target.value)} 
      />
      {loading ? 'Loading...' : (
        filteredProducts.map(product => (
          <div key={product.id}>
            <h3>{product.name}</h3>
            <p>${product.price}</p>
            <button onClick={() => addToCart(product)}>
              Add to Cart
            </button>
          </div>
        ))
      )}
    </div>
  );
}

// Structure to aim for:
// services/productService.ts
// services/cartService.ts
// hooks/useProducts.ts
// hooks/useCart.ts
// components/ProductDashboard.tsx (orchestrator)
// components/ProductList.tsx (presentational)
// components/ProductCard.tsx (presentational)
// components/SearchBar.tsx (presentational)

// services/productService.ts
export const productService = {
  async getAll(): Promise<Product[]> {
    const response = await apiClient.get('/api/products');
    return response.data;
  }
};

// services/cartService.ts
export const cartService = {
  async addItem(productId: string): Promise<CartItem> {
    const response = await apiClient.post('/api/cart', { productId });
    return response.data;
  }
};

features/comments/
├── components/
│   ├── CommentList/
│   │   ├── CommentList.tsx
│   │   ├── CommentList.test.tsx
│   │   └── CommentList.module.css
│   ├── CommentItem/
│   ├── CommentForm/
│   └── CommentReply/
├── hooks/
│   ├── useComments.ts
│   ├── useAddComment.ts
│   ├── useUpdateComment.ts
│   └── useDeleteComment.ts
├── api/
│   └── commentService.ts
├── types/
│   └── comment.types.ts
├── utils/
│   └── commentHelpers.ts
└── index.ts

class AppError extends Error {
  constructor(
    message: string,
    public code: string,
    public statusCode: number
  ) {
    super(message);
  }
}

class AuthError extends AppError {
  constructor(message: string) {
    super(message, 'AUTH_ERROR', 401);
  }
}

// Handle in component:
try {
  await login(credentials);
} catch (error) {
  if (error instanceof AuthError) {
    setError('Invalid email or password');
  } else if (error instanceof NetworkError) {
    setError('Connection failed. Please try again.');
  } else {
    setError('An unexpected error occurred');
  }
}

🧠 Knowledge Check Quiz

// useShoppingCart.ts
- Calculate cart totals
- Add/remove items logic
- Cart state management
- Business rules (max items, etc.)

// Component
- Button click handlers that just call hooks
- Simple UI state (modal open/closed)
- Navigation after actions
- Direct prop transformations for rendering

- User
- CreateUserDto
- UpdateUserDto
- UserFilters
- UserRole (enum)

- ApiResponse<T>
- PaginatedResponse<T>
- ApiError
- ID (type alias)
- Nullable<T>
- Common utility types

📝 Lesson Summary