# Project Development Guidelines

**Version**: 1.0  
**Last Updated**: July 1, 2025

## 1\. Introduction

This document provides the official guidelines for developing this application. Its purpose is to ensure a consistent, maintainable, and high-quality codebase. Adhering to these standards is mandatory for all contributors.

---

## 2\. Project Structure

We use a **feature-based structure** to ensure modularity and scalability.

```
/
├── src/
│   ├── assets/
│   ├── components/        # Only for shared components (e.g., App Layout, Button)
│   ├── config/
│   ├── contexts/
│   ├── features/          # Main directory for all application features
│   │   ├── authentication/
│   │   │   ├── api/
│   │   │   │   └── authAPI.ts
│   │   │   ├── components/
│   │   │   │   └── LoginForm.tsx
│   │   │   ├── hooks/
│   │   │   │   └── useAuth.ts
│   │   │   ├── routes/
│   │   │   │   └── LoginPage.tsx  # The main entry point for this feature's route
│   │   │   └── types.ts
│   │   │
│   │   └── products/
│   │       ├── api/
│   │       │   └── productsAPI.ts
│   │       ├── components/
│   │       │   ├── ProductCard.tsx
│   │       │   └── ProductGrid.tsx
│   │       ├── routes/
│   │       │   └── ProductListPage.tsx
│   │       └── index.ts
│   │
│   ├── hooks/             # Only for global hooks
│   ├── lib/               # For external library configurations (e.g., axios instance)
│   ├── providers/         # A single place for all context providers
│   ├── routes/            # Central route configuration
│   │   └── index.tsx
│   ├── types/             # Only for global types
│   ├── App.tsx
│   └── main.tsx
│
```

- **`src/features/`**: All code related to a specific business feature (e.g., `authentication`, `products`, `user-profile`) resides within its own folder here. Each feature folder should contain its own `components`, `hooks`, `api`, `types`, and `routes`.
- **`src/components/`**: This directory is **only** for truly generic, shared UI components that are used across multiple features (e.g., `Button`, `Layout`, `Logo`).
- **`src/lib/`**: For configuring and exporting instances of third-party libraries (e.g., an `axios` client).
- **`src/providers/`**: A single location to compose all React Context providers (`AuthProvider`, `ThemeProvider`, etc.).
- **`src/routes/`**: The central routing configuration, which lazy-loads page components from the `features` directory.
- **`src/theme/`**: Contains the MUI theme definition and global styles.

---

## 3\. Naming Conventions

Consistent naming is critical for readability.

- **Files**:
  - **Components**: **`PascalCase.tsx`** (e.g., `ProductCard.tsx`)
  - **Hooks**: **`useCamelCase.ts`** (e.g., `useDebounce.ts`)
  - **All other `.ts` files**: **`camelCase.ts`** (e.g., `authService.ts`)

- **Components**: **`PascalCase`**. The component function name must match the filename.

  ```tsx
  // src/components/SubmitButton.tsx
  function SubmitButton() {
    // ...
  }
  ```

- **Variables and Functions**: **`camelCase`**.

  ```typescript
  const userCount = 10;
  function getUserProfile() {
    /* ... */
  }
  ```

- **Constants**: **`UPPER_SNAKE_CASE`**. For constant values that are hardcoded and reused.

  ```typescript
  const MAX_LOGIN_ATTEMPTS = 5;
  ```

- **Types and Interfaces**: **`PascalCase`**.

  ```typescript
  interface UserProfile {
    userId: string;
    displayName: string;
  }
  ```

---

## 4\. Coding Best Practices

- **Functional Components**: All components **must** be functional components using React Hooks. Class components are not permitted.
- **TypeScript**: Use TypeScript's features to your advantage. Avoid `any` whenever possible. Define clear types and interfaces for props, API responses, and complex objects.
- **Props**: Always define props with a `type` or `interface`. Use destructuring in the component signature for clarity.

  ```tsx
  interface UserCardProps {
    name: string;
    avatarUrl: string;
  }

  function UserCard({ name, avatarUrl }: UserCardProps) {
    // ...
  }
  ```

