brand-master/README.md

E-Commerce Website - Full Setup Guide

This is a complete, fully functional e-commerce website for selling clothes and shoes with both backend and frontend fully connected.

Project Structure

ecommerce/
├── backend/                 # FastAPI backend
│   ├── app/
│   │   ├── main.py         # Main FastAPI app
│   │   ├── config.py       # Configuration
│   │   ├── database/       # Database setup
│   │   ├── models/         # SQLAlchemy models
│   │   ├── schemas/        # Pydantic schemas
│   │   ├── services/       # Business logic
│   │   └── routers/        # API endpoints
│   ├── seed.py             # Seed data script
│   ├── requirements.txt    # Python dependencies
│   └── .env.example        # Environment variables example
│
└── frontend/               # React + Vite frontend
    ├── src/
    │   ├── components/     # Reusable components
    │   ├── pages/          # Page components
    │   ├── context/        # React context
    │   ├── styles/         # CSS styles
    │   ├── App.jsx         # Main App component
    │   ├── main.jsx        # Entry point
    │   └── api.js          # API client
    ├── index.html          # HTML template
    ├── package.json        # NPM dependencies
    ├── vite.config.js      # Vite configuration
    └── .env.example        # Environment variables example

System Requirements

• Python 3.8+
• Node.js 16+
• PostgreSQL 12+ (running locally or accessible)
• npm or yarn

Backend Setup

1. Install PostgreSQL

Download and install PostgreSQL from https://www.postgresql.org/download/

After installation:

# Create database
psql -U postgres
CREATE DATABASE ecommerce_db;
\q

2. Create Virtual Environment

cd backend

# On Windows
python -m venv venv
venv\Scripts\activate

# On macOS/Linux
python3 -m venv venv
source venv/bin/activate

3. Install Dependencies

pip install -r requirements.txt

4. Configure Environment Variables

Copy .env.example to .env and update with your database credentials:

cp .env.example .env

Edit .env:

DATABASE_URL=postgresql://postgres:your_password@localhost:5432/ecommerce_db
JWT_SECRET_KEY=your-super-secret-key-change-this
JWT_ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30
FRONTEND_URL=http://localhost:5173

5. Create Database Tables

python seed.py

This will create all tables and seed sample data including categories, products (with focus on shoes), and test users.

6. Run Backend Server

uvicorn app.main:app --reload --port 8000

Server will be available at: http://localhost:8000 API documentation: http://localhost:8000/docs

Frontend Setup

1. Install Node Modules

cd frontend
npm install

2. Configure Environment Variables

Copy .env.example to .env:

cp .env.example .env

Edit .env:

VITE_API_URL=http://localhost:8000/api
VITE_APP_NAME=StyleHub

3. Run Development Server

npm run dev

Frontend will be available at: http://localhost:5173

4. Build for Production

npm run build

Features

Authentication

• User registration and login
• JWT token-based authentication
• User profile management
• Persistent login using localStorage

Products

• Browse all products
• Filter by category, gender, price
• Search products by name or brand
• Product detail pages with images, specifications
• Product reviews and ratings
• Featured products and new arrivals

Shopping

• Add/remove items from cart
• Update quantities
• View cart with price calculations
• Checkout process
• Order history

User Features

• User registration
• Login/logout
• User profile with shipping address
• Order history
• Wishlist/favorites
• Add/remove from wishlist

Admin Features

• Add new products
• Edit existing products
• Delete products
• Manage stock quantities
• Mark products as featured or on sale

Pages

1. Home - Hero section, featured products, categories, deals
2. Products - Product listing with filters and sorting
3. Product Detail - Full product information
4. Categories - Men, Women, Shoes, Shirts, Pants, Hats, Accessories
5. Sales - Discounted products and limited-time offers
6. About - Company story and values
7. Contact - Contact form, store information
8. Cart - Shopping cart with summary
9. Checkout - Order confirmation and shipping address
10. Login/Register - Authentication pages
11. Profile - User account information
12. Orders - Order history and tracking
13. Wishlist - Saved favorite products

API Endpoints

Authentication

