Skip to content

README.md

Latest commit

 

History

History
433 lines (333 loc) · 12.9 KB

README.md

File metadata and controls

433 lines (333 loc) · 12.9 KB

Ecommerce Platform

A full-stack ecommerce application built with modern web technologies, featuring a React/Next.js frontend, Python FastAPI backend, and MongoDB database.

⚠️ IMPORTANT CAUTION

Database Availability Issue: This application uses MongoDB Atlas on a free tier instance. The cluster may be automatically shut down due to inactivity periods. If you experience any of the following issues:

  • Pages fail to load or load indefinitely
  • Signup/Sign in buttons don"t work
  • "500 Internal Server Error" messages
  • Product listings not appearing
  • Cart or order operations failing

The cause is likely that the MongoDB Atlas cluster has been shut down due to inactivity. This is a known limitation of the free tier. The cluster will automatically restart when accessed again, but there may be a delay (typically 5-10 minutes).

Solution: Contact the project maintainer to restart the cluster or deploy the database to a paid tier or self-hosted MongoDB instance for production use.

🚀 Features

  • User Authentication: Secure signup, signin, and logout with JWT tokens and OTP verification
  • Product Management: Browse, search, and filter products with detailed product pages
  • Shopping Cart: Add/remove items, manage quantities with persistent cart storage
  • Checkout: Complete checkout process with order creation and management
  • User Addresses: Add, edit, and manage multiple delivery addresses
  • Order History: View previous orders and track order details
  • Location Services: Google Maps integration for location-based features
  • Search & Filters: Advanced product search and filtering capabilities
  • Deal Pages: Featured deals and promotional products
  • User Profiles: Manage user account information and preferences
  • Image Upload: Product and user image uploads via Cloudinary
  • Responsive Design: Fully responsive UI optimized for all devices

📸 Screenshots

Application Overview

Screenshot 1

Screenshot 2

Screenshot 3

Screenshot 4

Screenshot 5

Screenshot 6

Screenshot 7

Screenshot 8

🛠️ Tech Stack

Frontend Technologies

Next.js React Tailwind CSS JavaScript

Backend Technologies

FastAPI Python

Database

MongoDB Mongoose

Authentication & Security

JWT Bcrypt

APIs & Services

Google Maps Cloudinary

Additional Libraries

Framer Motion Zod React Hot Toast

Detailed Tech Stack

Frontend

  • Framework: Next.js 15
  • UI Library: React 19
  • Styling: Tailwind CSS
  • Database ODM: Mongoose
  • Authentication: JWT (Jose), Bcrypt
  • APIs:
    • Google Maps API
    • Cloudinary
    • Leaflet/React-Leaflet for maps
  • Utilities:
    • React Hot Toast for notifications
    • Framer Motion for animations
    • Zod for validation
    • Date-fns for date manipulation

Backend

  • Framework: FastAPI (Python)
  • Database: MongoDB
  • Authentication: JWT
  • Email: SMTP (Nodemailer integration)
  • CORS: Enabled for frontend communication

📁 Project Structure

ecommerce/
├── backend/
│   ├── main.py              # FastAPI application entry point
│   ├── config.py            # Configuration settings
│   ├── database.py          # Database connection
│   ├── models.py            # Data models
│   ├── auth/                # Authentication module
│   │   ├── routes.py        # Auth endpoints
│   │   ├── address.py       # Address management
│   │   ├── cart.py          # Cart operations
│   │   └── utils.py         # Helper functions
│   └── __pycache__/
│
├── website/                 # Next.js Frontend Application
│   ├── app/
│   │   ├── page.js          # Home page
│   │   ├── layout.js        # Root layout
│   │   ├── globals.css      # Global styles
│   │   ├── api/             # API routes
│   │   │   ├── auth/        # Authentication endpoints
│   │   │   ├── products/    # Product endpoints
│   │   │   ├── cart/        # Cart endpoints
│   │   │   ├── orders/      # Order endpoints
│   │   │   ├── checkout/    # Checkout endpoints
│   │   │   └── ...
│   │   ├── components/      # Reusable React components
│   │   ├── lib/             # Utility functions and helpers
│   │   ├── models/          # Mongoose schemas
│   │   ├── services/        # API service functions
│   │   └── [pages]/         # Dynamic pages
│   ├── public/              # Static assets
│   ├── scripts/
│   │   ├── seed-products.js # Database seeding script
│   │   └── test-mongodb-connection.js
│   ├── package.json         # Frontend dependencies
│   ├── next.config.mjs      # Next.js configuration
│   └── README-MONGODB.md    # MongoDB setup guide
│
├── package.json             # Root dependencies
└── README.md               # This file

⚙️ Installation & Setup

Prerequisites

  • Node.js (v18 or higher)
  • Python 3.9+
  • MongoDB (local or Atlas)
  • npm or yarn package manager

1. Clone & Install Dependencies

# Install root dependencies
npm install

# Install frontend dependencies
cd website
npm install

# Install backend dependencies (if using pip)
cd ../backend
pip install -r requirements.txt  # Create if needed
cd ../..

2. Environment Configuration