- **Imports**: Use absolute paths with the `@/` alias for cleaner imports.
- **DRY (Don't Repeat Yourself)**: If you use a piece of logic more than twice, abstract it into a custom hook. If you use a piece of JSX more than twice, create a reusable component.

---

## 5\. State Management

- **Local State**: `useState` and `useReducer` are the default choices for component-level state.
- **Shared State**: For state that needs to be shared across the application (e.g., user authentication, theme), use the **React Context API**.

---

## 6\. Styling

Styling is handled by **Material-UI (MUI)**.

- For creating new, reusable, styled components, use the **`styled()` utility** from MUI.
- For one-off style adjustments or layout overrides, use the **`sx` prop**.

---

## 7\. Component Documentation (Storybook)

All shared UI components in the `src/components` directory **must** be documented using **Storybook**. This creates a living style guide, allows for isolated component development, and makes it easy for all developers to discover and use existing components.

Each component folder should contain a `*.stories.tsx` file.

---

## 8\. Code Comments

- **Comment the _Why_, Not the _What_**: Your code should be self-documenting. Use comments to explain _why_ a complex or non-obvious piece of code exists.

  ```typescript
  // Bad comment
  // Increment the counter
  counter++;

  // Good comment
  // We need to pre-increment the counter to account for the zero-based index of the array.
  ++preemptiveCounter;
  ```

- **JSDoc**: Use JSDoc blocks for all exported functions and custom hooks to enable better editor IntelliSense.
  ```typescript
  /**
   * Fetches a user profile from the API.
   * @param userId - The ID of the user to fetch.
   * @returns The user profile object or null if not found.
   */
  ```

---

## 9\. Git Workflow

We use a simplified GitFlow model.

1.  **Create a Branch**: All work must be done on a feature branch, named descriptively (e.g., `feat/login-page`, `fix/header-bug`).
2.  **Commit Often**: Make small, logical commits. Commit messages **must** follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification (e.g., `feat:`, `fix:`, `docs:`, `chore:`).
3.  **Create a Pull Request (PR)**: When the feature is complete, create a PR against the `main` branch.
4.  **Code Review**: At least one other team member must review and approve the PR.
5.  **Merge**: Once approved and all checks pass, the PR can be merged.

---

## 10\. Pre-Commit Checklist

Before creating a Pull Request, ensure you have:

- ✅ Formatted the entire codebase: `npm run format`
- ✅ Passed all linter checks: `npm run lint`
- ✅ Documented any new shared components in Storybook.

---

## 11\. Design Patterns

Design patterns are reusable solutions to common problems within a given context. Here are the key patterns we will use in this React project.

### Component Design Patterns

- **Container/Presentational Pattern (Smart/Dumb Components)**
  - **Concept**: Separate the "how things work" from the "how things look."
  - **Container (Smart) Component**: Manages state, fetches data, and contains business logic. It doesn't have many styles.
  - **Presentational (Dumb) Component**: Receives data via props and simply renders UI. It contains no business logic.
  - **Example**: A `UserProfilePage` (container) fetches user data and passes it to a `UserProfileCard` (presentational) to display.

- **Composition Pattern**
  - **Concept**: Build complex components by combining simpler, more generic ones. This is React's core philosophy.
  - **Example**: Using the `children` prop to create a generic `Card` component that can wrap any content:
  ```tsx
  <Card>
    <h2>Title</h2>
    <p>Content</p>
  </Card>
  ```

### State Management Patterns

- **Provider Pattern**
  - **Concept**: Make data available to a deep tree of components without having to pass props down manually at every level.
  - **How we use it**: This is the pattern that powers the React Context API. Our `AuthProvider`, `ThemeProvider`, and `CustomThemeProvider` all use this pattern to provide authentication status and theme information to any component that needs it.

### Reusable Logic Patterns

- **Custom Hooks**
  - **Concept**: The modern, standard way to share stateful logic between components.
  - **How we use it**: By extracting logic into a function whose name starts with `use` (e.g., `useAuth`, `useTheme`), we can reuse that logic in any component without repeating code. This is the preferred replacement for older patterns like HOCs and Render Props.

### Memoization Pattern

- **Concept**: A performance optimization technique to prevent unnecessary re-renders and expensive re-calculations by caching results. React provides three main tools for this.

- **Best For**: Improving the performance of applications with complex components, large lists, or frequent state updates.

- **The Tools**:
  - **`React.memo`**: A higher-order component that prevents a component from re-rendering if its props haven't changed.
  - **`useMemo`**: A hook that caches the result of an expensive calculation. It only re-computes the value when its dependencies change.
  - **`useCallback`**: A hook that caches a function definition. This is useful for preventing child components from re-rendering when you pass functions down as props.

### Custom Data Fetching Hook

- **Concept**: A custom hook that abstracts all the logic for fetching data from an API. It typically manages the loading, error, and data states internally.

- **Best For**: Simplifying data fetching in your components, eliminating repetitive `useEffect` logic, and creating a consistent way to handle API requests across your app.

- **How it looks**: Components become much cleaner and focused on displaying the data.

  ```tsx
  function UserProfile({ userId }) {
    const { data: user, isLoading, error } = useFetch(`/api/users/${userId}`);

    if (isLoading) return <div>Loading...</div>;
    if (error) return <div>Error fetching data!</div>;

    return <div>{user.name}</div>;
  }
  ```