• POST /api/auth/register - Register new user
• POST /api/auth/login - Login user
• POST /api/auth/verify-token - Verify JWT token

Users

• GET /api/users/me - Get current user profile
• PUT /api/users/me - Update user profile
• GET /api/users/{user_id} - Get user by ID

Products

• GET /api/products - List products (with filters)
• GET /api/products/search - Search products
• GET /api/products/{id} - Get product details
• POST /api/products - Create product (admin)
• PUT /api/products/{id} - Update product (admin)
• DELETE /api/products/{id} - Delete product (admin)

Categories

• GET /api/categories - List all categories
• GET /api/categories/{id} - Get category
• POST /api/categories - Create category (admin)
• PUT /api/categories/{id} - Update category (admin)
• DELETE /api/categories/{id} - Delete category (admin)

Cart

• GET /api/cart - Get user's cart
• POST /api/cart/add - Add item to cart
• PUT /api/cart/{item_id} - Update cart item
• DELETE /api/cart/{item_id} - Remove item from cart
• DELETE /api/cart - Clear cart

Orders

• POST /api/orders - Create order
• GET /api/orders/user/orders - Get user's orders
• GET /api/orders/{id} - Get order details

Wishlist

• GET /api/wishlist - Get user's wishlist
• POST /api/wishlist/{product_id} - Add to wishlist
• DELETE /api/wishlist/{product_id} - Remove from wishlist

Contact

• POST /api/contact - Send contact message

Test Credentials

Demo account for testing:

• Email: user@example.com
• Password: password123

Or create a new account through the registration page.

Database Schema

Users Table

• id (Primary Key)
• email (Unique)
• hashed_password
• full_name
• phone, address, city, postal_code, country
• is_active
• created_at

Products Table

• id (Primary Key)
• name, description
• price, discount_price
• category_id (Foreign Key)
• gender (men/women)
• brand
• sizes (JSON array)
• colors (JSON array)
• stock (quantity)
• images (JSON array)
• is_featured, is_on_sale
• created_at

Categories Table

• id (Primary Key)
• name (Unique)
• slug (Unique)
• description

Cart & CartItems Tables

• cart_id (Foreign Key to User)
• cart_item_id (Product, quantity, size, color)

Orders & OrderItems Tables

• order_id (User, status, total, shipping info)
• order_item_id (Product, quantity, price at purchase time)

Wishlist Table

• user_id, product_id (Foreign Keys)
• created_at

ContactMessages Table

• id (Primary Key)
• name, email, subject, message
• created_at

Troubleshooting

Backend Issues

PostgreSQL connection error:

• Ensure PostgreSQL is running
• Check DATABASE_URL in .env
• Verify username and password

Import errors:

• Make sure virtual environment is activated
• Run pip install -r requirements.txt again

Frontend Issues

API not responding:

• Check backend is running on port 8000
• Check VITE_API_URL in .env

Port already in use:

# Find and kill process on port
# On Windows
netstat -ano | findstr :5173
taskkill /PID <PID> /F

# On macOS/Linux
lsof -ti:5173 | xargs kill -9

Development Notes

• Backend is built with FastAPI for high performance
• Frontend uses React with Vite for fast development
• SQLAlchemy handles database operations
• JWT for secure authentication
• CORS enabled for frontend-backend communication
• All responses follow RESTful API standards

Production Deployment

For production:

1. Set DEBUG=False in backend config
2. Use a production database server
3. Configure proper CORS settings
4. Use environment-specific .env files
5. Deploy frontend as static assets
6. Use a production WSGI server (Gunicorn)
7. Set up HTTPS/SSL certificates

Contributing

This is a template project. Feel free to customize and extend with:

• Payment gateway integration
• Email notifications
• Advanced analytics
• Admin dashboard
• Mobile app
• Inventory management system

License

This project is open source and available for personal and commercial use.

Support

For issues or questions, check:

• FastAPI docs: https://fastapi.tiangolo.com/
• React docs: https://react.dev/
• SQLAlchemy docs: https://docs.sqlalchemy.org/
• Vite docs: https://vitejs.dev/