React-Architecture-Approaches

React Architecture Approaches: A Comprehensive Guide

📖 Overview

Choosing the right architecture for your React application is crucial for long-term maintainability, scalability, and team productivity. This guide explores four popular architectural approaches, their philosophies, implementation details, and ideal use cases.

What You’ll Learn

📐 Four distinct architectural approaches with complete folder structures
🏗️ Real-world code examples for each pattern
✅ Pros and cons to make informed decisions
🎯 Recommendations based on project size and team structure
🔧 How to combine approaches for maximum flexibility

Atomic Design Approach
Domain-Driven Design (DDD) Approach
Feature-Sliced Design (FSD) Approach
Hybrid Approach
Comparison Table
Which Approach Should You Choose?
Recommendations

1. Atomic Design Approach

🎯 Philosophy

“Build from the smallest to the largest”

Atomic Design breaks down UI components into five distinct levels based on their complexity and composition:

Atoms → Molecules → Organisms → Templates → Pages

This methodology, inspired by chemistry, creates a systematic approach to building consistent, reusable UI components.

📂 Complete Structure

project/
├── public/
│   ├── index.html
│   └── favicon.ico
│
├── src/
│   ├── components/
│   │   ├── atoms/                      # Smallest, indivisible components
│   │   │   ├── Button/
│   │   │   │   ├── Button.tsx
│   │   │   │   ├── Button.module.css
│   │   │   │   ├── Button.test.tsx
│   │   │   │   └── Button.stories.tsx
│   │   │   ├── Input/
│   │   │   │   ├── Input.tsx
│   │   │   │   └── Input.module.css
│   │   │   ├── Label/
│   │   │   │   └── Label.tsx
│   │   │   ├── Icon/
│   │   │   │   └── Icon.tsx
│   │   │   ├── Avatar/
│   │   │   │   └── Avatar.tsx
│   │   │   ├── Badge/
│   │   │   │   └── Badge.tsx
│   │   │   └── index.ts               # Barrel exports
│   │   │
│   │   ├── molecules/                  # Combinations of atoms
│   │   │   ├── SearchBar/
│   │   │   │   ├── SearchBar.tsx      # Input + Button + Icon
│   │   │   │   └── SearchBar.module.css
│   │   │   ├── UserCard/
│   │   │   │   ├── UserCard.tsx       # Avatar + Text + Badge
│   │   │   │   └── UserCard.module.css
│   │   │   ├── FormField/
│   │   │   │   ├── FormField.tsx      # Label + Input + Error
│   │   │   │   └── FormField.module.css
│   │   │   ├── NavigationItem/
│   │   │   │   ├── NavigationItem.tsx # Icon + Link + Badge
│   │   │   │   └── NavigationItem.module.css
│   │   │   ├── ProductCard/
│   │   │   │   ├── ProductCard.tsx    # Image + Title + Price + Button
│   │   │   │   └── ProductCard.module.css
│   │   │   └── index.ts
│   │   │
│   │   ├── organisms/                  # Complex UI sections
│   │   │   ├── Header/
│   │   │   │   ├── Header.tsx        # Logo + Navigation + SearchBar
│   │   │   │   └── Header.module.css
│   │   │   ├── Footer/
│   │   │   │   ├── Footer.tsx
│   │   │   │   └── Footer.module.css
│   │   │   ├── ProductList/
│   │   │   │   ├── ProductList.tsx   # Multiple ProductCards + Filter
│   │   │   │   └── ProductList.module.css
│   │   │   ├── Sidebar/
│   │   │   │   ├── Sidebar.tsx       # NavigationItems + UserCard
│   │   │   │   └── Sidebar.module.css
│   │   │   ├── DashboardWidget/
│   │   │   │   ├── DashboardWidget.tsx
│   │   │   │   └── DashboardWidget.module.css
│   │   │   └── index.ts
│   │   │
│   │   ├── templates/                  # Page layouts with placeholders
│   │   │   ├── DefaultLayout/
│   │   │   │   ├── DefaultLayout.tsx # Header + Main + Footer
│   │   │   │   └── DefaultLayout.module.css
│   │   │   ├── DashboardLayout/
│   │   │   │   ├── DashboardLayout.tsx # Sidebar + Header + Content
│   │   │   │   └── DashboardLayout.module.css
│   │   │   ├── AuthLayout/
│   │   │   │   ├── AuthLayout.tsx    # Only form container
│   │   │   │   └── AuthLayout.module.css
│   │   │   └── index.ts
│   │   │
│   │   └── pages/                      # Complete pages (templates filled)
│   │       ├── HomePage.tsx
│   │       ├── DashboardPage.tsx
│   │       ├── ProductsPage.tsx
│   │       ├── LoginPage.tsx
│   │       └── UserProfilePage.tsx
│   │
│   ├── hooks/
│   │   ├── useAuth.ts
│   │   ├── useFetch.ts
│   │   └── useLocalStorage.ts
│   │
│   ├── services/
│   │   ├── apiClient.ts
│   │   ├── authService.ts
│   │   └── productService.ts
│   │
│   ├── store/
│   │   ├── slices/
│   │   │   ├── authSlice.ts
│   │   │   └── productSlice.ts
│   │   └── store.ts
│   │
│   ├── styles/
│   │   ├── global.scss
│   │   └── variables.scss
│   │
│   ├── types/
│   │   ├── components.types.ts
│   │   └── api.types.ts
│   │
│   ├── utils/
│   │   ├── formatters.ts
│   │   └── validators.ts
│   │
│   ├── App.tsx
│   ├── index.tsx
│   └── router.tsx
│
├── package.json
└── tsconfig.json

💻 Example Code

Atom: Button Component

// components/atoms/Button/Button.tsx
interface ButtonProps {
  variant: 'primary' | 'secondary' | 'danger';
  size: 'sm' | 'md' | 'lg';
  children: React.ReactNode;
  onClick?: () => void;
  disabled?: boolean;
  loading?: boolean;
}

export const Button: React.FC<ButtonProps> = ({
  variant,
  size,
  children,
  onClick,
  disabled,
  loading,
}) => {
  return (
    <button
      className={`btn btn-${variant} btn-${size}`}
      onClick={onClick}
      disabled={disabled || loading}
      aria-busy={loading}
    >
      {loading ? <Spinner /> : children}
    </button>
  );
};

Molecule: SearchBar Component

// components/molecules/SearchBar/SearchBar.tsx
import { Input, Button, Icon } from '../../atoms';

interface SearchBarProps {
  onSearch: (query: string) => void;
  placeholder?: string;
  initialValue?: string;
}

export const SearchBar: React.FC<SearchBarProps> = ({
  onSearch,
  placeholder = 'Search...',
  initialValue = '',
}) => {
  const [query, setQuery] = useState(initialValue);

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    if (query.trim()) {
      onSearch(query);
    }
  };

  return (
    <form className="search-bar" onSubmit={handleSubmit} role="search">
      <Icon name="search" aria-hidden="true" />
      <Input
        value={query}
        onChange={(e) => setQuery(e.target.value)}
        placeholder={placeholder}
        aria-label="Search"
      />
      <Button variant="primary" size="md" type="submit">
        Search
      </Button>
    </form>
  );
};

Organism: Header Component

// components/organisms/Header/Header.tsx
import { Logo, Navigation, SearchBar, UserMenu } from '../../molecules';

