From ff6a199dc55ecdb0b94f8fdbb04b4e0c5f7ad87f Mon Sep 17 00:00:00 2001
From: Vishnu <vishnu@hexrfactory.com>
Date: Thu, 10 Apr 2025 17:02:36 +0530
Subject: [PATCH] docs: Update project structure documentation for clarity and
 guidelines

---
 app/docs/documents/projectStructure.md | 248 ++++++++++++++++++-------
 1 file changed, 176 insertions(+), 72 deletions(-)

diff --git a/app/docs/documents/projectStructure.md b/app/docs/documents/projectStructure.md
index 1e12346..234dabb 100644
--- a/app/docs/documents/projectStructure.md
+++ b/app/docs/documents/projectStructure.md
@@ -1,10 +1,13 @@
-# Project Folder Structure
+# **Project Folder Structure Maintenance**
 
-This document provides a detailed description of the purpose of each folder in the project by root level, along with the folder hierarchy.
+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
+---
+
+## **Folder Hierarchy**
 
 ```
+📁 .github
 📁 src
 ├── 📁 assets
 ├── 📁 components
@@ -14,94 +17,195 @@ This document provides a detailed description of the purpose of each folder in t
 │   ├── 📁 builder
 │   ├── 📁 simulation
 │   └── 📁 visualization
+├── 📁 pages
 ├── 📁 services
 ├── 📁 store
 ├── 📁 styles
 ├── 📁 tests
 ├── 📁 types
 ├── 📁 utils
+├── 📁 temp
 ├── App.css
 ├── App.tsx
 ├── index.css
 ├── main.tsx
-└── vite-env.d.ts
+├── Dockerfile
+└── nginx.conf
 ```
 
 ---
 
-## Description of Each Folder
+## **Folder and File Descriptions**
 
-### 📁 `src`
-The root directory for all source code related to the application.
-
-#### 📁 `assets`  
-- **Purpose:** Contains static assets such as images, icons, fonts, or other resources.  
-- **Example:**  
-  - `react.svg`: A static SVG file used in the project.
-
-#### 📁 `components`  
-- **Purpose:** Contains reusable React components, serving as building blocks for the user interface.  
-- **Example:**  
-  - Buttons, modals, headers, and forms.
-
-#### 📁 `functions`  
-- **Purpose:** Stores pure functions or logic that can be reused across the application.  
-- **Example:**  
-  - Utility functions for data transformation or computation.
-
-#### 📁 `hooks`  
-- **Purpose:** Holds custom React hooks for managing specific logic or behaviors.  
-- **Example:**  
-  - Hooks for state management, API calls, or reusable effects.
-
-#### 📁 `modules`  
-- **Purpose:** Organizes high-level, feature-specific code into subdirectories.  
-  - **📁 builder:** Manages functionalities and components related to building or configuring features.  
-  - **📁 simulation:** Handles processes or logic related to simulations or dynamic scenarios.  
-  - **📁 visualization:** Focuses on displaying data visually, such as charts, graphs, or interactive UI elements.
-
-#### 📁 `services`  
-- **Purpose:** Encapsulates external service interactions, such as API calls or library integrations.  
-- **Example:**  
-  - REST API clients or authentication handlers.
-
-#### 📁 `store`  
-- **Purpose:** Contains state management logic and configurations for tools like Redux or Zustand.  
-- **Example:**  
-  - Redux slices, context providers, or global state stores.
-
-#### 📁 `styles`  
-- **Purpose:** Includes global CSS, SCSS, or theming resources.  
-- **Example:**  
-  - Global styles, theme variables, or resets.
-
-#### 📁 `tests`  
-- **Purpose:** Stores test files for unit testing, integration testing, and mock data.  
-- **Example:**  
-  - Test files (`*.test.tsx`, `*.spec.ts`) or mock utilities.
-
-#### 📁 `types`  
-- **Purpose:** Contains shared TypeScript type definitions and interfaces.  
-- **Example:**  
-  - Type declarations for props, data models, or API responses.
-
-#### 📁 `utils`  
-- **Purpose:** Includes general-purpose utility files that don’t fit into other specific folders.  
-- **Example:**  
-  - Helper functions like debouncers or date formatters.
+### 📁 **`src`**
+The root directory for all application source code.
 
 ---
 
-## Root-Level Files
+### 📁 **`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`).
 
-### `App.tsx`
-- **Purpose:** The root React component, initializing the main application layout and logic.
+---
 
-### `index.css`
-- **Purpose:** Contains global styles applied throughout the application.
+### 📁 **`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/`).
 
-### `main.tsx`
-- **Purpose:** The entry point of the app, rendering the React application and setting up the React DOM.
+---
 
-### `vite-env.d.ts`
-- **Purpose:** TypeScript environment configuration file for Vite.
+### 📁 **`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.