# 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
Title
Content
```
### 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 Loading...
;
if (error) return Error fetching data!
;
return {user.name}
;
}
```