interface HeaderProps {
  user?: User;
  navItems: NavItem[];
}

export const Header: React.FC<HeaderProps> = ({ user, navItems }) => {
  return (
    <header className="header" role="banner">
      <div className="header__container">
        <Logo />
        <Navigation items={navItems} />
        <SearchBar onSearch={handleSearch} />
        <UserMenu user={user} />
      </div>
    </header>
  );
};

✅ Pros

Advantage	Description
High Reusability	Components are built to be reused across the application
Consistent UI	Standardized naming and structure ensure design consistency
Easy Testing	Small, focused components are straightforward to test
Design System Friendly	Perfect foundation for building and maintaining UI libraries
Clear Hierarchy	Easy to understand component relationships

❌ Cons

Disadvantage	Description
Over-engineering	Can be too granular for simple applications
Feature Scattering	Related logic is spread across different folders
Complex Navigation	Can be difficult to locate components in large projects
Rigid Structure	May not accommodate complex business logic well

🎯 Best For

Design Systems and UI Libraries
Large Applications with shared components across multiple features
Teams with Dedicated UI/UX designers
Projects requiring high visual consistency

2. Domain-Driven Design (DDD) Approach

🎯 Philosophy

“Organize around business domains, not technical layers”

Domain-Driven Design organizes code around business domains (bounded contexts) rather than technical concerns. Each domain (e.g., Users, Products, Orders) contains everything it needs: components, hooks, services, types, and state management.

📂 Complete Structure

src/
├── domains/                           # Business domains (bounded contexts)
│   │
│   ├── auth/                          # Authentication domain
│   │   ├── components/
│   │   │   ├── LoginForm.tsx
│   │   │   ├── RegisterForm.tsx
│   │   │   ├── ForgotPassword.tsx
│   │   │   └── AuthGuard.tsx
│   │   ├── hooks/
│   │   │   ├── useAuth.ts
│   │   │   ├── useLogin.ts
│   │   │   └── useSession.ts
│   │   ├── services/
│   │   │   ├── auth.service.ts
│   │   │   ├── token.service.ts
│   │   │   └── session.service.ts
│   │   ├── store/
│   │   │   ├── auth.slice.ts
│   │   │   └── auth.selectors.ts
│   │   ├── types/
│   │   │   ├── auth.types.ts
│   │   │   ├── user.types.ts
│   │   │   └── session.types.ts
│   │   ├── utils/
│   │   │   ├── auth.validators.ts
│   │   │   ├── password.utils.ts
│   │   │   └── token.utils.ts
│   │   ├── pages/
│   │   │   ├── LoginPage.tsx
│   │   │   ├── RegisterPage.tsx
│   │   │   └── ResetPasswordPage.tsx
│   │   ├── constants/
│   │   │   ├── auth.constants.ts
│   │   │   └── roles.constants.ts
│   │   ├── auth.test.ts
│   │   └── index.ts                  # Public API
│   │
│   ├── users/                         # Users domain
│   │   ├── components/
│   │   │   ├── UserProfile.tsx
│   │   │   ├── UserList.tsx
│   │   │   ├── UserCard.tsx
│   │   │   └── UserSettings.tsx
│   │   ├── hooks/
│   │   │   ├── useUsers.ts
│   │   │   ├── useUserProfile.ts
│   │   │   └── useUserRoles.ts
│   │   ├── services/
│   │   │   ├── user.service.ts
│   │   │   ├── user.repository.ts
│   │   │   └── user.api.ts
│   │   ├── store/
│   │   │   ├── user.slice.ts
│   │   │   └── user.selectors.ts
│   │   ├── types/
│   │   │   ├── user.types.ts
│   │   │   ├── role.types.ts
│   │   │   └── permission.types.ts
│   │   ├── utils/
│   │   │   ├── user.validators.ts
│   │   │   └── user.formatters.ts
│   │   ├── pages/
│   │   │   ├── UsersPage.tsx
│   │   │   ├── UserDetailsPage.tsx
│   │   │   └── UserEditPage.tsx
│   │   ├── user.test.ts
│   │   └── index.ts
│   │
│   ├── products/                      # Products domain
│   │   ├── components/
│   │   │   ├── ProductCard.tsx
│   │   │   ├── ProductList.tsx
│   │   │   ├── ProductForm.tsx
│   │   │   ├── ProductFilters.tsx
│   │   │   └── ProductReview.tsx
│   │   ├── hooks/
│   │   │   ├── useProducts.ts
│   │   │   ├── useProductSearch.ts
│   │   │   └── useProductFilters.ts
│   │   ├── services/
│   │   │   ├── product.service.ts
│   │   │   ├── product.cache.ts
│   │   │   └── product.api.ts
│   │   ├── store/
│   │   │   ├── product.slice.ts
│   │   │   └── product.selectors.ts
│   │   ├── types/
│   │   │   ├── product.types.ts
│   │   │   ├── category.types.ts
│   │   │   └── inventory.types.ts
│   │   ├── utils/
│   │   │   ├── product.validators.ts
│   │   │   ├── product.formatters.ts
│   │   │   └── product.calculators.ts
│   │   ├── pages/
│   │   │   ├── ProductsPage.tsx
│   │   │   ├── ProductDetailsPage.tsx
│   │   │   └── ProductCreatePage.tsx
│   │   ├── product.test.ts
│   │   └── index.ts
│   │
│   ├── orders/                        # Orders domain
│   │   ├── components/
│   │   ├── hooks/
│   │   ├── services/
│   │   ├── store/
│   │   ├── types/
│   │   ├── utils/
│   │   ├── pages/
│   │   └── index.ts
│   │
│   └── shared/                        # Shared across domains
│       ├── components/
│       │   ├── Button.tsx
│       │   ├── Modal.tsx
│       │   ├── Spinner.tsx
│       │   └── Toast.tsx
│       ├── hooks/
│       │   ├── useDebounce.ts
│       │   └── useLocalStorage.ts
│       ├── types/
│       │   ├── common.types.ts
│       │   └── api.types.ts
│       ├── utils/
│       │   ├── formatters.ts
│       │   ├── validators.ts
│       │   └── date.utils.ts
│       ├── constants/
│       │   ├── routes.ts
│       │   └── app.constants.ts
│       └── services/
│           └── api.service.ts
│
├── app/                               # App-level configuration
│   ├── config/
│   │   ├── env.ts
│   │   └── app.config.ts
│   ├── store/
│   │   └── store.ts                  # Root store combining domain stores
│   ├── router/
│   │   └── router.tsx
│   ├── styles/
│   │   └── global.scss
│   ├── App.tsx
│   └── index.tsx
│
└── infrastructure/                    # External integrations
    ├── api/
    ├── logging/
    ├── monitoring/
    └── analytics/

💻 Example Code

Domain Types

// domains/auth/types/auth.types.ts
export interface User {
  id: string;
  email: string;
  firstName: string;
  lastName: string;
  roles: UserRole[];
  permissions: Permission[];
  createdAt: Date;
  updatedAt: Date;
}

export enum UserRole {
  ADMIN = 'admin',
  USER = 'user',
  MODERATOR = 'moderator',
}

export enum Permission {
  READ_USERS = 'read:users',
  WRITE_USERS = 'write:users',
  DELETE_USERS = 'delete:users',
  READ_PRODUCTS = 'read:products',
  WRITE_PRODUCTS = 'write:products',
}

