🏗️ Lesson 8.5: Architecture Best Practices

🎯 Principles of Good Architecture

Think of architecture like the framing of a house. 🏠 Nobody walks into a finished home and admires the studs behind the drywall — but get the framing wrong and every room you add later leans a little more, until one day the whole thing is too fragile to change. Software architecture is the framing behind your features: invisible when it's right, painfully obvious when it's wrong. Before we reach for specific patterns, let's ground ourselves in the principles that hold everything up. These apply whether you're building a weekend side project or an app that a hundred engineers touch every day.

The Core Principles

1. Separation of Concerns

Each part of your application should have a single, well-defined responsibility. Picture a restaurant kitchen: the person plating dessert isn't also taking orders and washing dishes. Each station does one job well, and the meal comes together because responsibilities are cleanly divided. React code works the same way — when components, hooks, and services each focus on one thing, they become dramatically easier to understand, test, and reuse. The example below shows the same feature written two ways: one where a single component tries to be the whole kitchen, and one where the work is split into stations.

// ❌ 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>
  );
}

6. Separate Server State from Client State

This is the single most important architectural shift in modern React, and it's worth pausing on. For years we jammed everything into useState and Redux — form inputs, modal toggles, and the list of users fetched from the API — as if it were all the same kind of data. It isn't.

• 🖥️ Client state is data your app owns and fully controls: is the sidebar open? what's typed in this input? which tab is active? It's synchronous, it lives only in the browser, and you are the source of truth.
• 🌐 Server state is a borrowed copy of data that actually lives on a server: the user list, a blog post, the shopping cart. It's asynchronous, it can go stale the moment someone else changes it, and the server — not your app — is the source of truth.

Treating borrowed server data like owned client state is why so many older codebases drown in isLoading flags, manual cache invalidation, and "why is this list out of date?" bugs. The modern answer is to stop hand-rolling that machinery and let a dedicated server-state library handle caching, refetching, and staleness for you.

7. Design for Testability

A good architecture test: if a component is hard to test, it's probably doing too much. This isn't just a nice-to-have — testability is a diagnostic. When you find yourself mocking six things just to render one component, that pain is the code telling you its concerns are tangled. Pull the data fetching into a hook you can test in isolation, keep the presentational component a pure function of its props, and suddenly both halves become trivial to test. We call these clean boundaries testing seams: the natural places where you can slot in a fake and verify one layer without dragging in the whole app.

Architecture Anti-Patterns to Avoid

📁 Feature-Based Folder Structure

Here's a question that reveals a lot about a codebase: when you sit down to change the "users" feature, how many folders do you have to open? In a small app, organizing files by type — all components in one folder, all hooks in another, all services in a third — feels tidy. But as the app grows, that tidiness turns on you. A single feature ends up smeared across four or five folders, and every change becomes a scavenger hunt.

Think of it like organizing a kitchen. 🍳 You could put all the handles in one drawer, all the blades in another, all the electrical cords in a third — sorted perfectly by type. But when you want to make an omelette, you'd be running all over the kitchen. Instead, you keep the things you use together, together. A feature-based structure does exactly this: it colocates everything a feature needs — its components, hooks, service calls, and types — so you can understand and change a feature as one complete unit.

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's public API
import { UserList, useUsers, type User } from '@/features/users';

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

That index.ts file is called a barrel — it re-exports a feature's public surface from one convenient place. Barrels are genuinely useful at the boundary of a feature: they let the rest of the app import from @/features/users without knowing or caring how the folder is laid out inside. That's real encapsulation, and it means you can rename or reorganize a feature's internals without breaking a single import elsewhere.

Path Aliases: Killing the ../../../ Problem

You've probably noticed the @/ in those imports. That's a path alias, and it's the difference between a clean import { userService } from '@/features/users' and the dreaded import { userService } from '../../../features/users' that breaks the instant you move a file. You configure it in two places — TypeScript (for type-checking and editor navigation) and your bundler (for the actual build):

// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import path from 'node:path';

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
});

Shared vs Feature-Specific

Deciding what goes in shared/ vs features/:

🧩 Component Organization Patterns

Not all components are created equal. A component that owns a route and coordinates a whole page plays a very different role from a tiny reusable button — and treating them the same way is how folders turn to mush. Understanding these roles is like understanding the ranks in a kitchen brigade: the head chef (page) plans the meal, station chefs (feature containers) run their sections, and line cooks (presentational components) execute one dish well. When everyone knows their job, the kitchen runs smoothly.

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

We touched on separation of concerns as a principle earlier; now let's make it concrete. The idea is to organize code into layers, each with a clear job, stacked so that each one only talks to the layer directly below it. Think of a restaurant again: the dining room (presentation) never walks into the walk-in freezer (data access) to grab ingredients — it sends an order through the kitchen (business logic), which decides what's needed and requests it from the pantry. Each layer trusts the next to do its job and doesn't reach past it. That discipline is what lets you swap out your entire API client later without touching a single button.

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) {
      // Under strict TS, a caught error is `unknown` — narrow before use
      toast.error(error instanceof Error ? error.message : 'Could not add to cart');
    }
  };
  
  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

If separation of concerns is the goal, custom hooks are the workhorse that gets you there in React. A custom hook is just a function whose name starts with use and that calls other hooks — but that simple idea is quietly powerful. It lets you lift stateful logic out of a component and into a named, reusable, independently testable unit, leaving the component free to do what it's best at: describe what the UI looks like. Think of a hook as a self-contained appliance: your component plugs into useCart() the way you plug a toaster into the wall, without needing to know a thing about the wiring inside.

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) {
      // `error` is `unknown` in strict mode — narrow before reading .message
      const message = error instanceof Error ? error.message : 'Submission failed';
      setErrors({ submit: 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 — the one place in your app that actually knows the shape of your backend. Instead of scattering fetch('/api/users') calls across twenty components (each with its own slightly different error handling and its own chance to typo the URL), you funnel everything through a typed service. It's the embassy of your application: all diplomacy with the outside world happens here, in one language, with one set of rules.

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

Types are the vocabulary of your codebase. When they're well organized, a new developer can read features/users/types/user.types.ts and understand the entire "users" domain in two minutes — the data shapes, the request payloads, the allowed roles. When they're scattered and inconsistently named, every file becomes a guessing game. The guiding rule is simple and mirrors the folder structure you already learned: put types as close to where they're used as possible. A type only the "users" feature cares about lives with the users feature; a type half the app shares moves to shared/.

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, unknown>; // prefer unknown over any for untrusted shapes
}

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

Errors aren't edge cases — they're a first-class part of your app's behavior, and users judge you by how gracefully you handle them. The difference between "Something went wrong, please try again" with a working retry button and a blank white screen of death is entirely architectural. The trick is to decide, deliberately, which layer handles which kind of failure. A network hiccup is caught differently from a validation error, which is caught differently from a bug that crashes rendering. Think of it as a set of nets stacked under a trapeze artist: most falls are caught by the first net (the API layer), and the last net (an error boundary) exists only to make sure nobody ever hits the floor.

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?: unknown
  ) {
    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>
  );
}

import { ErrorBoundary } from 'react-error-boundary';

function App() {
  return (
    <ErrorBoundary
      FallbackComponent={DefaultErrorFallback}
      onReset={() => queryClient.clear()}
    >
      <Routes />
    </ErrorBoundary>
  );
}

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