294 lines
7.1 KiB
Markdown
294 lines
7.1 KiB
Markdown
# 🗺️ 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! 🚀**
|