export interface AuthState {
  user: User | null;
  isAuthenticated: boolean;
  isLoading: boolean;
  error: string | null;
  token: string | null;
}

Domain Service

// domains/auth/services/auth.service.ts
import { User, AuthState } from '../types/auth.types';
import { apiClient } from '../../../infrastructure/api';

export class AuthService {
  static async login(email: string, password: string): Promise<User> {
    try {
      const response = await apiClient.post('/auth/login', { email, password });
      const { user, token } = response.data;
      
      // Store token
      localStorage.setItem('access_token', token);
      apiClient.defaults.headers.common['Authorization'] = `Bearer ${token}`;
      
      return user;
    } catch (error) {
      throw new Error('Authentication failed');
    }
  }

  static async logout(): Promise<void> {
    try {
      await apiClient.post('/auth/logout');
    } finally {
      localStorage.removeItem('access_token');
      delete apiClient.defaults.headers.common['Authorization'];
    }
  }

  static async refreshToken(): Promise<string> {
    const response = await apiClient.post('/auth/refresh');
    const { token } = response.data;
    localStorage.setItem('access_token', token);
    return token;
  }

  static async getCurrentUser(): Promise<User> {
    const response = await apiClient.get('/auth/me');
    return response.data;
  }
}

Domain Hook

// domains/auth/hooks/useAuth.ts
import { useAuthStore } from '../store/auth.slice';
import { AuthService } from '../services/auth.service';
import { useCallback } from 'react';

export const useAuth = () => {
  const { user, isAuthenticated, isLoading, error } = useAuthStore();

  const login = useCallback(async (email: string, password: string) => {
    try {
      useAuthStore.getState().setLoading(true);
      const user = await AuthService.login(email, password);
      useAuthStore.getState().setUser(user);
    } catch (error) {
      useAuthStore.getState().setError(error.message);
    } finally {
      useAuthStore.getState().setLoading(false);
    }
  }, []);

  const logout = useCallback(async () => {
    try {
      await AuthService.logout();
      useAuthStore.getState().clearUser();
    } catch (error) {
      console.error('Logout failed:', error);
    }
  }, []);

  const refreshSession = useCallback(async () => {
    try {
      const token = await AuthService.refreshToken();
      const user = await AuthService.getCurrentUser();
      useAuthStore.getState().setUser(user);
      return token;
    } catch (error) {
      useAuthStore.getState().clearUser();
      throw error;
    }
  }, []);

  return {
    user,
    isAuthenticated,
    isLoading,
    error,
    login,
    logout,
    refreshSession,
  };
};

Domain Component

// domains/auth/components/LoginForm.tsx
import { useAuth } from '../hooks/useAuth';
import { Button, Input } from '../../shared/components';
import { useForm } from '../../shared/hooks/useForm';
import { authValidators } from '../utils/auth.validators';

interface LoginFormData {
  email: string;
  password: string;
}

export const LoginForm: React.FC = () => {
  const { login, isLoading } = useAuth();
  const { values, errors, handleChange, handleSubmit } = useForm<LoginFormData>({
    initialValues: { email: '', password: '' },
    validate: authValidators.login,
    onSubmit: (data) => login(data.email, data.password),
  });

  return (
    <form onSubmit={handleSubmit} className="login-form" noValidate>
      <div className="login-form__header">
        <h2>Welcome Back</h2>
        <p>Sign in to your account to continue</p>
      </div>

      <Input
        type="email"
        name="email"
        value={values.email}
        onChange={handleChange}
        label="Email Address"
        placeholder="you@example.com"
        required
        error={errors.email}
        disabled={isLoading}
        autoFocus
      />

      <Input
        type="password"
        name="password"
        value={values.password}
        onChange={handleChange}
        label="Password"
        placeholder="Enter your password"
        required
        error={errors.password}
        disabled={isLoading}
      />

      <div className="login-form__actions">
        <Button
          type="submit"
          variant="primary"
          size="lg"
          loading={isLoading}
          disabled={isLoading}
          fullWidth
        >
          {isLoading ? 'Signing in...' : 'Sign In'}
        </Button>
      </div>

      <div className="login-form__footer">
        <a href="/forgot-password">Forgot password?</a>
        <span>|</span>
        <a href="/register">Create account</a>
      </div>
    </form>
  );
};

✅ Pros

Advantage	Description
Business Logic Centric	Easy to understand and modify business rules
Autonomous Teams	Teams can work on separate domains independently
High Cohesion	Related code lives together, reducing cognitive load
Scalable	Easy to add new domains without affecting others
Maintainability	Clear boundaries make code easier to maintain

❌ Cons

Disadvantage	Description
Initial Complexity	More setup and planning required
Domain Boundaries	Can be blurry between domains
Shared Components	Need careful management of shared code
Overhead	May be overkill for simple applications

🎯 Best For

Large Enterprise Applications with complex business logic
Multiple Teams working on different features independently
Long-term Projects requiring high maintainability
Projects with Clear Domain Experts who understand business rules

3. Feature-Sliced Design (FSD) Approach

🎯 Philosophy

“Strict layers with clear dependency rules”

Feature-Sliced Design is a structural architecture that organizes code into slices (features) with strict layering:

App → Pages → Widgets → Features → Entities → Shared

Each layer can only depend on layers below it, creating a clear, predictable architecture that scales well.

📂 Complete Structure

