# 🗺️ Project Navigation Guide

Welcome! Here's where to find everything you need.

## 📖 Documentation

**Start Here:**
1. **[QUICKSTART.md](QUICKSTART.md)** ⭐ - Get up and running in 5 minutes
2. **[README.md](README.md)** - Complete setup and feature guide
3. **[PROJECT_OVERVIEW.md](PROJECT_OVERVIEW.md)** - Full completion checklist

**Reference:**
- **[API_DOCUMENTATION.md](API_DOCUMENTATION.md)** - All 30+ endpoints
- **[DATABASE.md](DATABASE.md)** - Database schema

---

## 📁 Folder Structure

### Backend (`/backend`)

**Start here:**
- `.env.example` - Copy to `.env` and update database URL
- `requirements.txt` - Python dependencies
- `seed.py` - Creates tables and sample data

**Main app:**
- `app/main.py` - FastAPI application
- `app/config.py` - Settings

**Database:**
- `app/database/database.py` - SQLAlchemy setup

**Data models:**
- `app/models/user.py` - User table
- `app/models/product.py` - Product table
- `app/models/category.py` - Category table
- `app/models/cart.py` - Cart tables
- `app/models/order.py` - Order tables
- `app/models/wishlist.py` - Wishlist table
- `app/models/contact_message.py` - Contact table

**API schemas (validation):**
- `app/schemas/user.py`
- `app/schemas/product.py`
- `app/schemas/category.py`
- `app/schemas/cart.py`
- `app/schemas/order.py`
- `app/schemas/wishlist.py`
- `app/schemas/contact.py`

**Business logic:**
- `app/services/auth.py` - Authentication
- `app/services/product.py` - Product operations
- `app/services/cart.py` - Cart operations
- `app/services/order.py` - Order operations

**API Routes:**
- `app/routers/auth.py` - Registration, login
- `app/routers/users.py` - User profiles
- `app/routers/products.py` - Product API
- `app/routers/categories.py` - Category API
- `app/routers/cart.py` - Shopping cart
- `app/routers/orders.py` - Orders
- `app/routers/wishlist.py` - Wishlist
- `app/routers/contact.py` - Contact form

---

### Frontend (`/frontend`)

**Start here:**
- `.env.example` - Copy to `.env`
- `package.json` - NPM dependencies
- `index.html` - HTML template
- `vite.config.js` - Vite configuration

**Main app:**
- `src/App.jsx` - Main component with routing
- `src/main.jsx` - Entry point
- `src/api.js` - Axios API client

**Layout components:**
- `src/components/Navbar.jsx` - Navigation bar
- `src/components/Footer.jsx` - Footer

**Product components:**
- `src/components/ProductCard.jsx` - Product card
- `src/components/CategoryCard.jsx` - Category card
- `src/components/ProductFilters.jsx` - Filter sidebar
- `src/components/SearchBar.jsx` - Search functionality

**Pages:**
- `src/pages/Home.jsx` - Home page
- `src/pages/Products.jsx` - Product listing
- `src/pages/ProductDetail.jsx` - Product details
- `src/pages/Cart.jsx` - Shopping cart
- `src/pages/Checkout.jsx` - Checkout page
- `src/pages/Login.jsx` - Login page
- `src/pages/Register.jsx` - Registration page
- `src/pages/Profile.jsx` - User profile
- `src/pages/Orders.jsx` - Order history
- `src/pages/Wishlist.jsx` - Wishlist
- `src/pages/About.jsx` - About page
- `src/pages/Contact.jsx` - Contact page
- `src/pages/Sales.jsx` - Sales page

**State management:**
- `src/context/AuthContext.jsx` - Authentication state
- `src/context/CartContext.jsx` - Shopping cart state

**Styling:**
- `src/styles/global.css` - All styles (responsive design)

---

## 🚀 Quick Commands

### Backend

```bash
# Install dependencies
pip install -r requirements.txt

# Set up database
python seed.py

# Run server
uvicorn app.main:app --reload

# API docs at http://localhost:8000/docs
```

### Frontend

```bash
# Install dependencies
npm install

# Run dev server
npm run dev

# Build for production
npm run build
```

