dvirlabs/brand-master
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
brand-master/NAVIGATION.md
dvirlabs d182f76201 Initial app
2026-05-01 11:12:13 +03:00

7.1 KiB
Raw Blame History

🗺️ Project Navigation Guide

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

📖 Documentation

Start Here:

  1. QUICKSTART.md ⭐ - Get up and running in 5 minutes
  2. README.md - Complete setup and feature guide
  3. PROJECT_OVERVIEW.md - Full completion checklist

Reference:

📁 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

# 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

# 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:

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: 
    <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

Frontend not loading?

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

Port already in use?

# Use different port
uvicorn app.main:app --port 8001
npm run dev -- --port 5174

For more: QUICKSTART.md

📚 Learning Resources

FastAPI:

React:

Vite:

PostgreSQL:

💡 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 for endpoint details

✅ Next Steps

  1. Read 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! 🚀