ShopEase

A Full-Stack E-Commerce Web Application

Built with Flask, SQLite, and Vanilla JavaScript

📋 Table of Contents

Overview
Features
Design Patterns
Tech Stack
Project Structure
Installation
API Endpoints
Screenshots
Common Issues
Future Enhancements

Overview

ShopEase is a complete e-commerce web application that allows users to browse products, add items to cart, place orders, and manage their profile. It includes an admin dashboard for managing products, users, and viewing sales analytics.

The project demonstrates the practical implementation of 4 classic design patterns in a real-world Python application.

Features

👤 Customer Features

Feature	Description
User Authentication	Register, login, logout with session management
Product Browsing	View all products with image, price, rating
Search & Filters	Search by name, filter by category and price range
Sorting	Sort by price (low/high) and rating
Shopping Cart	Add/remove items, update quantities, persistent storage
Wishlist	Save favorite products
Order Management	Place orders, view confirmation, download receipts
Theme Toggle	Switch between dark and light mode

👑 Admin Features

Feature	Description
Admin Dashboard	View store statistics (revenue, orders, users, products)
Product Management	Add, edit, and delete products
User Management	View all users, change roles, delete users
Order Management	View all customer orders with details
Analytics	Sales trends, category performance, hourly sales

🎨 Design Patterns Implemented

Pattern	Location	Purpose	Code Example
Singleton	`cart_singleton.py`	Single CartManager instance across entire application	`cart_manager = CartSingleton()`
Factory	`factories.py`	Creates category-specific products	`factory_manager.get_factory('electronics')`
Builder	`factories.py`	Step-by-step product construction	`builder.set_name().set_price().build()`
Decorator	`discount_decorators.py`	Dynamic discount stacking	`PercentageDiscountDecorator(BasePriceCalculator(), 20)`

Detailed Pattern Explanation

1. Singleton Pattern

class CartSingleton:
    _instance = None
    
    def __new__(cls):
        if cls._instance is None:
            cls._instance = super().__new__(cls)
        return cls._instance

Ensures only ONE cart manager exists
Provides global access point for cart operations
Handles cart caching and statistics

2. Factory Pattern

class ProductFactoryManager:
    _factories = {
        'electronics': ElectronicsFactory(),
        'audio': AudioFactory(),
        'clothing': ClothingFactory()
    }

Creates products without specifying exact class
Each category has its own factory
Easy to add new product types

3. Builder Pattern

product = (builder
    .set_name("Laptop")
    .set_price(999.99)
    .set_description("Powerful laptop")
    .build())

Fluent interface for product creation
Step-by-step construction
Same process creates different product representations

4. Decorator Pattern

calculator = BasePriceCalculator()
calculator = PercentageDiscountDecorator(calculator, 20)
calculator = FixedAmountDiscountDecorator(calculator, 10)
final_price = calculator.calculate_price(100, 1)  # 100 - 20% - $10 = $70

Dynamically add discounts to products
Stack multiple discounts
Open for extension, closed for modification

Tech Stack

Backend

Technology	Purpose
Python 3.8+	Core programming language
Flask 2.3.3	Web framework
SQLAlchemy 2.0.19	ORM for database operations
SQLite	Database (lightweight, file-based)
Flask-CORS 4.0.0	Cross-origin requests handling
python-dotenv	Environment variables management

Frontend

Technology	Purpose
HTML5	Structure
CSS3	Styling (dark/light themes)
JavaScript	Dynamic interactions, API calls
Font Awesome 6.4.0	Icons

Project Structure

shopease/
│
├── backend/
│   ├── app.py                      # Main Flask application (all routes)
│   ├── models.py                   # Database models
│   │   ├── User                    # User authentication
│   │   ├── Product                 # Product catalog
│   │   ├── CartItem                # Shopping cart items
│   │   ├── Order                   # Customer orders
│   │   └── OrderItem               # Individual order items
│   │
│   ├── database.py                 # Database connection & session
│   ├── cart_singleton.py           # SINGLETON pattern implementation
│   ├── discount_decorators.py      # DECORATOR pattern implementation
│   ├── factories.py                # FACTORY & BUILDER patterns
│   ├── config.py                   # Configuration settings
│   ├── requirements.txt            # Python dependencies
│   │
│   ├── add_missing_columns.py      # Database migration script
│   ├── seed_products.py            # Product seeding script
│   ├── create_admin.py             # Admin user creator
│   └── check_database.py           # Database inspection tool
│
├── frontend/
│   ├── index.html                  # Homepage
│   ├── products.html               # Product listing with filters
│   ├── product-detail.html         # Individual product view
│   ├── cart.html                   # Shopping cart
│   ├── receipt.html                # Order confirmation
│   ├── login.html                  # Login page
│   ├── admin-dashboard.html        # Admin panel
│   ├── contact.html                # Contact page
│   ├── privacy-policy.html         # Privacy policy
│   └── disclaimer.html             # Legal disclaimer
│
├── templates/                      # Flask template folder
│   ├── index.html
│   ├── login.html
│   └── admin-dashboard.html
│
├── shopease.db                     # SQLite database file
└── README.md                       # This file

Installation

Prerequisites

Python 3.8 or higher
pip (Python package manager)

Step-by-Step Setup

1. Clone the Repository

git clone https://github.com/yourusername/shopease.git
cd shopease

2. Navigate to Backend Directory

cd backend

3. Install Dependencies

pip install -r requirements.txt

4. Initialize Database

python -c "from database import init_db; init_db()"

5. Add Missing Columns (if needed)

python add_missing_columns.py

6. Seed Products into Database

python seed_products.py

7. Create Admin User

python create_admin.py

Or send POST request to /api/create-admin:

{
    "username": "admin",
    "email": "admin@shopease.com", 
    "password": "admin123"
}

