# SnapLocal Implementation Guide

## ✅ MVP Features Implemented (Complete)

### Backend (Node.js + MongoDB)

#### 1. **Package System** ✓
- **Model**: `server/src/models/Package.js`
- **Routes**: `server/src/routes/packageRoutes.js`
- **Endpoints**:
  - `GET /api/packages/photographer/:photographerId` - Get photographer's packages
  - `GET /api/packages/:id` - Get single package
  - `POST /api/packages` - Create new package (auth required)
  - `PUT /api/packages/:id` - Update package (auth required)
  - `DELETE /api/packages/:id` - Delete package (auth required)

#### 2. **Photographer Verification** ✓
- **Model**: `server/src/models/Verification.js`
- **Routes**: `server/src/routes/verificationRoutes.js`
- **Endpoints**:
  - `GET /api/verification/status/:photographerId` - Get verification status
  - `POST /api/verification/submit` - Upload documents (auth required)
  - `POST /api/verification/:verificationId/approve` - Admin approve
  - `POST /api/verification/:verificationId/reject` - Admin reject

#### 3. **Photo Delivery** ✓
- **Model**: `server/src/models/PhotoDelivery.js`
- **Routes**: `server/src/routes/deliveryRoutes.js`
- **Endpoints**:
  - `GET /api/delivery/booking/:bookingId` - Get delivery status
  - `POST /api/delivery/booking/:bookingId` - Create delivery record
  - `POST /api/delivery/:deliveryId/upload` - Upload photos (auth required)
  - `POST /api/delivery/:deliveryId/complete` - Mark as delivered
  - `POST /api/delivery/:deliveryId/request-revision` - Request revisions

#### 4. **Invoice Generator** ✓
- **Model**: `server/src/models/Invoice.js`
- **Routes**: `server/src/routes/invoiceRoutes.js`
- **Endpoints**:
  - `GET /api/invoices/:id` - Get invoice
  - `GET /api/invoices/user/:userId` - Get user's invoices
  - `POST /api/invoices` - Create invoice
  - `PUT /api/invoices/:id/payment` - Update payment status
  - `GET /api/invoices/:id/download` - Download invoice

#### 5. **Smart Tags (Enhanced Search)** ✓
- Implemented in `Photographer.js` model with tags array
- Frontend Search component with tag filters

#### 6. **Additional Models Created** ✓
- **Loyalty Points** (`server/src/models/LoyaltyPoints.js`)
- **Report System** (`server/src/models/Report.js`)
- **Trip Planner** (`server/src/models/TripPlan.js`)
- **Dynamic Pricing** (`server/src/models/DynamicPrice.js`)
- **Deals/Discounts** (`server/src/models/Deal.js`)

---

### Frontend (React + Vite)

#### Components Created ✓

**Photographer Dashboard Components:**
- `PackagePanel.jsx` - Create and manage packages
- `PackageCard.jsx` - Individual package card display
- `CreatePackageModal.jsx` - Modal form for creating/editing packages
- `VerificationPanel.jsx` - Verification document upload and status
- `DeliveryPanel.jsx` - Photo upload and delivery management
- `InvoiceView.jsx` - Invoice display and download

**Customer Dashboard Components:**
- `TrendingSpots.jsx` - Popular photography locations
- `LastMinuteDeals.jsx` - Time-limited discount offers
- `Leaderboard.jsx` - Top photographers by rating
- `ShootTimeline.jsx` - Booking progress timeline

**Utilities:**
- `src/utils/invoiceGenerator.js` - Invoice HTML generation and PDF export

---

## 📱 Technology Stack

### Backend
- **Express.js** - REST API server
- **MongoDB** - Database
- **Mongoose** - ODM
- **JWT** - Authentication
- **Socket.io** - Real-time messaging (already in place)

### Frontend
- **React 19.2.4** - UI framework
- **Vite 8.0.0** - Build tool
- **Tailwind CSS 4.2.1** - Styling
- **Lucide React** - Icons
- **Axios** - HTTP client

---

## 🚀 How to Run

### Prerequisites
- Node.js 18+
- MongoDB running locally or cloud URL in `.env`
- npm or yarn

### 1. Install Dependencies

```bash
# Backend
cd server
npm install

# Frontend
cd ../client
npm install
```

### 2. Configure Environment