src/
├── app/                               # App-level configurations
│   ├── config/
│   │   ├── env.ts
│   │   └── app.config.ts
│   ├── providers/
│   │   ├── ThemeProvider.tsx
│   │   ├── StoreProvider.tsx
│   │   └── RouterProvider.tsx
│   ├── styles/
│   │   ├── _reset.scss
│   │   ├── _variables.scss
│   │   └── global.scss
│   ├── App.tsx
│   ├── index.tsx
│   └── types.ts
│
├── pages/                             # Page-level composition
│   ├── auth-page/
│   │   ├── ui/
│   │   │   ├── AuthPage.tsx
│   │   │   └── AuthPage.module.scss
│   │   └── index.ts
│   ├── dashboard-page/
│   │   ├── ui/
│   │   │   ├── DashboardPage.tsx
│   │   │   └── DashboardPage.module.scss
│   │   └── index.ts
│   ├── products-page/
│   │   ├── ui/
│   │   │   ├── ProductsPage.tsx
│   │   │   └── ProductsPage.module.scss
│   │   └── index.ts
│   └── index.ts
│
├── widgets/                           # Reusable blocks (larger than features)
│   ├── header/
│   │   ├── ui/
│   │   │   ├── Header.tsx
│   │   │   └── Header.module.scss
│   │   ├── model/
│   │   │   ├── header.model.ts
│   │   │   └── header.types.ts
│   │   └── index.ts
│   ├── sidebar/
│   │   ├── ui/
│   │   ├── model/
│   │   └── index.ts
│   ├── product-list/
│   │   ├── ui/
│   │   │   ├── ProductList.tsx
│   │   │   ├── ProductCard.tsx
│   │   │   └── ProductList.module.scss
│   │   ├── model/
│   │   │   ├── productList.model.ts
│   │   │   ├── productList.types.ts
│   │   │   └── productList.selectors.ts
│   │   ├── api/
│   │   │   └── productList.api.ts
│   │   └── index.ts
│   └── index.ts
│
├── features/                          # User interactions/scenarios
│   ├── auth/
│   │   ├── ui/
│   │   │   ├── LoginForm.tsx
│   │   │   ├── RegisterForm.tsx
│   │   │   └── AuthForm.module.scss
│   │   ├── model/
│   │   │   ├── auth.model.ts
│   │   │   ├── auth.types.ts
│   │   │   └── auth.selectors.ts
│   │   ├── api/
│   │   │   ├── auth.api.ts
│   │   │   └── auth.endpoints.ts
│   │   ├── lib/
│   │   │   ├── auth.mappers.ts
│   │   │   └── auth.validators.ts
│   │   ├── hooks/
│   │   │   ├── useAuth.ts
│   │   │   └── useLogin.ts
│   │   └── index.ts
│   │
│   ├── product-search/
│   │   ├── ui/
│   │   │   ├── SearchBar.tsx
│   │   │   ├── SearchFilters.tsx
│   │   │   └── SearchResults.tsx
│   │   ├── model/
│   │   │   ├── search.model.ts
│   │   │   └── search.types.ts
│   │   ├── api/
│   │   │   └── search.api.ts
│   │   ├── hooks/
│   │   │   ├── useSearch.ts
│   │   │   └── useFilters.ts
│   │   └── index.ts
│   │
│   ├── user-profile/
│   │   ├── ui/
│   │   ├── model/
│   │   ├── api/
│   │   ├── hooks/
│   │   └── index.ts
│   │
│   └── index.ts
│
├── entities/                          # Business entities
│   ├── user/
│   │   ├── ui/
│   │   │   ├── UserCard.tsx
│   │   │   ├── UserAvatar.tsx
│   │   │   └── UserCard.module.scss
│   │   ├── model/
│   │   │   ├── user.model.ts
│   │   │   └── user.types.ts
│   │   ├── api/
│   │   │   └── user.api.ts
│   │   ├── lib/
│   │   │   └── user.validators.ts
│   │   └── index.ts
│   │
│   ├── product/
│   │   ├── ui/
│   │   │   ├── ProductCard.tsx
│   │   │   ├── ProductPrice.tsx
│   │   │   └── ProductCard.module.scss
│   │   ├── model/
│   │   │   ├── product.model.ts
│   │   │   └── product.types.ts
│   │   ├── api/
│   │   │   └── product.api.ts
│   │   ├── lib/
│   │   │   ├── product.validators.ts
│   │   │   └── product.formatters.ts
│   │   └── index.ts
│   │
│   ├── order/
│   │   ├── ui/
│   │   ├── model/
│   │   ├── api/
│   │   └── index.ts
│   │
│   └── index.ts
│
└── shared/                           # Shared code (lowest layer)
    ├── ui/
    │   ├── atoms/
    │   │   ├── Button/
    │   │   ├── Input/
    │   │   ├── Label/
    │   │   └── Icon/
    │   ├── molecules/
    │   │   ├── FormField/
    │   │   └── Toast/
    │   ├── organisms/
    │   │   └── Modal/
    │   └── index.ts
    │
    ├── api/
    │   ├── apiClient.ts
    │   ├── endpoints.ts
    │   └── interceptors.ts
    │
    ├── lib/
    │   ├── react-query.ts
    │   ├── i18n.ts
    │   └── sentry.ts
    │
    ├── hooks/
    │   ├── useDebounce.ts
    │   ├── useLocalStorage.ts
    │   └── useWindowSize.ts
    │
    ├── utils/
    │   ├── formatters/
    │   ├── validators/
    │   └── helpers/
    │
    ├── types/
    │   ├── common.types.ts
    │   └── api.types.ts
    │
    ├── constants/
    │   ├── routes.ts
    │   └── app.constants.ts
    │
    └── config/
        └── env.ts

💻 Example Code

Shared Components

// shared/ui/atoms/Button/Button.tsx
export interface ButtonProps {
  variant: 'primary' | 'secondary' | 'danger' | 'ghost';
  size: 'sm' | 'md' | 'lg';
  children: React.ReactNode;
  onClick?: () => void;
  loading?: boolean;
  disabled?: boolean;
  fullWidth?: boolean;
  type?: 'button' | 'submit' | 'reset';
}

export const Button: React.FC<ButtonProps> = ({
  variant = 'primary',
  size = 'md',
  children,
  onClick,
  loading = false,
  disabled = false,
  fullWidth = false,
  type = 'button',
}) => {
  const className = classNames(
    'btn',
    `btn--${variant}`,
    `btn--${size}`,
    {
      'btn--loading': loading,
      'btn--full-width': fullWidth,
    }
  );

  return (
    <button
      className={className}
      onClick={onClick}
      disabled={disabled || loading}
      type={type}
      aria-busy={loading}
    >
      {loading && <Spinner size="sm" className="btn__spinner" />}
      <span className="btn__content">{children}</span>
    </button>
  );
};

Entity Model

// entities/product/model/product.types.ts
export interface Product {
  id: string;
  name: string;
  description: string;
  price: number;
  category: ProductCategory;
  stock: number;
  images: string[];
  rating: number;
  reviews: ProductReview[];
  createdAt: Date;
  updatedAt: Date;
}

export interface ProductCategory {
  id: string;
  name: string;
  slug: string;
  description?: string;
}

export interface ProductReview {
  id: string;
  userId: string;
  rating: number;
  comment: string;
  createdAt: Date;
}

// entities/product/model/product.model.ts
import { Product } from './product.types';

export const productModel = {
  calculateDiscountPrice: (product: Product, discount: number): number => {
    return Math.round(product.price * (1 - discount / 100) * 100) / 100;
  },

  isInStock: (product: Product): boolean => {
    return product.stock > 0;
  },

  getStockStatus: (product: Product): 'in-stock' | 'low-stock' | 'out-of-stock' => {
    if (product.stock === 0) return 'out-of-stock';
    if (product.stock < 10) return 'low-stock';
    return 'in-stock';
  },

  getAverageRating: (product: Product): number => {
    if (product.reviews.length === 0) return 0;
    const sum = product.reviews.reduce((acc, review) => acc + review.rating, 0);
    return Math.round((sum / product.reviews.length) * 10) / 10;
  },

  getProductImageUrl: (product: Product, index: number = 0): string => {
    return product.images[index] || '/images/product-placeholder.jpg';
  },

  formatPrice: (product: Product): string => {
    return new Intl.NumberFormat('en-US', {
      style: 'currency',
      currency: 'USD',
    }).format(product.price);
  },
};

Feature Model

// features/product-search/model/search.types.ts
import { Product } from '../../../entities/product/model/product.types';

export interface SearchState {
  query: string;
  filters: SearchFilters;
  results: Product[];
  isLoading: boolean;
  error: string | null;
  hasMore: boolean;
  page: number;
}

export interface SearchFilters {
  category?: string;
  minPrice?: number;
  maxPrice?: number;
  inStock?: boolean;
  rating?: number;
  sortBy?: 'price-asc' | 'price-desc' | 'rating' | 'newest';
}

// features/product-search/model/search.model.ts
import { SearchState, SearchFilters } from './search.types';
import { Product } from '../../../entities/product/model/product.types';

