docs: Update project structure documentation for clarity and guidelines
This commit is contained in:
parent
39a041180e
commit
ff6a199dc5
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue