# 🛍️ Wearwell - Modern E-commerce Clothing Store

<div align="center">
  
![Python](https://img.shields.io/badge/Python-3.12+-yellow.svg)
![Flask](https://img.shields.io/badge/Flask-3.1+-blue.svg)
![MariaDB](https://img.shields.io/badge/MariaDB-10+-orange.svg)

**WearWell - a simple flask shopping web app for clothes**

<img src="https://git.broombox.org/amanfromspace/wearwell/raw/branch/main/homepage.png" width="100%" height="500px">

</div>

## 📋 Table of Contents
- [✨ Features](#-features)
- [📁 Project Structure](#-project-structure)
- [🌐 Application Routes](#-application-routes)
- [🚀 Setup](#-setup)

## ✨ Features

### 🛒 Core E-commerce Features
- **User Management**: Registration, authentication, profiles, order history
- **Product Catalog**: Categories, filters, search, product variations
- **Shopping Cart**: Session-based cart, cart persistence, quantity management
- **Checkout Process**: Multi-step checkout, shipping options, payment integration
- **Order Management**: Order tracking, status updates, cancellation/returns
- **Inventory Management**: Stock tracking, low stock alerts, backorders
- **Reviews & Ratings**: Product reviews, star ratings, photo reviews

### 🎨 User Experience
- **Responsive Design**: Mobile-first, desktop-optimized interface
- **Image Gallery**: High-quality product images
- **Size Guides**: Interactive sizing charts, fit recommendations

### 🔧 Admin Features
- **Dashboard**: inventory overview

### 🛠️ Technical Features
- **Search Engine**: fast product search

## 📁 Project Structure

### Tree Structure of WearWell Project

```
wearwell/
├── .env.example              # Example environment of project (Database configures, etc)
├── .editorconfig             # Configurations of editor for formatting codes
├── app.py                    # Main Flask application entry point - initializes app, configures extensions, registers blueprints
├── extensions.py             # Centralized Flask extensions initialization (SQLAlchemy, Migrate, LoginManager, etc)
├── LICENSE                   # Project license file (GPL)
├── models.py                 # Database models definition (SQLAlchemy ORM - User, Product, Order, Cart, etc)
├── README.md                 # Project documentation, setup instructions, features overview
├── requirements.txt          # Python dependencies list for pip installation
├── seed_db.py               # Database seeding script - populates database with sample/test data
├── routes/                   # Flask route blueprints - modular URL routing by feature
│   ├── admin.py             # Admin panel routes - product management, user management, analytics
│   ├── auth.py              # Authentication routes - login, logout, registration, password reset
│   ├── cart.py              # Shopping cart operations - add/remove items, update quantities, view cart
│   ├── __init__.py          # Routes package initialization - exports blueprints
│   ├── main.py              # Public/main routes - homepage, product listings, search functionality
│   └── user.py              # User profile routes - profile management, order history, settings
├── static/                   # Static assets served directly by web server
│   ├── css/                 # Stylesheets for each page/component
│   │   ├── add_product.css      # Admin product addition form styling
│   │   ├── auth.css             # Login/registration form styling
│   │   ├── cart.css             # Shopping cart page styling
│   │   ├── categories.css       # Category listing/browsing styling
│   │   ├── checkout.css         # Checkout process styling
│   │   ├── dashboard.css        # Admin dashboard styling
│   │   ├── edit_product.css     # Admin product editing form styling
│   │   ├── home.css             # Homepage/landing page styling
│   │   ├── order_details.css    # Order summary and details page styling
│   │   ├── product_detail.css   # Individual product page styling
│   │   ├── products.css         # Product grid/listings styling
│   │   ├── profile.css          # User profile page styling
│   │   └── styles.css           # Global/base styles
│   ├── favicon.ico          # Browser tab/address bar icon
│   ├── images/              # Image assets (logos, backgrounds, etc)
│   │   └── default-product.jpg  # Fallback product image when none uploaded
│   └── js/                  # Client-side JavaScript files
│       ├── add_product.js       # Product form validation, image upload preview
│       ├── edit_product.js      # Product editing form interactions
│       ├── home.js              # Homepage animations, featured product carousel
│       ├── login.js             # Login form validation, password visibility toggle
│       ├── product_detail.js    # Product image gallery, quantity selector, add to cart
│       ├── products.js          # Product filtering, sorting, pagination
│       └── register.js          # Registration form validation, password strength
└── templates/               # Jinja2 HTML templates
    ├── admin/               # Admin panel templates
    │   ├── add_product.html    # Form for adding new products
    │   ├── categories.html     # Category management interface
    │   ├── dashboard.html      # Admin overview with statistics like CRUD table
    │   └── edit_product.html   # Form for editing existing products
    ├── base.html            # Base template with common layout (header, footer, nav)
    ├── cart.html            # Shopping cart display and management
    ├── checkout.html        # Checkout process steps and payment form
    ├── home.html            # Homepage/landing page
    ├── login.html           # User login form
    ├── order_details.html   # Detailed order confirmation and summary
    ├── product_detail.html  # Individual product display page
    ├── products.html        # Product grid/listings with filters
    ├── register.html        # User registration form
    └── user_profile.html    # User profile and order history
```

### Database Structure

<img src="https://git.broombox.org/amanfromspace/wearwell/raw/branch/main/diagram_wearwell_db.png" width="100%" height="768px">

## 🌐 Application Routes

### Main Routes

| Route | Template |  Description |
|-------|----------|--------------|
| `/` | `home.html` | Homepage with featured products and promotions |
| `/products` | `products.html` | Product catalog with filtering and sorting |
| `/login` | `login.html` | User authentication form |
| `/register` | `register.html` | New user registration form |
| `/cart` | `cart.html` | Shopping cart with items and quantities |
| `/profile` | `user_profile.html` | User profile management and personal information |
| `/checkout` | `checkout.html` | Order checkout process with payment and shipping |
| `/admin` | `admin/dashboard.html` | Admin dashboard with statistics and overview |

## 🚀 Setup

### Prerequisites
- **Python 3.12+** (also pip for installing requirements)
- **MariaDB 10+ (MySQL)** (Linux)
- **XAMPP 3.3.0+ (MySQL)** (Windows)

**Linux debian-based distros** (this apt command is only for practice it may be different)
```
sudo apt install python3.12 python3.12-venv mariadb-server mariadb-client
```

After installations of prerequisites depending on your OS follow the instructions below to run the web app

### Installation
First clone the project
```
git clone https://git.broombox.org/amanfromspace/wearwell.git
```
then go to the folder by using cd command
```
cd ./wearwell
```
now make virtual environment with python in your project (development mode not for production)
```
python3 -m venv venv
```
activate venv (linux)
```
source ./venv/bin/activate
```
activate venv (windows)
```
source venv/scripts/activate
```
you are ready to install requirements
```
pip install -r requirements.txt
```
it is time for your database to be ready - enter to mariadb and do the instructions
```
CREATE DATABASE wearwell;
```
better to use this specially with **utf8mb4_unicode_ci**
```
CREATE DATABASE IF NOT EXISTS wearwell
    CHARACTER SET utf8mb4
    COLLATE utf8mb4_unicode_ci;
```
create a user with password
```
CREATE USER 'wearwell'@'localhost' 
    IDENTIFIED BY 'password';
```
grant all privileges
```
GRANT ALL PRIVILEGES ON wearwell.* 
    TO 'wearwell'@'localhost';
```
apply it
```
FLUSH PRIVILEGES;
```
now you can exit from mariadb and edit your .env file (use .env.example template of project environment)
```
DB_USER=wearwell
DB_PASSWORD=password
DB_HOST=127.0.0.1
DB_PORT=3306
DB_NAME=wearwell
```
here is the structure of databse url in .env
```
mysql+pymysql://wearwell:password@127.0.0.1:3306/wearwell
├─────────────┘ ├──────┘ ├──────┘ ├───────┘ ├──┘ ├──────┘
│                │        │        │         │    └─── Database name
│                │        │        │         └─── Port
│                │        │        └─── Host/IP
│                │        └─── Password
│                └─── Username
└─── Database driver (mysql with pymysql connector)
```
> **⚠️ Warning:** Generate a random key as secret for your .env in production mode
it is time to initialize the models from models.py to migrate tables, ... into database
```
flask db init 
flask db migrate -m "Init"
flask db upgrade
```
> **📝 Important:** You can use seed_db.py for fake data ( users, products, ... )
```
python3 ./seed_db.py
```
resets data then fills data again
```
python ./seed_db.py --fresh
```
run the app
```
python3 ./app.py
```