---

## 🔑 Key Features by File

### Authentication
- **Backend:** `app/routers/auth.py`, `app/services/auth.py`
- **Frontend:** `src/context/AuthContext.jsx`, `src/pages/Login.jsx`

### Shopping Cart
- **Backend:** `app/models/cart.py`, `app/services/cart.py`
- **Frontend:** `src/context/CartContext.jsx`, `src/pages/Cart.jsx`

### Products
- **Backend:** `app/models/product.py`, `app/services/product.py`
- **Frontend:** `src/components/ProductCard.jsx`, `src/pages/Products.jsx`

### Orders
- **Backend:** `app/models/order.py`, `app/services/order.py`
- **Frontend:** `src/pages/Orders.jsx`, `src/pages/Checkout.jsx`

### Search & Filter
- **Frontend:** `src/components/SearchBar.jsx`, `src/components/ProductFilters.jsx`

### Admin Features
- **Product CRUD:** `app/routers/products.py`
- **Category CRUD:** `app/routers/categories.py`

---

## 🎯 Common Tasks

### Add a New Product

*Via API:*
```bash
POST /api/products
{
  "name": "Product Name",
  "description": "...",
  "price": 99.99,
  "category_id": 1,
  "gender": "men",
  "brand": "Brand",
  "sizes": ["8", "9", "10"],
  "colors": ["Black", "White"],
  "stock": 50,
  "images": ["url"],
  "is_featured": false,
  "is_on_sale": false
}
```

*Via database seed:*
Edit `backend/seed.py` and add to `products_data` list, then run `python seed.py`

### Change Styling

Edit `frontend/src/styles/global.css` - all styles are here (1200+ lines)

### Add a New Page

1. Create file in `frontend/src/pages/NewPage.jsx`
2. Add route in `frontend/src/App.jsx`:
   ```jsx
   <Route path="/newpage" element={<NewPage />} />
   ```
3. Add link in navbar or footer

### Create New API Endpoint

1. Create model in `backend/app/models/`
2. Create schema in `backend/app/schemas/`
3. Create service in `backend/app/services/`
4. Create route in `backend/app/routers/`
5. Include router in `backend/app/main.py`

---

## 🐛 Troubleshooting

**Can't connect to database?**
- Check PostgreSQL is running
- Verify credentials in `.env`
- See [README.md](README.md#troubleshooting)

**Frontend not loading?**
- Check backend is running on port 8000
- Check `VITE_API_URL` in `.env`

**Port already in use?**
```bash
# Use different port
uvicorn app.main:app --port 8001
npm run dev -- --port 5174
```

For more: [QUICKSTART.md](QUICKSTART.md#troubleshooting)

---

## 📚 Learning Resources

**FastAPI:**
- Official docs: https://fastapi.tiangolo.com/
- Tutorial: https://fastapi.tiangolo.com/tutorial/

**React:**
- Official docs: https://react.dev/
- Tutorial: https://react.dev/learn

**Vite:**
- Official docs: https://vitejs.dev/
- Guide: https://vitejs.dev/guide/

**PostgreSQL:**
- Official docs: https://www.postgresql.org/docs/
- Tutorials: https://www.postgresql.org/docs/current/tutorial.html

---

## 💡 Pro Tips

1. **Use FastAPI docs** - Visit `http://localhost:8000/docs` to test all endpoints
2. **Browser DevTools** - Use Network tab to debug API calls
3. **React DevTools** - Install React extension for debugging
4. **Database client** - Use pgAdmin or DBeaver to view database

---

## 📞 Questions?

- Check the relevant documentation file above
- Review comments in the code
- Look at similar implementations in the codebase
- Check [API_DOCUMENTATION.md](API_DOCUMENTATION.md) for endpoint details

---

## ✅ Next Steps

1. **Read** [QUICKSTART.md](QUICKSTART.md) - 5-minute setup
2. **Set up** backend and frontend following the guide
3. **Test** with demo account (user@example.com / password123)
4. **Customize** branding and content
5. **Deploy** to production

**You're all set! Happy coding! 🚀**