export class SearchModel {
  private state: SearchState;

  constructor(initialState: Partial<SearchState> = {}) {
    this.state = {
      query: '',
      filters: {},
      results: [],
      isLoading: false,
      error: null,
      hasMore: true,
      page: 1,
      ...initialState,
    };
  }

  getState(): SearchState {
    return this.state;
  }

  setQuery(query: string) {
    this.state.query = query;
    this.state.page = 1;
    this.state.results = [];
  }

  setFilters(filters: SearchFilters) {
    this.state.filters = { ...this.state.filters, ...filters };
    this.state.page = 1;
    this.state.results = [];
  }

  setResults(results: Product[], append: boolean = false) {
    this.state.results = append
      ? [...this.state.results, ...results]
      : results;
  }

  setLoading(isLoading: boolean) {
    this.state.isLoading = isLoading;
  }

  setError(error: string | null) {
    this.state.error = error;
  }

  setHasMore(hasMore: boolean) {
    this.state.hasMore = hasMore;
  }

  incrementPage() {
    this.state.page += 1;
  }

  reset() {
    this.state = {
      query: '',
      filters: {},
      results: [],
      isLoading: false,
      error: null,
      hasMore: true,
      page: 1,
    };
  }

  getFilteredResults(): Product[] {
    return this.state.results.filter(product => {
      // Category filter
      if (this.state.filters.category &&
        product.category.id !== this.state.filters.category) {
        return false;
      }

      // Price range filter
      if (this.state.filters.minPrice !== undefined &&
        product.price < this.state.filters.minPrice) {
        return false;
      }

      if (this.state.filters.maxPrice !== undefined &&
        product.price > this.state.filters.maxPrice) {
        return false;
      }

      // In stock filter
      if (this.state.filters.inStock && product.stock === 0) {
        return false;
      }

      // Rating filter
      if (this.state.filters.rating !== undefined) {
        const avgRating = product.reviews.reduce((acc, r) => acc + r.rating, 0) / product.reviews.length;
        if (avgRating < this.state.filters.rating) {
          return false;
        }
      }

      return true;
    });
  }

  sortResults(results: Product[]): Product[] {
    const sortBy = this.state.filters.sortBy || 'newest';
    const sorted = [...results];

    switch (sortBy) {
      case 'price-asc':
        return sorted.sort((a, b) => a.price - b.price);
      case 'price-desc':
        return sorted.sort((a, b) => b.price - a.price);
      case 'rating':
        return sorted.sort((a, b) => {
          const ratingA = a.reviews.reduce((sum, r) => sum + r.rating, 0) / a.reviews.length;
          const ratingB = b.reviews.reduce((sum, r) => sum + r.rating, 0) / b.reviews.length;
          return ratingB - ratingA;
        });
      case 'newest':
      default:
        return sorted.sort((a, b) =>
          new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime()
        );
    }
  }
}

Feature Hook

// features/product-search/hooks/useSearch.ts
import { useQuery, useInfiniteQuery } from '@tanstack/react-query';
import { searchApi } from '../api/search.api';
import { SearchModel } from '../model/search.model';
import { useMemo, useCallback } from 'react';

export const useSearch = (initialQuery: string = '') => {
  const [searchState, setSearchState] = useState<SearchState>({
    query: initialQuery,
    filters: {},
    results: [],
    isLoading: false,
    error: null,
    hasMore: true,
    page: 1,
  });

  const searchModel = useMemo(() => new SearchModel(searchState), [searchState]);

  const { data, isLoading, error, fetchNextPage, hasNextPage } = useInfiniteQuery({
    queryKey: ['search', searchState.query, searchState.filters],
    queryFn: ({ pageParam = 1 }) =>
      searchApi.search(searchState.query, searchState.filters, pageParam),
    getNextPageParam: (lastPage, allPages) => {
      if (lastPage.length < 20) return undefined;
      return allPages.length + 1;
    },
    enabled: searchState.query.length >= 3,
    staleTime: 30000,
  });

  const results = useMemo(() => {
    if (!data) return [];
    return data.pages.flat();
  }, [data]);

  const performSearch = useCallback((query: string) => {
    searchModel.setQuery(query);
    setSearchState(searchModel.getState());
  }, [searchModel]);

  const applyFilters = useCallback((filters: SearchFilters) => {
    searchModel.setFilters(filters);
    setSearchState(searchModel.getState());
  }, [searchModel]);

  const loadMore = useCallback(() => {
    if (hasNextPage && !isLoading) {
      fetchNextPage();
    }
  }, [hasNextPage, isLoading, fetchNextPage]);

  return {
    results,
    isLoading,
    error: error?.message || null,
    performSearch,
    applyFilters,
    loadMore,
    hasMore: hasNextPage,
    model: searchModel,
  };
};

// widgets/product-list/ui/ProductList.tsx
import { useSearch } from '../../../features/product-search/hooks/useSearch';
import { ProductCard } from '../../../entities/product/ui/ProductCard';
import { SearchBar } from '../../../features/product-search/ui/SearchBar';
import { ProductFilters } from '../../../features/product-search/ui/ProductFilters';
import { LoadingSpinner } from '../../../shared/ui/atoms/Spinner';
import { EmptyState } from '../../../shared/ui/molecules/EmptyState';
import { useInView } from '../../../shared/hooks/useInView';

interface ProductListProps {
  initialQuery?: string;
  className?: string;
}

export const ProductList: React.FC<ProductListProps> = ({
  initialQuery = '',
  className,
}) => {
  const {
    results,
    isLoading,
    error,
    performSearch,
    applyFilters,
    loadMore,
    hasMore,
    model,
  } = useSearch(initialQuery);

  const { ref, inView } = useInView();

  // Auto-load more when reaching bottom
  useEffect(() => {
    if (inView && hasMore && !isLoading) {
      loadMore();
    }
  }, [inView, hasMore, isLoading, loadMore]);

  if (error) {
    return (
      <div className="product-list__error">
        <p>Error loading products: {error}</p>
        <Button onClick={() => performSearch(model.getState().query)}>
          Retry
        </Button>
      </div>
    );
  }

  return (
    <div className={classNames('product-list', className)}>
      <div className="product-list__header">
        <SearchBar
          onSearch={performSearch}
          initialValue={initialQuery}
          isLoading={isLoading}
        />
        <ProductFilters onApplyFilters={applyFilters} currentFilters={model.getState().filters} />
      </div>

      {isLoading && results.length === 0 ? (
        <div className="product-list__loading">
          <LoadingSpinner size="lg" />
          <p>Loading products...</p>
        </div>
      ) : results.length === 0 ? (
        <EmptyState
          title="No products found"
          description="Try adjusting your search or filters"
          action={
            <Button variant="secondary" onClick={() => performSearch('')}>
              Clear filters
            </Button>
          }
        />
      ) : (
        <>
          <div className="product-list__grid">
            {results.map((product, index) => (
              <ProductCard
                key={product.id}
                product={product}
                priority={index < 6}
              />
            ))}
          </div>

          {hasMore && (
            <div ref={ref} className="product-list__load-more">
              {isLoading && <LoadingSpinner size="sm" />}
            </div>
          )}

          {!hasMore && results.length > 0 && (
            <p className="product-list__end-message">
              You've reached the end of the results
            </p>
          )}
        </>
      )}
    </div>
  );
};

