Frontend repository for Software Engineering project, built with React, Material-UI (MUI), Vite, and Lodash.
src/
├── apis/ # API endpoints and HTTP requests
├── assets/ # Static files, data, icons, and illustrations
├── auth/ # Authentication logic and context
├── components/ # Reusable UI components
├── hooks/ # Custom React hooks
├── layouts/ # Page layout templates
├── pages/ # Page components with metadata
├── routes/ # Routing configuration
├── sections/ # View sections and page content
├── theme/ # MUI theme customization
└── utils/ # Utility functions and helpers
Contains all API endpoint definitions and HTTP request handlers using Axios, including:
- Backend server API endpoints
- Third-party API integrations (e.g., Amap administrative region API)
├── apis
│ └── index.js # Centralized API management (recommended for all endpoints)
Best Practice: Consolidate all API endpoints in index.js for easier maintenance.
Stores static files, regional data, icons, and illustrations.
├── assets
│ ├── data/ # Static data files
│ │ ├── countries.js
│ │ └── index.js
│ ├── icons/ # Custom icon components
│ │ ├── email-inbox-icon.jsx
│ │ ├── new-password-icon.jsx
│ │ ├── password-icon.jsx
│ │ ├── plan-free-icon.jsx
│ │ ├── plan-premium-icon.jsx
│ │ ├── plan-starter-icon.jsx
│ │ └── sent-icon.jsx
│ └── illustrations/ # SVG illustration components
│ ├── avatar-shape.jsx
│ ├── background-shape.jsx
│ ├── booking-illustration.jsx
│ ├── forbidden-illustration.jsx
│ ├── page-not-found-illustration.jsx
│ └── ...
Note: Unused files will be cleaned up based on project requirements.
Handles authentication logic, including login, registration, token management, and third-party authentication.
├── auth
│ ├── context/
│ │ └── jwt/
│ │ ├── auth-consumer.jsx
│ │ ├── auth-context.js
│ │ ├── auth-provider.jsx # Handles login, registration, and verification
│ │ ├── index.js # Export barrel
│ │ └── utils.js # Token storage, persistence, and expiration
│ └── hooks/
│ ├── index.js
│ └── use-auth-context.js
Features:
- Form submission and validation
- Custom error handling
- Token persistence and expiration management
- Future support for third-party authentication
Reusable UI components encapsulated for use throughout the application.
├── components
│ ├── city-cascader/ # Region selection cascader
│ │ ├── city-cascader.jsx # Component implementation
│ │ ├── index.js # Export barrel
│ │ └── utils.js # Administrative region fetch functions
│ ├── hook-form/ # React Hook Form + MUI components
│ │ ├── form-provider.jsx
│ │ ├── index.js
│ │ ├── rhf-select.jsx
│ │ └── rhf-text-field.jsx
│ ├── iconify/ # Icon animation wrapper
│ │ ├── iconify.jsx
│ │ └── index.js
│ ├── loading-screen/ # Loading and splash screens
│ │ ├── index.js
│ │ ├── loading-screen.jsx
│ │ └── splash-screen.jsx
│ ├── logo/ # Logo component
│ │ ├── index.js
│ │ └── logo.jsx
│ └── settings/ # Theme settings context
│ ├── context/
│ │ ├── index.js
│ │ ├── settings-context.js
│ │ └── settings-provider.jsx
│ └── index.js
Note: Most MUI-wrapped components should be used as-is unless specific business requirements necessitate modifications. When adding new components from templates, remember to update this documentation.
Custom React hooks and MUI-provided hooks for common functionalities.
├── hooks
│ ├── use-boolean.js
│ ├── use-copy-to-clipboard.js
│ ├── use-countdown.js
│ ├── use-debounce.js
│ ├── use-double-click.js
│ ├── use-event-listener.js
│ ├── use-local-storage.js
│ ├── use-mocked-user.js
│ ├── use-off-set-top.js
│ ├── use-responsive.js
│ └── use-scroll-to-top.js
Recommendation: Understand the usage of each hook for effective implementation.
Page layout templates managing CSS and styling using MUI's JSX-inline styling approach.
├── layouts
│ ├── auth/
│ │ └── classic.jsx # Unified auth layout for login/register
│ ├── main/ # Main layout (to be implemented)
│ │ └── modern.jsx # Modern layout variant (to be implemented)
│ └── config-layout.js # Global layout configuration
Development Pattern: Future layouts should follow the structure shown above. CSS is written directly in JSX components using MUI's styling system.
Combines page <title> metadata with view components for optimized rendering. Pages are exported and combined with layouts in the routes section.
├── pages
│ ├── Home/ # Placeholder (to be redesigned)
│ │ └── index.jsx
│ ├── Layout/ # Placeholder (to be removed)
│ │ ├── index.jsx
│ │ └── index.scss
│ └── auth/
│ ├── login.jsx
│ └── register.jsx
Note: Temporary placeholder pages will be removed or refactored as development progresses.
Combines page components with layout components to create route configurations.
├── routes
│ ├── components/ # MUI routing components
│ │ ├── index.js
│ │ └── router-link.jsx
│ ├── hooks/ # MUI routing hooks
│ │ ├── index.js
│ │ ├── use-active-link.js
│ │ ├── use-params.js
│ │ ├── use-pathname.js
│ │ ├── use-router.js
│ │ └── use-search-params.js
│ ├── paths.js # ⚠️ IMPORTANT: Centralized route path definitions
│ └── sections/ # Route section assembly
│ ├── auth.jsx
│ └── index.jsx
Key File: paths.js manages all page routes centrally for easy maintenance.
Contains view implementations (HTML + JS logic) that are exported for use in pages.
├── sections
│ ├── Home/ # Placeholder (to be renamed for main page)
│ └── auth/
│ └── jwt/
│ ├── index.js
│ ├── jwt-login-view.jsx
│ └── jwt-register-view.jsx
Purpose: Implements the actual UI views and business logic for each section.
MUI theme customization files. Modify here to change the application's visual theme.
├── theme
│ ├── css.js
│ ├── custom-shadows.js
│ ├── index.jsx
│ ├── overrides/
│ │ ├── components/ # Component-specific style overrides
│ │ │ ├── accordion.js
│ │ │ ├── alert.js
│ │ │ ├── button.js
│ │ │ ├── card.js
│ │ │ ├── textfield.js
│ │ │ └── ...
│ │ ├── default-props.jsx
│ │ └── index.js
│ ├── palette.js # Color palette configuration
│ ├── shadows.js # Shadow definitions
│ └── typography.js # Typography settings
Reference: See MUI Theme Documentation for customization guidelines.
Utility functions and helpers used throughout the application.
└── utils
├── axios.js # ⚠️ IMPORTANT: HTTP client with interceptors
├── change-case.js # Case transformation utilities
├── format-time.js # Time formatting utilities
├── highlight.js # Syntax highlighting utilities
├── storage-available.js # Storage availability checker
└── zh-en.js # Chinese-English region name conversion
Key File: axios.js contains GET, POST, DELETE methods and custom error handling.
┌─────────────────────────────────────────────────────────────┐
│ User Request │
└─────────────────────────┬───────────────────────────────────┘
│
▼
┌───────────────┐
│ Routes │
│ (paths.js) │
└───────┬───────┘
│
▼
┌───────────────┐
│ Pages │
│ + Layouts │
└───────┬───────┘
│
▼
┌───────────────┐
│ Sections │
│ (Views) │
└───────┬───────┘
│
┌─────────┴─────────┐
│ │
▼ ▼
┌───────────┐ ┌───────────┐
│Components │ │ APIs │
│ + Hooks │ │ (Axios) │
└───────────┘ └─────┬─────┘
│
▼
┌──────────────┐
│ Backend │
│ Server │
└──────────────┘
┌──────────────┐
│ Auth Context│────────┐
└──────────────┘ │
▼
┌──────────────┐ ┌────────────┐
│Theme Settings│───▶│ Pages │
└──────────────┘ └────────────┘
│
┌──────────────┐ │
│ Custom Hooks │◀───────┘
└──────────────┘
- Component Reusability: Encapsulate common UI patterns in the
components/directory - Centralized API Management: Keep all API calls in
apis/index.js - Route Organization: Use
paths.jsfor all route definitions - MUI Best Practices: Leverage MUI's built-in components and customization system
- Minimal Custom CSS: Use MUI's sx prop and styled components instead of separate CSS files
-
Adding New Pages:
- Create view in
sections/ - Create page component in
pages/ - Add route in
routes/sections/ - Register path in
routes/paths.js
- Create view in
-
Adding New Components:
- Create component in
components/ - Export through
index.jsbarrel file - Document any new dependencies or usage patterns
- Create component in
-
API Integration:
- Define endpoint in
apis/index.js - Use Axios instance from
utils/axios.js - Handle errors using custom error handlers
- Define endpoint in
- Node.js 16.x or higher
- npm or yarn package manager
# Clone the repository
git clone https://github.com/yourusername/web_frontend.xjco2913.git
# Navigate to project directory
cd web_frontend.xjco2913
# Install dependencies
npm install
# or
yarn install
# Start development server
npm run dev
# or
yarn devCreate a .env file in the root directory:
VITE_API_URL=http://localhost:8080/api
VITE_AMAP_KEY=your_amap_api_keyThis project adopts a subtractive approach based on MUI templates:
- Start with comprehensive MUI templates
- Remove unnecessary components and features
- Add custom components only when business requirements demand them
- Focus on understanding the project structure before implementing features
Most Important: Understanding the project structure is key to effective development. Follow the established patterns and conventions for consistency.
- Follow the existing directory structure and naming conventions
- Update documentation when adding new features or components
- Keep components modular and reusable
- Write meaningful commit messages
- Test thoroughly before submitting pull requests
This project is licensed under the MIT License - see the LICENSE file for details.