229 lines
9.8 KiB
Markdown
229 lines
9.8 KiB
Markdown
# 🛍️ Wearwell - Modern E-commerce Clothing Store
|
|
|
|
<div align="center">
|
|
|
|
|
|
|
|
|
|
|
|
**WearWell - a simple flask shopping web app for clothes**
|
|
|
|
<img src="http://g.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="http://g.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 http://g.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
|
|
```
|