🛍️ ShopCo - Modern E-commerce Platform

A comprehensive, full-stack e-commerce platform built with modern web technologies, featuring authentication, product management, shopping cart, and order processing capabilities.

✨ Features

🔐 Authentication System

• User Registration & Login with secure JWT authentication
• Email Verification with token-based verification system
• Password Reset functionality with secure tokens
• Password encryption using bcryptjs
• Protected routes with role-based access control
• Persistent login sessions across page refreshes
• Automatic token validation and expiry handling
• Seamless user data persistence in localStorage
• Form validation with Zod schemas and react-hook-form

🎨 Modern UI/UX

• Responsive design with Tailwind CSS
• Interactive modals with React Portals for proper z-index layering
• Toast notifications with smart fallback system (works with/without react-hot-toast)
• Loading states and smooth animations
• Mobile-first approach with clean, modern interface
• Lazy loading with React.lazy and Suspense for optimal performance
• URL-based navigation with persistent tab states
• Consistent design system with icon-free buttons and clean typography

🛒 E-commerce Core

• Product catalog with categories and detailed views
• Shopping cart functionality
• Order management system
• User profiles with comprehensive management
  • Profile information editing with avatar upload
  • Password change with validation
  • Address management with multiple address types
  • Email verification status
• Address Management
  • Multiple address support (Home, Work, Other)
  • Default address selection
  • City autocomplete with Geoapify API integration
  • Color-coded address type badges
• Newsletter subscription system
• Search and filtering capabilities

🔧 Developer Experience

• TypeScript for type safety across the entire stack
• ESLint for code quality and consistency (zero warnings)
• Hot reload for fast development
• Environment-based configuration
• Clean architecture with separation of concerns
• Type-safe API responses with proper interfaces
• Optimized production builds with code splitting and tree shaking
• Security vulnerability-free dependencies

🚀 Tech Stack

Frontend

• React 19 with TypeScript for modern UI development
• Vite for lightning-fast development and optimized builds
• Tailwind CSS for utility-first styling
• React Router for client-side routing
• Zustand for lightweight state management
• React Hook Form with Zod validation
• Axios for API communication
• Lucide React for beautiful icons

Backend

• Node.js with Express.js framework
• MongoDB with Mongoose ODM
• JWT for secure authentication
• bcryptjs for password hashing
• Express Validator for input validation
• Helmet for security headers
• Morgan for request logging
• Rate limiting for API protection

Development Tools

• ESLint with TypeScript support
• Nodemon for development server
• CORS for cross-origin requests
• dotenv for environment management

📁 Project Structure

ShopCo/
├── client/                     # React Frontend Application
│   ├── src/
│   │   ├── components/         # Reusable UI Components
│   │   │   ├── ui/            # Core UI components (Modal, ConfirmModal)
│   │   │   ├── layout/        # Layout components (Header, Footer)
│   │   │   ├── forms/         # Form components (Input, Button)
│   │   │   ├── auth/          # Authentication components (ProtectedRoute)
│   │   │   ├── providers/     # Context providers (ToastProvider)
│   │   │   └── cart/          # Shopping cart components
│   │   ├── pages/             # Page Components
│   │   │   ├── auth/          # Authentication pages (Login, Signup)
│   │   │   ├── home/          # Home page components
│   │   │   └── NotFound.tsx   # 404 error page
│   │   ├── services/          # API Services
│   │   │   ├── api.ts         # Main API configuration
│   │   │   ├── authService.ts # Authentication API calls
│   │   │   └── toastService.ts # Toast notification service
│   │   ├── stores/            # State Management (Zustand)
│   │   │   └── authStore.ts   # Authentication state
│   │   ├── schemas/           # Validation Schemas (Zod)
│   │   │   └── auth.schemas.ts # Auth form validation
│   │   ├── hooks/             # Custom React Hooks
│   │   │   └── useAuth.ts     # Authentication hook
│   │   ├── routes/            # Routing Configuration
│   │   │   └── AppRoutes.tsx  # Main route definitions
│   │   ├── types/             # TypeScript Definitions
│   │   │   └── auth.types.ts  # Authentication types
│   │   └── config/            # Configuration Files
│   └── package.json
└── server/                     # Express Backend API
    ├── models/                 # Database Models (Mongoose)
    │   ├── User.js            # User model with authentication
    │   ├── Product.js         # Product catalog model
    │   ├── Category.js        # Product categories
    │   └── Order.js           # Order management
    ├── routes/                 # API Route Handlers
    │   └── authRoutes.js      # Authentication endpoints
    ├── controllers/            # Business Logic Controllers
    ├── middleware/             # Custom Middleware
    ├── validators/             # Input Validation
    ├── utils/                  # Utility Functions
    ├── config/                 # Database & App Configuration
    ├── index.js               # Main server entry point
    ├── .env                   # Environment variables
    └── package.json

