Repository files navigation

Welcome toFusion Electronics, aMERN-Stack E-commerce Application! This project is a working demo of a full-stack web application that was built using the MERN stack (MongoDB, Express.js, React.js, Node.js). Additionally, it also includes features such as user authentication, checkout process, product recommendations with vector search, and more!

It also aims to provide a comprehensive example of building a modern e-commerce platform, covering frontend user interface, backend server logic, database management, and integration with third-party libraries. Let's dive in!

1. Introduction
2. Live Deployment
3. User Interface
   • Home Page
   • Full Product List
   • Cart Page
   • Checkout Page
4. Features
5. Technologies Used
6. Getting Started
   • Prerequisites
   • Installation
7. Project Structure
8. Running the Application
9. Product Recommendations with Vector Database
10. Testing the APIs
11. Unit & Integration Testing
    • Backend Tests
    • Frontend Tests
12. Swagger API Documentation
13. OpenAPI Specification
    • Using theopenapi.yaml File
14. Deployment
15. Containerization
16. GitHub Actions & CI/CD
17. Contributing
18. License
19. Creator

This project is a demonstration of building an e-commerce application using the MERN stack, which consists of MongoDB (database), Express.js (server), React.js (frontend), and Node.js (runtime environment). The application allows users to browse products, add them to a shopping cart, proceed to checkout, and simulate the order processing. It includes comprehensive validations for user inputs and simulates the checkout process on the backend.

The application is designed to be user-friendly and responsive, providing a seamless shopping experience. It also includes features such as product search, user authentication, and order confirmation. Additionally, it uses Pinecone (with optional Weaviate support) for product recommendations based on vector search, enhancing the user experience by suggesting relevant products.

The application is deployed live on Vercel. You can access it at the following URL:Fusion Electronics App.

Theprimary backend server is deployed on Vercel and can be accessed at the following URL:Fusion Electronics API.

Thebackup backend server is deployed on Render and can be accessed at the following URL:Fusion Electronics API.

• Product Management:

  • View a list of products.
  • View detailed product information.
  • Add products to the shopping cart.

• Shopping Cart:

  • View items in the shopping cart.
  • Remove items from the cart.
  • Calculate total amount of items in the cart.

