# **Project Folder Structure Maintenance**

This document outlines the project’s folder structure, describing the purpose of each folder and file. It also includes guidelines for development, collaboration, and scalability.

---

## **Folder Hierarchy**

```
📁 .github
📁 src
├── 📁 assets
├── 📁 components
├── 📁 functions
├── 📁 hooks
├── 📁 modules
│   ├── 📁 builder
│   ├── 📁 simulation
│   └── 📁 visualization
├── 📁 pages
├── 📁 services
├── 📁 store
├── 📁 styles
├── 📁 tests
├── 📁 types
├── 📁 utils
├── 📁 temp
├── App.css
├── App.tsx
├── index.css
├── main.tsx
├── Dockerfile
└── nginx.conf
```

---

## **Folder and File Descriptions**

### 📁 **`src`**
The root directory for all application source code.

---

### 📁 **`assets`**
- **Purpose:** Static assets like images, fonts, and icons.  
- **Examples:**  
  - Subfolders for `images`, `icons`, and `fonts`.  
  - Use descriptive file names (e.g., `logo.svg`, `Roboto-Regular.ttf`).

---

### 📁 **`components`**
- **Purpose:** Reusable React components forming the building blocks of the UI.  
- **Examples:**  
  - Buttons, modals, input fields, and headers.  
  - Organize larger components into folders (e.g., `Button/`).

---

### 📁 **`functions`**
- **Purpose:** Pure functions and reusable logic.  
- **Examples:**  
  - `formatDate.ts`: Format dates into readable strings.  
  - `calculateTotal.ts`: Logic for cart total calculation.

---

### 📁 **`hooks`**
- **Purpose:** Custom React hooks encapsulating reusable logic.  
- **Examples:**  
  - `useAuth.ts`: Manages authentication logic.  
  - `useFetch.ts`: Fetches data from APIs.

---

### 📁 **`modules`**
- **Purpose:** Feature-specific code organized into subfolders.  
- **Subfolders:**  
  - **`builder`**: For UI components and logic related to building features.  
  - **`simulation`**: Code for running simulations.  
  - **`visualization`**: Visualization components like charts and graphs.

---

### 📁 **`pages`**
- **Purpose:** Pages that represent routes in the application.  
- **Examples:**  
  - `HomePage.tsx`: Home route.  
  - `DashboardPage.tsx`: Dashboard route.

---

### 📁 **`services`**
- **Purpose:** External API interactions and third-party service logic.  
- **Examples:**  
  - `apiClient.ts`: Wrapper for HTTP requests.  
  - `authService.ts`: Authentication services.

---

### 📁 **`store`**
- **Purpose:** State management logic using tools like Redux or Context API.  
- **Examples:**  
  - `authSlice.ts`: Authentication-related state management.  
  - `cartSlice.ts`: Shopping cart state management.

---

### 📁 **`styles`**
- **Purpose:** Global and modular styles.  
- **Examples:**  
  - `global.css`: Global styles.  
  - `theme.scss`: Theme variables.

---

### 📁 **`tests`**
- **Purpose:** Test files for unit, integration, and E2E testing.  
- **Examples:**  
  - `Button.test.tsx`: Tests for the `Button` component.  
  - `mockData.ts`: Mock API responses.

---

### 📁 **`types`**
- **Purpose:** Shared TypeScript type definitions and interfaces.  
- **Examples:**  
  - `User.ts`: User-related type definitions.  
  - `ApiResponse.ts`: API response types.

---

### 📁 **`utils`**
- **Purpose:** General-purpose utility functions and constants.  
- **Examples:**  
  - `debounce.ts`: Debounce function.  
  - `constants.ts`: Shared constants.

---

### 📁 **`temp`**
- **Purpose:** A temporary directory for experimental or work-in-progress code.  
- **Guidelines:**  
  - This folder is included in `.gitignore` to prevent its contents from affecting the main project.  
  - Move any experimental work here to isolate it from production-ready code.  

---

### **Root-Level Files**

- **`App.tsx`**: Root React component.  
- **`main.tsx`**: Entry point for the app.  
- **`Dockerfile`**: Docker configuration for containerizing the application.  
- **`nginx.conf`**: Configuration for the Nginx server.

---

## **Development Guidelines**

### **Environment Management**
- **`.env.local`**: Use this file for testing and development-specific variables.  
- **`.env`**: Should only contain variables required for deployed services (e.g., API base URLs).  

### **Collaboration Best Practices**
1. **Use the `temp` Folder for Experiments:**  
   Any experimental work should be isolated in the `temp` folder. Avoid committing temporary code to the main repository.  

2. **Documentation:**  
   - Read the shared documentation in the `docify` and `.github` folders before starting work.  
   - Follow any guidelines or standards outlined in these documents.  

3. **Branching Rules:**  
   - Do not merge other branches into your branch without proper code review or necessity.  
   - Use meaningful branch names (e.g., `feature/auth-module`, `fix/header-bug`).  

4. **Code Reviews:**  
   - Ensure all code undergoes peer review before merging.  
   - Use PR templates provided in the `.github` folder to document changes.  

---

## **Additional Instructions for Large-Scale Projects**

1. **Folder Depth:**  
   - Avoid excessive nesting of folders to maintain simplicity.  
   - Refactor large folders into modules or domains as the project scales.

2. **Dependency Management:**  
   - Regularly review and update dependencies.  
   - Remove unused or deprecated libraries to reduce technical debt.

3. **Automate Workflows:**  
   - Use CI/CD pipelines to automate testing, building, and deployment processes.  
   - Integrate tools like Prettier, ESLint, and Husky to enforce code quality.

4. **Versioning and Change Logs:**  
   - Maintain a changelog to track major updates.  
   - Use semantic versioning (`x.y.z`) for releases.

5. **Performance Monitoring:**  
   - Regularly monitor and optimize app performance.  
   - Use tools like Lighthouse, React DevTools, and browser profilers.

6. **Error Handling:**  
   - Centralize error handling using utilities or middleware.  
   - Log errors in both the frontend and backend for debugging.

7. **Documentation:**  
   - Continuously update this document to reflect structural or procedural changes.  
   - Ensure all team members are familiar with the documentation.