🛠️ Development Setup

Prerequisites

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

Installation

1. Clone the repository

   git clone https://github.com/marmikitpl-dev/ShopCo.git
   cd ShopCo

2. Install dependencies

   # Install server dependencies
   cd server
   yarn install
   
   # Install client dependencies
   cd ../client
   yarn install

3. Environment Setup

   # Copy environment template
   cd server
   cp .env.example .env

   Configure your .env file:

   # Server Configuration
   PORT=5000
   NODE_ENV=development
   
   # Database
   MONGODB_URI=mongodb://localhost:27017/shopco
   # Or use MongoDB Atlas: mongodb+srv://username:password@cluster.mongodb.net/shopco
   
   # JWT Configuration
   JWT_SECRET=your-super-secret-jwt-key-here
   JWT_EXPIRES_IN=7d
   
   # CORS Configuration
   CLIENT_URL=http://localhost:5173

4. Database Setup

   # Make sure MongoDB is running locally, or use MongoDB Atlas
   # The application will automatically create the database and collections

Running the Application

Development Mode

1. Start the backend server

   cd server
   yarn dev

   Server will run on http://localhost:5000

2. Start the frontend (in a new terminal)

   cd client
   yarn dev

   Client will run on http://localhost:5173

Production Mode

1. Build the client

   cd client
   yarn build

2. Start the server

   cd server
   yarn start

📝 Available Scripts

Client (Frontend)

• yarn dev - Start development server
• yarn build - Build for production
• yarn preview - Preview production build
• yarn lint - Run ESLint

Server (Backend)

• yarn start - Start production server
• yarn dev - Start development server with nodemon

🌐 API Endpoints

Base URL: http://localhost:5000

General

• GET / - Welcome message
• GET /api - API information
• GET /api/health - Health check endpoint

Authentication (/api/auth)

• POST /api/auth/register - User registration
• POST /api/auth/login - User login
• POST /api/auth/logout - User logout
• GET /api/auth/me - Get current user profile
• PUT /api/auth/profile - Update user profile
• PUT /api/auth/change-password - Change user password
• POST /api/auth/verify-email - Verify email with token
• POST /api/auth/resend-verification - Resend verification email
• POST /api/auth/forgot-password - Request password reset
• POST /api/auth/reset-password - Reset password with token

Addresses (/api/addresses)

• GET /api/addresses - Get all user addresses
• POST /api/addresses - Add new address
• PUT /api/addresses/:id - Update address
• DELETE /api/addresses/:id - Delete address
• PUT /api/addresses/:id/default - Set address as default

Newsletter (/api/newsletter)

• POST /api/newsletter/subscribe - Subscribe to newsletter
• POST /api/newsletter/unsubscribe - Unsubscribe from newsletter

Products (/api/products) - Coming Soon

• GET /api/products - Get all products
• GET /api/products/:id - Get product by ID
• POST /api/products - Create new product (Admin)
• PUT /api/products/:id - Update product (Admin)
• DELETE /api/products/:id - Delete product (Admin)

Categories (/api/categories) - Coming Soon

• GET /api/categories - Get all categories
• POST /api/categories - Create category (Admin)

Orders (/api/orders) - Coming Soon

• GET /api/orders - Get user orders
• POST /api/orders - Create new order
• GET /api/orders/:id - Get order by ID

🚀 Deployment

Frontend (Vercel - Recommended)

The client is optimized for Vercel deployment:

1. Connect your repository to Vercel

2. Configure build settings:

   • Build Command: yarn build
   • Output Directory: dist
   • Root Directory: client

3. Environment Variables:

   VITE_API_BASE_URL=https://your-backend-url.com