Create `server/.env`:
```env
MONGODB_URI=mongodb://localhost:27017/snaplocal
PORT=5000
JWT_SECRET=your_secret_key
```

### 3. Start Development Servers

```bash
# Terminal 1: Backend
cd server
npm run dev
# Server runs on http://localhost:5000

# Terminal 2: Frontend
cd client
npm run dev
# Client runs on http://localhost:5173
```

---

## 📊 API Usage Examples

### Create a Package (Photographer)
```javascript
// POST http://localhost:5000/api/packages
{
  "name": "Premium Wedding Package",
  "description": "8 hours coverage with 300+ edited photos",
  "price": 15000,
  "priceUnit": "session",
  "duration": 8,
  "deliverables": {
    "numPhotos": 350,
    "numEdited": 200,
    "numLocations": 2,
    "includesAlbum": true
  },
  "tags": ["wedding", "bride", "groom"]
}
```

### Submit Verification
```javascript
// POST http://localhost:5000/api/verification/submit
{
  "idDocumentUrl": "https://example.com/aadhar.jpg",
  "portfolioUrls": [
    "https://example.com/photo1.jpg",
    "https://example.com/photo2.jpg"
  ]
}
```

### Upload Photos for Delivery
```javascript
// POST http://localhost:5000/api/delivery/{deliveryId}/upload
{
  "photoUrls": [
    "https://example.com/photo1.jpg",
    "https://example.com/photo2.jpg",
    // ... more photos
  ]
}
```

### Create Invoice
```javascript
// POST http://localhost:5000/api/invoices
{
  "bookingId": "booking_id_here",
  "photographerId": "photographer_id",
  "customerId": "customer_id",
  "items": [
    {
      "description": "Premium Wedding Photography",
      "quantity": 1,
      "unitPrice": 15000,
      "total": 15000
    }
  ],
  "subtotal": 15000,
  "tax": 2700,
  "taxRate": 18,
  "totalAmount": 17700
}
```

---

## 🎯 Dashboard Features

### Photographer Dashboard
1. **Overview** - Statistics (bookings, revenue, pending, rating)
2. **My Profile** - Edit bio, specialty, rate, experience
3. **Portfolio** - Upload images/videos
4. **Packages** ⭐ - Create and manage service packages
5. **Verification** ⭐ - Upload documents for verification badge
6. **Availability** - Set weekly schedule
7. **Bookings** - Manage booking requests with timeline
8. **Photo Delivery** ⭐ - Upload and deliver photos to customers
9. **Reports** - View and respond to customer complaints

### Customer Dashboard
1. **Search** - Find photographers (enhanced with tag filters)
2. **Trending Spots** ⭐ - Popular photography locations
3. **Last-Minute Deals** ⭐ - Time-limited discounts
4. **Nearby Photographers** - Map view with location filtering
5. **My Bookings** - Manage reservations and download photos
6. **Leaderboard** ⭐ - Top-rated photographers
7. **Loyalty/Rewards** - Points and tier benefits
8. **Trip Planner** - Plan photo shoot trips

---

## 📂 File Structure Summary

```
server/src/
├── models/
│   ├── Package.js           ✓ NEW
│   ├── Verification.js      ✓ NEW
│   ├── PhotoDelivery.js     ✓ NEW
│   ├── Invoice.js           ✓ NEW
│   ├── LoyaltyPoints.js     ✓ NEW
│   ├── Report.js            ✓ NEW
│   ├── TripPlan.js          ✓ NEW
│   ├── DynamicPrice.js      ✓ NEW
│   └── Deal.js              ✓ NEW
├── routes/
│   ├── packageRoutes.js     ✓ NEW
│   ├── verificationRoutes.js✓ NEW
│   ├── deliveryRoutes.js    ✓ NEW
│   ├── invoiceRoutes.js     ✓ NEW
│   ├── reportRoutes.js      ✓ NEW
│   ├── loyaltyRoutes.js     ✓ NEW
│   ├── tripPlanRoutes.js    ✓ NEW
│   └── dealRoutes.js        ✓ NEW
└── index.js                 ✓ UPDATED

client/src/
├── components/
│   ├── PackagePanel.jsx     ✓ NEW
│   ├── PackageCard.jsx      ✓ NEW
│   ├── CreatePackageModal.jsx✓ NEW
│   ├── VerificationPanel.jsx ✓ NEW
│   ├── DeliveryPanel.jsx    ✓ NEW
│   ├── InvoiceView.jsx      ✓ NEW
│   ├── TrendingSpots.jsx    ✓ NEW
│   ├── LastMinuteDeals.jsx  ✓ NEW
│   ├── Leaderboard.jsx      ✓ NEW
│   └── ShootTimeline.jsx    ✓ NEW
└── utils/
    └── invoiceGenerator.js  ✓ NEW
```