Page

// pages/products-page/ui/ProductsPage.tsx
import { ProductList } from '../../../widgets/product-list/ui/ProductList';
import { PageLayout } from '../../../widgets/page-layout/ui/PageLayout';
import { Breadcrumbs } from '../../../widgets/breadcrumbs/ui/Breadcrumbs';
import { PageTitle } from '../../../shared/ui/molecules/PageTitle';
import { useRouteParams } from '../../../shared/hooks/useRouteParams';

export const ProductsPage: React.FC = () => {
  const params = useRouteParams<{ category?: string }>();
  const category = params.category || '';

  return (
    <PageLayout>
      <div className="products-page">
        <Breadcrumbs
          items={[
            { label: 'Home', href: '/' },
            { label: 'Products', href: '/products' },
            ...(category ? [{ label: category, href: `/products/${category}` }] : []),
          ]}
        />

        <PageTitle
          title={category ? `${category} Products` : 'All Products'}
          subtitle="Browse our curated collection of high-quality products"
        />

        <ProductList
          initialQuery={category}
          className="products-page__list"
        />
      </div>
    </PageLayout>
  );
};

✅ Pros

Advantage	Description
Strict Layer Architecture	Clear dependency rules (App → Pages → Widgets → Features → Entities → Shared)
Excellent Scalability	Designed for large applications from the start
High Reusability	Components are reusable across features
Team Collaboration	Clear ownership of slices
Maintainability	Easy to understand where things belong

❌ Cons

Disadvantage	Description
Steep Learning Curve	Complex architecture to understand
Over-engineering	Too much structure for small apps
Boilerplate	Lots of folders and files
Rigidity	Can be inflexible for some use cases

🎯 Best For

Large-scale Enterprise Applications
Long-term Projects with many developers
Projects requiring high maintainability
Teams comfortable with strict architectural rules

4. Hybrid Approach

🎯 Philosophy

“Balance technical organization with feature cohesion”

The Hybrid approach organizes code by technical concerns at the top level for easy navigation, while grouping related business logic within feature folders to maintain cohesion. It strikes a practical balance between rigid architecture and complete flexibility.

📂 Complete Structure

src/
├── assets/                            # Static assets
│   ├── images/
│   ├── fonts/
│   └── icons/
│
├── components/                        # Reusable components
│   ├── Button/
│   │   ├── Button.tsx
│   │   ├── Button.module.scss
│   │   └── Button.test.tsx
│   ├── Modal/
│   │   ├── Modal.tsx
│   │   └── Modal.module.scss
│   ├── Navbar/
│   │   ├── Navbar.tsx
│   │   └── Navbar.module.scss
│   ├── Card/
│   │   ├── Card.tsx
│   │   └── Card.module.scss
│   └── index.ts
│
├── features/                          # Feature-specific logic
│   ├── auth/
│   │   ├── components/
│   │   │   ├── LoginForm.tsx
│   │   │   ├── RegisterForm.tsx
│   │   │   └── AuthGuard.tsx
│   │   ├── hooks/
│   │   │   └── useAuth.ts
│   │   ├── services/
│   │   │   └── auth.service.ts
│   │   ├── types/
│   │   │   └── auth.types.ts
│   │   ├── store/
│   │   │   └── auth.slice.ts
│   │   └── index.ts
│   │
│   ├── dashboard/
│   │   ├── components/
│   │   │   ├── DashboardStats.tsx
│   │   │   ├── ActivityFeed.tsx
│   │   │   └── ChartWidget.tsx
│   │   ├── hooks/
│   │   │   └── useDashboard.ts
│   │   ├── services/
│   │   │   └── dashboard.service.ts
│   │   ├── types/
│   │   │   └── dashboard.types.ts
│   │   └── index.ts
│   │
│   ├── profile/
│   │   ├── components/
│   │   │   ├── UserProfile.tsx
│   │   │   ├── ProfileSettings.tsx
│   │   │   └── AvatarUpload.tsx
│   │   ├── hooks/
│   │   │   └── useProfile.ts
│   │   ├── services/
│   │   │   └── profile.service.ts
│   │   ├── types/
│   │   │   └── profile.types.ts
│   │   └── index.ts
│   │
│   └── products/
│       ├── components/
│       │   ├── ProductCard.tsx
│       │   ├── ProductList.tsx
│       │   └── ProductFilters.tsx
│       ├── hooks/
│       │   ├── useProducts.ts
│       │   └── useProductSearch.ts
│       ├── services/
│       │   └── product.service.ts
│       ├── types/
│       │   └── product.types.ts
│       └── index.ts
│
├── hooks/                             # Global custom hooks
│   ├── useAuth.ts
│   ├── useFetch.ts
│   ├── useForm.ts
│   ├── useLocalStorage.ts
│   ├── useDebounce.ts
│   └── useMediaQuery.ts
│
├── layouts/                           # Layout components
│   ├── MainLayout/
│   │   ├── MainLayout.tsx
│   │   └── MainLayout.module.scss
│   ├── AdminLayout/
│   │   ├── AdminLayout.tsx
│   │   └── AdminLayout.module.scss
│   └── AuthLayout/
│       ├── AuthLayout.tsx
│       └── AuthLayout.module.scss
│
├── pages/                             # Page components (routes)
│   ├── auth/
│   │   ├── LoginPage.tsx
│   │   ├── RegisterPage.tsx
│   │   └── ForgotPasswordPage.tsx
│   ├── dashboard/
│   │   └── DashboardPage.tsx
│   ├── products/
│   │   ├── ProductsPage.tsx
│   │   ├── ProductDetailsPage.tsx
│   │   └── ProductCreatePage.tsx
│   ├── users/
│   │   ├── UsersPage.tsx
│   │   └── UserDetailsPage.tsx
│   └── index.ts
│
├── services/                          # API and external services
│   ├── api/
│   │   ├── apiClient.ts
│   │   ├── api.interceptors.ts
│   │   └── endpoints.ts
│   ├── authService.ts
│   ├── userService.ts
│   ├── productService.ts
│   └── index.ts
│
├── store/                             # Global state management
│   ├── slices/
│   │   ├── auth.slice.ts
│   │   ├── user.slice.ts
│   │   ├── product.slice.ts
│   │   └── ui.slice.ts
│   ├── selectors/
│   │   ├── auth.selectors.ts
│   │   ├── user.selectors.ts
│   │   └── product.selectors.ts
│   ├── hooks/
│   │   ├── useAppDispatch.ts
│   │   └── useAppSelector.ts
│   └── store.ts
│
├── styles/                            # Global styles
│   ├── abstracts/
│   │   ├── _variables.scss
│   │   ├── _mixins.scss
│   │   └── _functions.scss
│   ├── base/
│   │   ├── _reset.scss
│   │   └── _typography.scss
│   ├── components/
│   │   └── _utilities.scss
│   ├── themes/
│   │   ├── _light.scss
│   │   └── _dark.scss
│   └── global.scss
│
├── types/                             # TypeScript types
│   ├── api.types.ts
│   ├── common.types.ts
│   ├── user.types.ts
│   └── component.types.ts
│
├── utils/                             # Utility functions
│   ├── formatters/
│   │   ├── date.formatters.ts
│   │   ├── currency.formatters.ts
│   │   └── string.formatters.ts
│   ├── validators/
│   │   ├── email.validators.ts
│   │   └── password.validators.ts
│   ├── helpers/
│   │   ├── debounce.ts
│   │   └── throttle.ts
│   └── index.ts
│
├── constants/                         # Constants
│   ├── routes.ts
│   ├── roles.ts
│   ├── permissions.ts
│   └── app.constants.ts
│
├── config/                            # Configuration
│   ├── env.ts
│   ├── app.config.ts
│   └── theme.config.ts
│
├── App.tsx
├── index.tsx
└── router.tsx