• Checkout Process:

  • Enter billing, shipping, and payment information.
  • Client-side credit card validation:
    • Luhn algorithm validation for card number verification
    • Automatic card type detection (Visa, Mastercard, Amex, Discover, Diners Club, JCB)
    • Real-time validation with visual error feedback
    • Expiry date validation (checks for valid month and ensures card hasn't expired)
    • CVC validation (3 digits for most cards, 4 for American Express)
    • Email format validation
  • Simulate the order creation process on the backend.
  • Receive confirmation of order success.

• User Authentication:

  • User registration and login.
  • Password hashing for security.
  • Protected routes for authenticated users.
  • JWT-based authentication.
  • Forgot and reset password functionality.
  • User profile management (view and update profile information).
  • Order history (view past orders).

• Product Recommendations:

  • Vector-based product recommendations using Pinecone (with optional Weaviate support).
  • Similar products displayed on product detail pages.

• Search Functionality:

  • Search products by name, description, brand, or category.
  • Real-time search suggestions.
  • Filter and sort search results.
  • Pagination for search results.
  • Debounced search input to optimize performance.

• Order Tracking:

  • View order status and details.
  • Get estimated delivery date and tracking information.

• Terms of Service & Privacy Policy:

  • Inform users about terms of service and privacy policy.

• Support Page:

  • Provide contact information and support resources.
  • FAQ section.
  • Contact form for user inquiries.

• Responsive Design:

  • Mobile-friendly layout.
  • Responsive components for various screen sizes.

• Frontend:

  • React.js
  • Material-UI for styling
  • Axios for API requests
  • react-credit-cards-2 for credit card visualization
  • react-router-dom for routing
  • react-hook-form for form validation
  • react-toastify for toast notifications
  • Jest and React Testing Library for testing

• Backend:

  • Node.js
  • Express.js
  • MongoDB (with Mongoose ODM)
  • Axios for external API requests
  • JsonWebToken for user authentication
  • Bcrypt for password hashing
  • Dotenv for environment variables
  • Cors for cross-origin resource sharing
  • Swagger for API documentation
  • Nodemon for server hot-reloading
  • Middleware: JWT for securing API endpoints
  • Pinecone andWeaviate for product recommendations with vector databases
  • FAISS & LangChain for efficient similarity search
  • Jest for unit and integration testing
  • Supertest for API endpoint testing
  • Cross-env for setting environment variables in scripts

• Development Tools:

  • Jetbrains WebStorm (IDE)
  • Postman (for API testing)
  • Git (version control)
  • npm (package manager)
  • Docker (for containerization)
  • GitHub Actions (for CI/CD)
  • Vercel and Render (for deployment)

The project is organized into two main "stacks": The backend is in thebackend directory that hosts all product & order data and the frontend is in theroot directory. Here is an overview of the project structure:

fullstack-ecommerce/├── backend/                       # Node.js server files│   ├── config/                    # Configuration files│   │   └── db.js                  # Database connection│   ├── docs/│   │   └── swagger.js             # Swagger API documentation setup│   ├── models/                    # Mongoose models│   │   ├── user.js                # User schema│   │   └── product.js             # Product schema│   ├── routes/                    # Route handlers│   │   ├── products.js            # Product routes│   │   ├── search.js              # Search routes│   │   └── checkout.js            # Checkout routes│   ├── middleware/                # Middleware functions│   │   ├── auth.js                # Authentication middleware│   ├── scripts/                   # Scripts for various tasks│   │   ├── build-faiss-index.js   # Script to build FAISS index│   │   ├── search-faiss-index.js  # Script to search FAISS index│   │   ├── query-weaviate.js      # Script to query Weaviate│   │   ├── weaviate-upsert.js     # Script to upsert products to Weaviate│   │   ├── sync-weaviate.js       # Script to synchronize products with Weaviate│   │   └── sync-pinecone.js       # Script to synchronize products with Pinecone│   ├── seed/                      # Database seed data│   │   └── productSeeds.js        # Product seed data│   ├── services/                  # Shared services (e.g., Pinecone sync helpers)│   ├── weaviateClient.js          # Weaviate client setup│   ├── pineconeClient.js          # Pinecone client setup│   ├── faiss.sh                   # FAISS index setup script│   ├── .env                       # Environment variables│   └── index.js                   # Server entry point├── public/                        # Frontend public assets│   ├── index.html                 # HTML template│   ├── manifest.json              # Web app manifest│   └── favicon.ico                # Favicon├── src/                           # React.js frontend files│   ├── components/                # Reusable components│   │   ├── CheckoutForm.jsx       # Checkout form component│   │   ├── ProductCard.jsx        # Product card component│   │   ├── NavigationBar.jsx      # Navigation bar component│   │   ├── OrderConfirmation.jsx  # Order confirmation component│   │   ├── ProductListing.jsx     # Product listing component│   │   ├── SearchResults.jsx      # Search results component│   │   └── ShoppingCart.jsx       # Shopping cart component│   ├── dev/                       # Development utilities│   │   ├── index.js               # Development entry point│   │   ├── palette.jsx            # Color palette│   │   ├── preview.jsx            # Component preview│   │   └── useInitials.js         # Initials hook│   ├── pages/                     # Page components│   │   ├── Cart.jsx               # Cart page component│   │   ├── Checkout.jsx           # Checkout page component│   │   ├── Home.jsx               # Home page component│   │   ├── ProductDetails.jsx     # Product details page component│   │   ├── OrderSuccess.jsx       # Order success page component│   │   ├── ProductDetails.jsx     # Product details page component│   │   └── Shop.jsx               # Shop page component│   ├── App.jsx                    # Main application component│   ├── App.css                    # Main application styles│   └── index.js                   # React entry point├── build/                         # Frontend production build files├── tests/                         # Test files├── .gitignore                     # Git ignore file├── package.json                   # NPM package file├── jsconfig.json                  # JS config file└── setupProxy.js                  # Proxy configuration(... and more files not listed here ...)

Before running this project, ensure you have the following installed:

• Node.js (with npm)
• MongoDB (with either local or remote instance)
• Git

1. Clone the repository:

   git clone https://github.com/hoangsonww/MERN-Stack-Ecommerce-App.gitcd MERN-Stack-Ecommerce-App# Fix the path if necessary

2. Install project dependencies:

   # Install server (backend) dependenciescd backendnpm install# Note: If you encounter any issues with the backend/package-lock.json not updating, run the following command from root directory:npm install --no-workspaces --prefix backend# Install client (frontend) dependenciescd ..npm install

3. Set up the backend:

   • Create a.env file in thebackend/ directory and add the following environment variable (replace the URI with your MongoDB connection string):

     MONGO_URI=mongodb://localhost:27017/Ecommerce-ProductsJWT_SECRET=your_secret_key

     For your information, I am using MongoDB Atlas for this project. You can create a free account and get your connection string from there if you want to deploy the application to the cloud.

   • Ensure that your MongoDB server is running. If you're using Mac, you can start the MongoDB server with the following command:

   brew services start mongodb-community

   • Seed the database with sample data:

     cd backend/seednode productSeeds.js dev

   • Run the backend server: (firstcd into the backend directory)

     cd ..npm start

4. Set up the frontend:

   • First,cd into theroot directory if you are not already there:

     cd ..

     Or

     cd fullstack-ecommerce

   • Start the frontend development server:

     npm start

• Open your browser and navigate tohttp://localhost:3000 to view the application.

The application usesPinecone as the primary vector database while still supportingWeaviate,FAISS, andLangChain for additional experimentation. Pinecone keeps MongoDB products and vector embeddings in sync automatically, ensuring recommendations remain fresh.

1. Create a Pinecone project and serverless index (e.g.,ecommerce-products) in the AWSus-east-1 region.
2. Add the following variables tobackend/.env:

   PINECONE_API_KEY=your_pinecone_api_keyPINECONE_HOST=https://your-index.svc.YOUR-REGION.pinecone.ioPINECONE_INDEX=ecommerce-productsPINECONE_NAMESPACE=ecommerce-products # optionalGOOGLE_AI_API_KEY=your_google_ai_api_keyPINECONE_PURGE_ON_SYNC=true # set to false to skip clearing existing vectors during sync

   The Google AI key powers the embedding model (text-embedding-004).
3. Sync MongoDB products into Pinecone:

   cd backendnpm run sync-pinecone

   The backend also runs this sync during startup and re-syncs vectors automatically whenever products are created, updated (name/description/price/brand/image/category), or deleted. WhenPINECONE_PURGE_ON_SYNC is true (default), the sync clears the namespace first to prevent stale vectors building up.

1. Provision a Weaviate instance atWeaviate Cloud and collect the host + API key.
2. Add the variables tobackend/.env:

   WEAVIATE_HOST=https://your-weaviate-instance.weaviate.networkWEAVIATE_API_KEY=your_weaviate_api_key

3. Index existing products in Weaviate:

   cd backendnpm run weaviate-upsertnpm run sync-weaviate

   If you want the recommendation endpoints to prioritize Weaviate responses, setRECOMMENDATION_PREFER_WEAVIATE=true inbackend/.env.
4. (Optional)Build and query the FAISS index:

   cd backendnode scripts/build-faiss-index.jsnpm run faiss-search --"your search text" 5

With Pinecone configured, product pages and bundles leverage vector similarity for recommendations. When Pinecone or Weaviate lookups have no matches, the API falls back to metadata-based heuristics to ensure users always see relevant suggestions.

• Simply open your browser and navigate tohttp://localhost:5000/api/products to view the list of products.
• You can also change the sample data by navigating tobackend/seed/productSeeds.js and modifying the data there.

We have implemented unit and integration tests for the application using Jest and React Testing Library. To run the tests, follow these steps:

cd backend# Run backend tests (default mode)npm runtest# Run frontend tests (watch mode - this will automatically re-run tests on file changes)npm run test:watch# Run frontend tests (coverage mode - this will generate a coverage report)npm run test:coverage

cd ..# if you are still in the backend directory# Run frontend tests (default mode)npm runtest# Run frontend tests (watch mode - this will automatically re-run tests on file changes)npm run test:watch# Run frontend tests (coverage mode - this will generate a coverage report)npm run test:coverage

• The backend server includes Swagger API documentation that can be accessed athttp://localhost:5000/api-docs.
• Before accessing the above URL, ensure that the backend server is running.
• The Swagger UI provides a detailed overview of the API endpoints, request/response schemas, and example requests.
• If you have everything set up correctly, you should see the Swagger UI documentation page:

1. View the API Documentation

• OpenSwagger Editor.
• Upload theopenapi.yaml file or paste its content.
• Visualize and interact with the API documentation.

2. Test the API

• Importopenapi.yaml intoPostman:
  • Open Postman → Import → Selectopenapi.yaml.
  • Test the API endpoints directly from Postman.
• Or useSwagger UI:
  • Provide the file URL or upload it to view and test endpoints.

3. Generate Client Libraries

• Install OpenAPI Generator:

  npm install @openapitools/openapi-generator-cli -g

• Generate a client library:

  openapi-generator-cli generate -i openapi.yaml -g<language> -o ./client

• Replace<language> with the desired programming language.

4. Generate Server Stubs

• Generate a server stub:

  openapi-generator-cli generate -i openapi.yaml -g<framework> -o ./server

• Replace<framework> with the desired framework.

5. Run a Mock Server

• Install Prism:

  npm install -g @stoplight/prism-cli

• Start the mock server:

  prism mock openapi.yaml

6. Validate the OpenAPI File

• UseSwagger Validator:
  • Uploadopenapi.yaml or paste its content to check for errors.

This guide enables you to view, test, and utilize the API. You can generate client libraries, server stubs, and run a mock server using the OpenAPI Specification.

Fusion Electronics supports a wide range of deployment platforms, including Vercel, Render, AWS, and more. You can deploy both the frontend and backend servers to your preferred cloud provider.

It also supports containerized and enterprise-grade deployments (blue/green deployments, canary releases, etc.) using Docker and Kubernetes. For more details on deployments, see theDEPLOYMENT GUIDE file.

This project can be containerized using Docker. First, ensure that Docker Desktop is running on your system. Then, to create a Docker image, run the following command:

docker compose up --build

This command will create a Docker image for the frontend and backend, and run the application in a containerized environment.

This project includes a GitHub Actions workflow for continuous integration and deployment. The workflow is defined in the.github/workflows/ci.yml file and will automatically run tests and build the application on every push or pull request.

Contributions to this project are welcome! Here are some ways you can contribute:

• Report bugs and request features by opening issues.
• Implement new features or enhancements and submit pull requests.
• Improve documentation and README files.

This project is licensed under theMIT License - see theLICENSE file for details.

Fusion Electronics was created with ❤️ by:

• Son Nguyen -hoangsonww
• Email:hoangson091104@gmail.com.

Thank you for exploringFusion Electronics - a MERN Stack E-commerce Application! If you have any questions or feedback, feel free to reach out or open an issue.

Happy coding! 🚀