8. Start the Server

python app.py

9. Access the Application

Open your browser and go to: http://localhost:5000

API Endpoints

🔐 Authentication

Method	Endpoint	Description
POST	`/api/login`	User login (username/email + password)
POST	`/api/register`	Create new account
POST	`/api/logout`	Logout current user
GET	`/api/check-auth`	Check if user is logged in
POST	`/api/create-admin`	Create admin user

📦 Products

Method	Endpoint	Description
GET	`/api/products`	Get products (with filters & pagination)
GET	`/api/products/<id>`	Get single product by ID
GET	`/api/categories`	Get all product categories

🛒 Cart

Method	Endpoint	Description
GET	`/api/cart?session_id=xxx`	Get cart items
POST	`/api/cart`	Add item to cart
PUT	`/api/cart/<item_id>`	Update item quantity
DELETE	`/api/cart/<item_id>`	Remove item from cart
DELETE	`/api/cart/clear?session_id=xxx`	Clear entire cart

📄 Orders

Method	Endpoint	Description
POST	`/api/orders`	Create new order from cart
GET	`/api/orders/<order_number>`	Get order details

👑 Admin (requires admin role)

Method	Endpoint	Description
GET	`/api/admin/stats`	Dashboard statistics
GET	`/api/admin/products`	Get all products (admin view)
POST	`/api/admin/products`	Create new product
PUT	`/api/admin/products/<id>`	Update product
DELETE	`/api/admin/products/<id>`	Delete product
GET	`/api/admin/users`	Get all users
PUT	`/api/admin/users/<id>`	Update user role
DELETE	`/api/admin/users/<id>`	Delete user
GET	`/api/admin/orders`	Get all orders

🏷️ Discounts

Method	Endpoint	Description
POST	`/api/discounts/apply`	Apply discounts to cart
POST	`/api/discounts/validate-coupon`	Validate coupon code
GET	`/api/discounts/active`	Get active discounts

🔧 Debug Endpoints

Method	Endpoint	Description
GET	`/api/health`	Health check
GET	`/api/debug/products`	List all products
GET	`/api/debug/cart-items`	List all cart items
POST	`/api/debug/test-cart`	Test cart functionality

Database Schema

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│    users    │     │   orders    │     │ order_items │
├─────────────┤     ├─────────────┤     ├─────────────┤
│ id (PK)     │────<│ user_id (FK)│     │ id (PK)     │
│ username    │     │ order_number│     │ order_id(FK)│>───┐
│ email       │     │ session_id  │     │ product_id  │    │
│ password_hash│    │ total_amount│     │ quantity    │    │
│ role        │     │ status      │     │ price       │    │
│ created_at  │     │ shipping_info│    │ created_at  │    │
└─────────────┘     │ created_at  │     └─────────────┘    │
                    └─────────────┘                        │
                                                            │
┌─────────────┐     ┌─────────────┐                        │
│  products   │     │ cart_items  │                        │
├─────────────┤     ├─────────────┤                        │
│ id (PK)     │<────│ product_id  │                        │
│ name        │     │ id (PK)     │                        │
│ category    │     │ session_id  │                        │
│ price       │     │ quantity    │                        │
│ rating      │     │ added_at    │                        │
│ reviews     │     └─────────────┘                        │
│ description │                                            │
│ image       │                                            │
│ created_at  │                                            │
└─────────────┘                                            │
                                                           │
                                              ┌────────────┴────────────┐
                                              │                         │
                                         ┌────┴────┐              ┌──────┴─────┐
                                         │ product │              │   order    │
                                         │ (rel)   │              │  (rel)     │
                                         └─────────┘              └────────────┘

Screenshots

Homepage

Product categories showcase
Featured products section
Dark/light theme toggle

Products Page

Grid layout with product cards
Search bar with real-time filtering
Category dropdown, price filter, sort options
Pagination support

Product Detail Page

High-res product image with thumbnails
Rating stars, price, description
Add to cart / wishlist buttons
Related products section

Shopping Cart

List of added items with quantities
Update quantity or remove items
Subtotal, shipping, tax calculation
Proceed to checkout

Order Receipt

Order confirmation number
Itemized order details
Shipping information display
Download receipt option
Estimated delivery date

Admin Dashboard

Statistics cards (revenue, orders, users)
Recent orders table
Product management (CRUD operations)
User management with role assignment

Common Issues & Solutions

🔴 Database Issues

Issue	Solution
Missing columns in orders table	Run `python add_missing_columns.py`
No products in database	Run `python seed_products.py`
Database locked error	Close all connections or restart server
Table doesn't exist	Run `python -c "from database import init_db; init_db()"`

🔴 Connection Issues

Issue	Solution
Flask server not running	Run `python app.py` in backend directory
Port 5000 already in use	Kill process or change port in app.py
CORS errors	Check CORS configuration in app.py
API_BASE_URL wrong	Update to `http://localhost:5000/api`

🔴 Authentication Issues

Issue	Solution
Can't login	Clear browser cookies and localStorage
Session not persisting	Check if `SECRET_KEY` is set in config
Admin access denied	Run `python create_admin.py` to create admin

🔴 Cart Issues

Issue	Solution
Cart not saving	Check session_id is being generated
Items disappearing	Verify localStorage persistence
Add to cart failing	Check backend is running on port 5000

Future Enhancements

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open a Pull Request

License

Contact

For questions or support, please reach out:

Email: saminsarfaraz949@gmail.com
GitHub: https://github.com/samin949

Made with ❤️ using Python and Flask

⭐ Star this repository if you found it helpful!

Name		Name	Last commit message	Last commit date
backend		backend
frontend		frontend
README.md		README.md
shopping-app.png		shopping-app.png

Latest commit

History

Folders and files

Repository files navigation