Create a .env.local file in the website directory:

# MongoDB
MONGO_URI=mongodb://localhost:27017/ecommerce

# Frontend URL
NEXT_PUBLIC_API_URL=http://localhost:8000

# Google Maps (optional)
NEXT_PUBLIC_GOOGLE_MAPS_API_KEY=your_api_key

# Cloudinary (optional)
NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME=your_cloud_name

Create a .env file in the backend directory:

# Email Configuration
SMTP_SERVER=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your_email@gmail.com
SMTP_PASSWORD=your_app_password

# JWT Configuration
SECRET_KEY=your-secret-key-here
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30
JWT_ISSUER=your-app-name
JWT_AUDIENCE=your-app-audience

# Frontend URL
FRONTEND_URL=http://localhost:3000

# Debug Mode
DEBUG=False

3. Database Setup

# Seed the database with sample products
cd website
npm run seed

🚀 Running the Application

Development Mode

Terminal 1 - Start Backend (FastAPI)

cd backend
uvicorn main:app --reload
# API runs on http://localhost:8000

Terminal 2 - Start Frontend (Next.js)

cd website
npm run dev
# Frontend runs on http://localhost:3000

Production Build

# Build frontend
cd website
npm run build
npm start

# Backend - Configure for production
cd backend
uvicorn main:app --host 0.0.0.0 --port 8000

📚 API Documentation

Authentication Endpoints

  • POST /api/auth/signup - User registration
  • POST /api/auth/signin - User login
  • POST /api/auth/logout - User logout
  • POST /api/auth/send-otp - Send OTP for verification
  • POST /api/auth/verify - Verify OTP

Product Endpoints

  • GET /api/products - Get all products
  • GET /api/products/[id] - Get product details
  • GET /api/products/featured - Get featured products
  • GET /api/products/deals - Get deal products
  • GET /api/products/filters - Get available filters
  • POST /api/search - Search products

Cart Endpoints

  • GET /api/cart - Get cart items
  • POST /api/cart/[action] - Add/update cart items
  • DELETE /api/cart/[id] - Remove from cart

Order Endpoints

  • GET /api/orders - Get user orders
  • GET /api/orders/[id] - Get order details
  • POST /api/orders - Create new order
  • GET /api/orders/previous-products - Get previous order products

User Endpoints

  • GET /api/user/profile - Get user profile
  • GET /api/user/address - Get user addresses
  • POST /api/user/address - Add new address
  • PUT /api/user/address - Update address

Other Endpoints

  • POST /api/checkout - Process checkout
  • GET /api/geocode - Geocoding service
  • POST /api/upload - Upload files

🗄️ Database Models

User

  • Email, password, name
  • Phone, addresses
  • Order history

Product

  • Name, description, price
  • Category, stock
  • Images, ratings
  • Deal information

Cart

  • User reference
  • Product items with quantities

Order

  • User reference
  • Products ordered
  • Delivery address
  • Order status
  • Total amount

Address

  • Street, city, state
  • Zip code, country
  • Default address flag

🔧 Available Scripts

Frontend

npm run dev      # Start development server
npm run build    # Build for production
npm run start    # Start production server
npm run lint     # Run ESLint
npm run seed     # Seed database with products

Backend

uvicorn main:app --reload          # Development with hot reload
uvicorn main:app --host 0.0.0.0    # Production

📝 Key Features Implementation

Authentication

  • JWT-based authentication with secure token storage
  • OTP verification for account security
  • Password hashing with bcrypt
  • CORS-enabled for frontend communication

Product Management

  • MongoDB integration with Mongoose
  • Product filtering and search
  • Deal and featured product pages
  • Image uploads via Cloudinary

Shopping Experience

  • Real-time cart management
  • Address management for delivery
  • Order creation and tracking
  • Order history with previous purchases

Maps Integration

  • Google Maps for location services
  • Leaflet for interactive maps
  • Geolocation support

🐛 Troubleshooting

MongoDB Connection Issues

  • Ensure MongoDB is running locally or check Atlas credentials
  • Verify MONGO_URI in .env.local
  • Run test script: node scripts/test-mongodb-connection.js

CORS Errors

  • Verify backend CORS configuration allows http://localhost:3000
  • Check FRONTEND_URL in backend .env

Authentication Issues

  • Ensure SECRET_KEY matches between frontend and backend
  • Check JWT token expiration settings
  • Verify SMTP credentials for email features

Image Upload Issues

  • Verify Cloudinary credentials in environment
  • Check file size limits in configuration

📄 License

This project is private and for educational/development purposes.

🤝 Contributing

  1. Create a feature branch
  2. Make your changes
  3. Test thoroughly
  4. Submit pull request

📧 Support

For issues or questions, please refer to the documentation or create an issue in the repository.

👥 Authors

  • Your Name - Initial work and development

🙏 Acknowledgments

  • Next.js documentation and community
  • FastAPI documentation
  • MongoDB Atlas for database hosting
  • Google Maps API
  • Cloudinary for image hosting

Additional Resources

Built with ❤️ for learning and development. Version: 0.1.0 | Last Updated: January 2026