212 lines
6.4 KiB
Markdown
212 lines
6.4 KiB
Markdown
# **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.
|