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:
```bash
# Create database
psql -U postgres
CREATE DATABASE ecommerce_db;
\q
```

### 2. Create Virtual Environment

```bash
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

```bash
pip install -r requirements.txt
```

### 4. Configure Environment Variables

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

```bash
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

```bash
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

```bash
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

```bash
cd frontend
npm install
```

### 2. Configure Environment Variables

Copy `.env.example` to `.env`:

```bash
cp .env.example .env
```

Edit `.env`:
```
VITE_API_URL=http://localhost:8000/api
VITE_APP_NAME=StyleHub
```

### 3. Run Development Server

```bash
npm run dev
```

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

### 4. Build for Production

```bash
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:**
```bash
# 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/