Dwinzo_dev/app/docs/documents/projectStructure.md

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.