---

## ✨ Next Steps (Phase 2+)

### Advanced Features
1. **AI-Powered Features**
   - Style matching (upload reference photo for similar photographers)
   - Dynamic pricing suggestions based on demand
   - Smart recommendations

2. **Enhanced Search**
   - Geolocation-based photographer search
   - Advanced filters (availability, price range, ratings, tags)

3. **Performance Analytics**
   - Charts and graphs for photographer earnings/bookings
   - Customer analytics for trends

4. **Trip Planning**
   - Itinerary builder
   - Recommended photography spots
   - Travel packages

5. **Additional Features**
   - Watermark protection for portfolio images
   - Live photographer availability map
   - Video introductions for photographers
   - Social sharing buttons

---

## 🔐 Security Notes

- All protected routes require JWT authentication
- Password hashing with bcryptjs (already implemented)
- CORS enabled for development
- Input validation needed (in production)
- Rate limiting recommended for API endpoints

---

## 📊 Database Schema Overview

### Package
```
{
  photographerId, name, description, price, priceUnit, duration,
  deliverables: { numPhotos, numEdited, numLocations, includesAlbum },
  active, bookingCount, tags, timestamps
}
```

### Verification
```
{
  photographerId, status (pending|verified|rejected),
  idDocument, portfolioSamples[], submittedAt, verifiedAt,
  adminNotes, rejectionReason, timestamps
}
```

### Invoice
```
{
  invoiceNumber, bookingId, photographerId, customerId,
  items[], subtotal, tax, taxRate, discount, totalAmount,
  paymentStatus, paidAt, timestamps
}
```

### PhotoDelivery
```
{
  bookingId, photographerId, customerId, photos[],
  status (pending|partially_delivered|delivered|revision_requested),
  deliveredAt, downloadLink, linkExpiresAt, revisionNotes, timestamps
}
```

---

## 🎓 Code Examples

### Use PackagePanel in Dashboard
```jsx
import PackagePanel from '../components/PackagePanel';

export default function PhotographerDashboard() {
  const { user } = useAuth();
  return <PackagePanel photographerId={user.id} />;
}
```

### Use DeliveryPanel in Booking Page
```jsx
import DeliveryPanel from '../components/DeliveryPanel';

export default function BookingDetail({ bookingId }) {
  return (
    <DeliveryPanel
      bookingId={bookingId}
      photographerId={currentPhotographerId}
      role="photographer"
    />
  );
}
```

### Generate and Download Invoice
```jsx
import { downloadInvoiceAsPDF } from '../utils/invoiceGenerator';

const handleDownload = (invoice, photographer, customer) => {
  downloadInvoiceAsPDF(invoice, photographer, customer);
};
```

---

## 🐛 Troubleshooting

### Port Already in Use
```bash
# Kill process on port 5000
lsof -i :5000
kill -9 <PID>
```

### MongoDB Connection Failed
- Ensure MongoDB is running: `mongod`
- Check MONGODB_URI in `.env`
- Verify connection string format

### Components Not Loading
- Clear Vite cache: `rm -rf client/node_modules/.vite`
- Restart dev server

---

## 📝 Future Enhancements

- [ ] Payment gateway integration (Stripe/Razorpay)
- [ ] Email notifications for bookings
- [ ] SMS alerts for photographers
- [ ] Multi-language support
- [ ] Mobile app (React Native)
- [ ] Admin dashboard
- [ ] Analytics and reporting
- [ ] Advanced booking calendar with time slots
- [ ] Subscription tiers for photographers
- [ ] Automated invoice generation and payment reminders

---

## 📞 Support

For issues or questions:
1. Check the Feature Implementation Map: `/FEATURE_IMPLEMENTATION_MAP.md`
2. Review API routes in respective `server/src/routes/` files
3. Check component prop requirements in `client/src/components/`

---

**Version**: 1.0.0 MVP
**Last Updated**: March 18, 2026
**Status**: ✅ Complete and Running