💻 Example Code

Shared Component

// components/Button/Button.tsx
export interface ButtonProps {
  variant?: 'primary' | 'secondary' | 'danger' | 'ghost';
  size?: 'sm' | 'md' | 'lg';
  children: React.ReactNode;
  onClick?: () => void;
  loading?: boolean;
  disabled?: boolean;
  fullWidth?: boolean;
  className?: string;
  type?: 'button' | 'submit' | 'reset';
  ariaLabel?: string;
}

export const Button: React.FC<ButtonProps> = ({
  variant = 'primary',
  size = 'md',
  children,
  onClick,
  loading = false,
  disabled = false,
  fullWidth = false,
  className = '',
  type = 'button',
  ariaLabel,
}) => {
  return (
    <button
      className={`btn btn--${variant} btn--${size} ${fullWidth ? 'btn--full-width' : ''} ${className}`}
      onClick={onClick}
      disabled={disabled || loading}
      type={type}
      aria-label={ariaLabel || (typeof children === 'string' ? children : undefined)}
      aria-busy={loading}
    >
      {loading && <Spinner size="sm" className="btn__spinner" />}
      <span className="btn__content">{children}</span>
    </button>
  );
};

Feature Service

// features/auth/services/auth.service.ts
import { apiClient } from '../../../services/api/apiClient';
import { User, LoginCredentials, RegisterData, AuthResponse } from '../types/auth.types';

class AuthService {
  private static instance: AuthService;

  static getInstance(): AuthService {
    if (!AuthService.instance) {
      AuthService.instance = new AuthService();
    }
    return AuthService.instance;
  }

  async login(credentials: LoginCredentials): Promise<User> {
    try {
      const response = await apiClient.post<AuthResponse>('/auth/login', credentials);
      const { user, token } = response.data;

      // Store token
      localStorage.setItem('access_token', token);
      apiClient.defaults.headers.common['Authorization'] = `Bearer ${token}`;

      return user;
    } catch (error) {
      throw this.handleError(error);
    }
  }

  async register(data: RegisterData): Promise<User> {
    try {
      const response = await apiClient.post<AuthResponse>('/auth/register', data);
      return response.data.user;
    } catch (error) {
      throw this.handleError(error);
    }
  }

  async logout(): Promise<void> {
    try {
      await apiClient.post('/auth/logout');
    } finally {
      localStorage.removeItem('access_token');
      delete apiClient.defaults.headers.common['Authorization'];
    }
  }

  async refreshToken(): Promise<string> {
    try {
      const refreshToken = localStorage.getItem('refresh_token');
      const response = await apiClient.post<{ token: string }>('/auth/refresh', {
        refreshToken,
      });
      const { token } = response.data;
      localStorage.setItem('access_token', token);
      return token;
    } catch (error) {
      throw this.handleError(error);
    }
  }

  async getCurrentUser(): Promise<User> {
    try {
      const response = await apiClient.get<User>('/auth/me');
      return response.data;
    } catch (error) {
      throw this.handleError(error);
    }
  }

  private handleError(error: any): Error {
    if (error.response) {
      const message = error.response.data?.message || 'An error occurred';
      return new Error(message);
    }
    return new Error('Network error');
  }
}

export const authService = AuthService.getInstance();

Feature Hook

// features/auth/hooks/useAuth.ts
import { useState, useCallback, useEffect } from 'react';
import { authService } from '../services/auth.service';
import { useAppDispatch, useAppSelector } from '../../../store/hooks';
import { setUser, clearUser, setLoading, setError } from '../store/auth.slice';
import { User, LoginCredentials, RegisterData } from '../types/auth.types';

export const useAuth = () => {
  const dispatch = useAppDispatch();
  const { user, isAuthenticated, isLoading, error } = useAppSelector(
    (state) => state.auth
  );

  const login = useCallback(async (credentials: LoginCredentials) => {
    try {
      dispatch(setLoading(true));
      dispatch(setError(null));
      const user = await authService.login(credentials);
      dispatch(setUser(user));
      return user;
    } catch (error) {
      dispatch(setError(error.message));
      throw error;
    } finally {
      dispatch(setLoading(false));
    }
  }, [dispatch]);

  const register = useCallback(async (data: RegisterData) => {
    try {
      dispatch(setLoading(true));
      dispatch(setError(null));
      const user = await authService.register(data);
      return user;
    } catch (error) {
      dispatch(setError(error.message));
      throw error;
    } finally {
      dispatch(setLoading(false));
    }
  }, [dispatch]);

  const logout = useCallback(async () => {
    try {
      await authService.logout();
    } finally {
      dispatch(clearUser());
    }
  }, [dispatch]);

  const refreshSession = useCallback(async () => {
    try {
      const token = await authService.refreshToken();
      const user = await authService.getCurrentUser();
      dispatch(setUser(user));
      return token;
    } catch (error) {
      dispatch(clearUser());
      throw error;
    }
  }, [dispatch]);

  // Check session on mount
  useEffect(() => {
    const token = localStorage.getItem('access_token');
    if (token && !user) {
      refreshSession().catch(() => {
        // Silent fail - session will be checked on next route change
      });
    }
  }, [user, refreshSession]);

  return {
    user,
    isAuthenticated,
    isLoading,
    error,
    login,
    register,
    logout,
    refreshSession,
  };
};

Feature Component

// features/auth/components/LoginForm.tsx
import { useState } from 'react';
import { useAuth } from '../hooks/useAuth';
import { Button } from '../../../components/Button/Button';
import { Input } from '../../../components/Input/Input';
import { useNavigate, Link } from 'react-router-dom';
import { validateEmail, validatePassword } from '../../../utils/validators';

interface LoginFormProps {
  redirectTo?: string;
  onSuccess?: () => void;
}