Backend (Render - Recommended)

The server is configured for Render deployment:

1. Connect your repository to Render

2. Configure service settings:

   • Build Command: yarn install
   • Start Command: yarn start
   • Root Directory: server

3. Environment Variables:

   NODE_ENV=production
   PORT=10000
   MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/shopco
   JWT_SECRET=your-production-jwt-secret
   JWT_EXPIRES_IN=7d
   CLIENT_URL=https://your-frontend-url.vercel.app

Alternative Deployment Options

• Frontend: Netlify, GitHub Pages, AWS S3
• Backend: Railway, Heroku, AWS EC2, DigitalOcean

🔧 Environment Variables Reference

Server (.env)

# Server Configuration
PORT=5000                                    # Server port
NODE_ENV=development                         # Environment (development/production)

# Database Configuration
MONGODB_URI=mongodb://localhost:27017/shopco # MongoDB connection string

# JWT Configuration
JWT_SECRET=your-super-secret-jwt-key-here    # JWT signing secret
JWT_EXPIRES_IN=7d                           # JWT expiration time

# CORS Configuration
CLIENT_URL=http://localhost:5173             # Frontend URL for CORS

# Optional: Email Configuration (for future features)
# SMTP_HOST=smtp.gmail.com
# SMTP_PORT=587
# SMTP_USER=your-email@gmail.com
# SMTP_PASS=your-app-password

Client (.env)

# API Configuration
VITE_API_BASE_URL=http://localhost:5000      # Backend API URL

🧪 Testing

Frontend Testing

cd client
# Run tests (when implemented)
yarn test

# Run linting
yarn lint

Backend Testing

cd server
# Run tests (when implemented)
yarn test

# Check for security vulnerabilities
yarn audit

🔒 Security Features

• Password Hashing: bcryptjs with salt rounds
• JWT Authentication: Secure token-based authentication
• Input Validation: Server-side validation with express-validator
• Rate Limiting: API rate limiting to prevent abuse
• CORS Protection: Configured cross-origin resource sharing
• Security Headers: Helmet.js for security headers
• Environment Variables: Sensitive data stored in environment variables

🚧 Roadmap

Phase 1 (Completed ✅)

• ✅ User authentication system (Register, Login, Logout)
• ✅ Email verification system
• ✅ Password reset functionality
• ✅ Modern UI with React 19
• ✅ Modal and toast notification system
• ✅ Responsive design
• ✅ User profile management
  • ✅ Profile information editing
  • ✅ Avatar upload
  • ✅ Password change
  • ✅ Address management (6 types)
  • ✅ City autocomplete
• ✅ Newsletter subscription system
• ✅ URL-based navigation with persistent states
• ✅ Type-safe API responses
• ✅ Production-optimized builds
• ✅ Zero security vulnerabilities

Phase 2 (In Progress 🔄)

• 🔄 Product catalog and management
• 🔄 Shopping cart functionality
• 🔄 Order processing system
• 🔄 Payment gateway integration

Phase 3 (Planned)

• 📋 Payment integration (Stripe/PayPal)
• 📋 Email notifications
• 📋 Admin dashboard
• 📋 Product reviews and ratings
• 📋 Wishlist functionality
• 📋 Search and filtering
• 📋 Mobile app (React Native)

🤝 Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch

   git checkout -b feature/amazing-feature

3. Make your changes
   • Follow the existing code style
   • Add tests for new features
   • Update documentation as needed
4. Commit your changes

   git commit -m 'feat: add amazing feature'

5. Push to your branch

   git push origin feature/amazing-feature

6. Open a Pull Request

Code Style Guidelines

• Use TypeScript for type safety
• Follow ESLint configuration
• Write descriptive commit messages
• Add comments for complex logic
• Ensure responsive design for UI changes

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support & Contact

• Issues: GitHub Issues
• Email: marmiksoni777@gmail.com

🙏 Acknowledgments

• React Team for the amazing React 19 features
• Tailwind CSS for the utility-first CSS framework
• Vite for the lightning-fast build tool
• MongoDB for the flexible database solution
• All Contributors who help make this project better

---

Built with ❤️ by the ShopCo Team

⭐ Star this repo • 🐛 Report Bug • ✨ Request Feature

Happy Shopping! 🛒✨