export const LoginForm: React.FC<LoginFormProps> = ({
  redirectTo = '/dashboard',
  onSuccess,
}) => {
  const navigate = useNavigate();
  const { login, isLoading, error } = useAuth();
  const [formData, setFormData] = useState({
    email: '',
    password: '',
  });
  const [formErrors, setFormErrors] = useState({
    email: '',
    password: '',
  });

  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    const { name, value } = e.target;
    setFormData(prev => ({ ...prev, [name]: value }));
    // Clear error on change
    setFormErrors(prev => ({ ...prev, [name]: '' }));
  };

  const validate = (): boolean => {
    const errors = {
      email: validateEmail(formData.email) ? '' : 'Please enter a valid email address',
      password: validatePassword(formData.password) ? '' : 'Password must be at least 8 characters',
    };
    setFormErrors(errors);
    return !errors.email && !errors.password;
  };

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();

    if (!validate()) {
      return;
    }

    try {
      await login(formData);
      onSuccess?.();
      navigate(redirectTo);
    } catch (error) {
      // Error is handled by useAuth
    }
  };

  return (
    <form className="login-form" onSubmit={handleSubmit} noValidate>
      <div className="login-form__header">
        <h2>Welcome Back</h2>
        <p>Sign in to your account to continue</p>
      </div>

      {error && (
        <div className="login-form__error" role="alert">
          {error}
        </div>
      )}

      <Input
        type="email"
        name="email"
        value={formData.email}
        onChange={handleChange}
        label="Email Address"
        placeholder="you@example.com"
        error={formErrors.email}
        disabled={isLoading}
        required
        autoFocus
      />

      <Input
        type="password"
        name="password"
        value={formData.password}
        onChange={handleChange}
        label="Password"
        placeholder="Enter your password"
        error={formErrors.password}
        disabled={isLoading}
        required
      />

      <div className="login-form__actions">
        <Button
          type="submit"
          variant="primary"
          size="lg"
          loading={isLoading}
          disabled={isLoading}
          fullWidth
        >
          {isLoading ? 'Signing in...' : 'Sign In'}
        </Button>
      </div>

      <div className="login-form__footer">
        <Link to="/forgot-password" className="login-form__link">
          Forgot password?
        </Link>
        <span className="login-form__separator">|</span>
        <Link to="/register" className="login-form__link">
          Create account
        </Link>
      </div>
    </form>
  );
};

Page

// pages/auth/LoginPage.tsx
import { LoginForm } from '../../features/auth/components/LoginForm';
import { AuthLayout } from '../../layouts/AuthLayout/AuthLayout';

export const LoginPage: React.FC = () => {
  return (
    <AuthLayout>
      <div className="login-page">
        <div className="login-page__container">
          <div className="login-page__brand">
            <img src="/logo.svg" alt="Company Logo" />
            <h1>Company Name</h1>
          </div>
          <LoginForm redirectTo="/dashboard" />
        </div>
      </div>
    </AuthLayout>
  );
};

✅ Pros

Advantage	Description
Familiar	Most React developers understand this structure
Flexible	Easy to modify and adapt as requirements change
Balanced	Good mix of technical and feature organization
Low Learning Curve	Easy for new developers to understand
Scalable	Can grow with the application

❌ Cons

Disadvantage	Description
Less Opinionated	Can become messy without discipline
Feature Scattering	Auth logic spread across multiple folders
Co-location Issues	Related code not always together
Requires Discipline	Team needs to agree on conventions

🎯 Best For

Medium-sized Applications
Teams New to React Architecture
Projects requiring flexibility
Rapid Development with changing requirements

Comparison Table

Aspect	Atomic Design	Domain-Driven Design	Feature-Sliced Design	Hybrid
Primary Focus	UI Design System	Business Domains	Feature Boundaries	Balanced
Learning Curve	🟢 Easy	🟡 Medium	🔴 Hard	🟢 Easy
Scalability	🟡 Medium	🟢 High	🟢 Very High	🟡 Medium-High
Team Collaboration	🟢 High	🟢 Very High	🟢 Very High	🟡 Medium
Code Reusability	🟢 Very High	🟡 Medium	🟢 High	🟡 Medium
Separation of Concerns	🟡 Medium	🟢 High	🟢 Very High	🟡 Medium
Boilerplate	🟡 Medium	🔴 High	🔴 Very High	🟢 Low
Flexibility	🟡 Medium	🟢 High	🔴 Low	🟢 Very High
Best for App Size	Small-Medium	Medium-Large	Large-Enterprise	Small-Medium
Component Reusability	🟢 Excellent	🟡 Good	🟢 Excellent	🟡 Good
Business Logic Organization	🟡 Average	🟢 Excellent	🟢 Excellent	🟡 Average
Maintainability	🟡 Good	🟢 Very Good	🟢 Excellent	🟡 Good
Testing Ease	🟢 Easy	🟡 Medium	🟢 Easy	🟡 Medium

Which Approach Should You Choose?

🎯 Choose Atomic Design if:

You’re building a design system or UI library
Your app is UI-heavy with many shared components
You have dedicated UI/UX designers on your team
Your app size is Small to Medium
You value component reusability above all

🎯 Choose Domain-Driven Design if:

You have complex business logic with multiple domains
You have multiple teams working independently
You have a strong focus on business requirements
Your app size is Medium to Large
You want domain experts to understand the code

🎯 Choose Feature-Sliced Design if:

You’re building a large-scale enterprise application
You have a long-term project with many developers
You need strict architectural rules
Your app size is Large to Enterprise
You value maintainability above all

🎯 Choose Hybrid if:

You need a balanced approach
Your team is learning React architecture
Your project requirements may change
Your app size is Small to Medium
You want flexibility and familiarity

🚀 Recommendation

I recommend a combination approach for most React projects:

Start with the Hybrid structure for its simplicity and familiarity
Apply Atomic Design principles to your /components/ folder for consistency
Use Feature-based organization for /features/ with clear boundaries
Gradually adopt DDD if the business logic becomes complex

Example: Combining Approaches

/src/
  /components/          # Atomic Design principles here
    /atoms/
    /molecules/
    /organisms/
  
  /features/           # Feature-Sliced inspired
    /auth/             # DDD domain approach
      /components/
      /hooks/
      /services/
      /types/
  
  /shared/             # Shared utilities
    /ui/
    /utils/
    /constants/

Why This Works

Atomic Design ensures your UI components are consistent and reusable
Feature organization keeps related business logic together
DDD principles help manage complex business rules
Hybrid structure provides a familiar entry point

Getting Started

Start Simple: Begin with the Hybrid approach
Refine as You Grow: Add more structure as needed
Stay Consistent: Document your conventions
Review Regularly: Adapt as the project evolves

📚 Additional Resources

📝 License

💡 Feedback

If you have suggestions or improvements, please contribute!

See Contributing Guidelines

</a>

This site is open source. Improve this page.

React-Architecture-Approaches

React Architecture Approaches: A Comprehensive Guide

📖 Overview

What You’ll Learn

Table of Contents

1. Atomic Design Approach

🎯 Philosophy

📂 Complete Structure

💻 Example Code

Atom: Button Component

Molecule: SearchBar Component

Organism: Header Component

✅ Pros

❌ Cons

🎯 Best For

2. Domain-Driven Design (DDD) Approach

🎯 Philosophy

📂 Complete Structure

💻 Example Code

Domain Types

Domain Service

Domain Hook

Domain Component

✅ Pros

❌ Cons

🎯 Best For

3. Feature-Sliced Design (FSD) Approach

🎯 Philosophy

📂 Complete Structure

💻 Example Code

Shared Components

Entity Model

Feature Model

Feature Hook

Widget

Page

✅ Pros

❌ Cons

🎯 Best For

4. Hybrid Approach

🎯 Philosophy

📂 Complete Structure

💻 Example Code

Shared Component

Feature Service

Feature Hook

Feature Component

Page

✅ Pros

❌ Cons

🎯 Best For

Comparison Table

Which Approach Should You Choose?

🎯 Choose Atomic Design if:

🎯 Choose Domain-Driven Design if:

🎯 Choose Feature-Sliced Design if:

🎯 Choose Hybrid if:

🚀 Recommendation

Example: Combining Approaches

Why This Works

Getting Started

📚 Additional Resources

📝 License

💡 Feedback