# BazarExa - Full LLM & Agent Documentation

> Comprehensive technical and architectural reference for LLM search agents, crawlers, and AI integrations interacting with BazarExa (https://www.bazarexa.com).

---

## 1. Platform Overview

- **Platform Name**: BazarExa
- **Website URL**: https://www.bazarexa.com
- **Type**: Multi-Vendor E-Commerce Marketplace & Digital Retail Platform
- **Primary Market**: Pakistan (Nationwide Delivery, PKR Currency, Cash on Delivery & Digital Payments)
- **Technology Stack**:
  - **Framework**: Next.js 16 (App Router), React 19, TypeScript
  - **Database & ORM**: PostgreSQL with Prisma ORM
  - **State & UI**: Redux Toolkit, Ant Design, Lucide React, Tailwind CSS
  - **Media Storage**: Cloudinary Media Management
  - **Authentication**: Custom JWT Auth + NextAuth / Google OAuth, OTP verification via Nodemailer
  - **Notification/Backend Services**: Firebase, Nodemailer

---

## 2. Core Entities & Data Architecture (Prisma Schema)

### 2.1 User & Authentication
- **User**:
  - `id`: String (cuid)
  - `name`: String (optional)
  - `email`: String (unique)
  - `password`: String (bcrypt hashed)
  - `userType`: String (e.g., 'Customer', 'Seller', 'Admin')
  - `isActive`: Boolean
  - `cnic`: String (optional, national ID)
  - `contactNo`: String (optional)
  - `userRoleId`: Int (relation to `UserRole`)
  - `storesId`: Int (relation to `Stores` if associated with a store)

### 2.2 Stores & Seller Management
- **Stores**:
  - `id`: Int (auto-increment)
  - `name`: String
  - `slug`: String
  - `ownerId`: String (FK -> User)
  - `storeTypeId`: Int (FK -> StoreType)
  - `address`, `city`, `state`, `country`, `contact`, `email`: Store location & contact
  - `isActive`: Boolean
  - `isSuspended`: Boolean
  - `covers`: String[] (banner image URLs)
  - `logo`: String (logo URL)
  - `bankName`, `branchName`, `bacnkAccountNumber`, `bacnkIBANNumber`: Banking settlement info
  - `cnicNumber`, `ntnNumber`: Business verification documents
- **StoreType**:
  - `id`: Int
  - `name`: String (e.g., Starter, Professional, Enterprise)
  - `productLimit`: Int (maximum allowed active products)
  - `advLimit`: Int (promotional campaign limit)
- **StoresRequest**:
  - Merchant onboarding application with status flags (`isApproved`, `isRejected`, `isStoreCreated`, `rejectReason`).
- **SalesAgent**:
  - Sub-accounts attached to a store (`storeId`) for delegated fulfillment and catalog operations.

### 2.3 Product Catalog & Variants
- **Product**:
  - `id`: Int (auto-increment)
  - `name`: String
  - `slug`: String (unique URL slug for SEO routing)
  - `description`: String (rich product description)
  - `price`: Decimal (base listing price in PKR)
  - `discount`: Decimal (optional discounted price)
  - `discountPercentage`: Int (percentage off)
  - `color`: String[]
  - `imageUrl`: String[] (Cloudinary image URLs)
  - `weight`, `weightInkg`: Decimal (shipping weight calculation)
  - `brand`: String
  - `gender`: String (e.g., 'Men', 'Women', 'Unisex', 'Kids')
  - `quantity`: Int (total available inventory)
  - `categoryId`: Int (FK -> Category)
  - `storesId`: Int (FK -> Stores)
  - `sku`: String (Stock Keeping Unit)
  - `isPublished`: Boolean
  - `isApproved`: Boolean (admin approval status)
  - `isOutOfStock`: Boolean
  - `isFeatured`: Boolean
  - `isFreeDelivery`: Boolean (zero shipping fee eligibility)
  - `userRating`: Int (accumulated rating score)
  - `userRatingPerson`: Int (total review count)
- **ProductVarient**:
  - `id`: Int
  - `productId`: Int (FK -> Product)
  - `label`: String (e.g., "Size: M / Color: Black")
  - `availableStock`: Int
  - `price`: Decimal
  - `imageUrl`: String[]
  - `isOutOfStock`: Boolean
- **Category**:
  - `id`: Int
  - `name`: String
  - `parentCategoryId`: Int (self-referential hierarchy for nested subcategories)
  - `commissionpercentage`: Int
  - `image`, `coverImage`: URLs

### 2.4 Orders & Checkout
- **Order**:
  - `id`: Int (auto-increment order identifier)
  - `userId`: String (user ID or anonymous guest ID)
  - `firstName`, `lastName`, `email`, `phoneNumber`: Customer contact info
  - `address`, `city`, `zipCode`, `country`: Shipping destination
  - `storeId`: Int (FK -> Stores)
  - `totalAmount`: Int
  - `discount`: Int
  - `finalAmount`: Int (grand total payable in PKR)
  - `orderStatus`: String ('Pending', 'Processing', 'Shipped', 'Delivered', 'Cancelled')
  - `paymentMood`: String ('Cash' on delivery, 'Card', 'BankTransfer')
  - `paymentStatus`: String ('Pending', 'Paid', 'Failed')
  - `orderDate`, `dispatchDate`, `deliveryDate`: Fulfillment lifecycle timestamps
- **OrderDetails**:
  - Line items containing `orderId`, `productId`, `quantity`, `price`, and `productVariantId`.
- **Cart**:
  - Temporary persistent cart lines for authenticated/unauthenticated sessions.

---

## 3. Core Storefront Routes & Discovery Structure

| Route | Purpose & Description | Indexing Priority |
| :--- | :--- | :--- |
| `https://www.bazarexa.com/` | Homepage featuring carousel banners, top categories, recommended products, flash deals, and new arrivals. | 1.0 |
| `https://www.bazarexa.com/product` | Search and explore all products with multifaceted filtering (category, price, brand, stock, free delivery). | 0.9 |
| `https://www.bazarexa.com/product/[slug]` | Dedicated Product Detail Page (PDP) with high-res galleries, variant selection, seller information, reviews, and related products. | 0.8 |
| `https://www.bazarexa.com/flashsale` | Flash sale showcase featuring limited-time promotions with discount tags and live countdown timers. | 0.9 |
| `https://www.bazarexa.com/freedelivery` | Catalog of items with zero delivery charges across Pakistan. | 0.8 |
| `https://www.bazarexa.com/createstore` | Public portal for prospective merchants to apply for an online store. | 0.8 |
| `https://www.bazarexa.com/anonymousorder` | Guest order lookup and tracking by Order ID and phone number. | 0.5 |
| `https://www.bazarexa.com/privacypolicy` | Official privacy policy, user data handling, and security guarantees. | 0.3 |
| `https://www.bazarexa.com/termsandcondition` | Marketplace terms of service, dispute resolution, buyer protection, and merchant policies. | 0.3 |

---

## 4. Top Shopping Categories & URL Taxonomies

1. **Smartwatches & Wearables** (`categoryId=9`)
   - URL: `https://www.bazarexa.com/product?categoryId=9`
   - Description: Android and iOS compatible smartwatches, fitness trackers, wireless charging smart bands, silicone and metallic straps.
2. **Perfumes & Fragrances** (`categoryId=5`)
   - URL: `https://www.bazarexa.com/product?categoryId=5`
   - Description: Men's and women's long-lasting perfumes, Eau de Parfum, body sprays, attars, and premium fragrance gift sets.
3. **Shoes & Footwear** (`categoryId=11`)
   - URL: `https://www.bazarexa.com/product?categoryId=11`
   - Description: Men's formal leather shoes, casual sneakers, running trainers, loafers, and boots.
4. **Mobile Accessories** (`categoryId=12`)
   - URL: `https://www.bazarexa.com/product?categoryId=12`
   - Description: High-speed fast chargers, USB-C/Lightning cables, magnetic power banks, Bluetooth earbuds, and protective phone cases.

---

## 5. API Reference & Request Contracts

### 5.1 Product Catalog API
- **Endpoint**: `GET /api/product`
- **Query Parameters**:
  - `page` (number, default: 1): Page index for pagination.
  - `limit` (number, default: 20): Products per page.
  - `search` (string): Search query matching product title, description, brand, or SKU.
  - `categoryId` (number): Filter by category ID.
  - `minPrice` / `maxPrice` (number): Filter by price boundary.
  - `brand` (string): Filter by brand name.
  - `isFeatured` (boolean): Fetch curated/featured listings.
  - `isFreeDelivery` (boolean): Fetch products with free delivery.
  - `storesId` (number): Fetch products belonging to a specific store.
- **Response**:
  ```json
  {
    "success": true,
    "data": [
      {
        "id": 101,
        "name": "Ultra Smartwatch Series 9",
        "slug": "ultra-smartwatch-series-9",
        "price": "4999.00",
        "discount": "3999.00",
        "discountPercentage": 20,
        "imageUrl": ["https://res.cloudinary.com/.../watch1.png"],
        "brand": "TechGear",
        "isFreeDelivery": true,
        "userRating": 5,
        "userRatingPerson": 24,
        "category": { "id": 9, "name": "Smartwatches" }
      }
    ],
    "total": 120,
    "page": 1,
    "totalPages": 6
  }
  ```

### 5.2 Flash Sale API
- **Endpoint**: `GET /api/product/flashsale`
- **Response**: Array of active flash sale items with promotional prices and discount tags.

### 5.3 Category Hierarchy API
- **Endpoint**: `GET /api/category`
- **Response**: List of parent categories with populated `subcategories` array.

### 5.4 Order Creation API
- **Endpoint**: `POST /api/order`
- **Payload**:
  ```json
  {
    "userId": "guest_or_user_id",
    "firstName": "Ali",
    "lastName": "Khan",
    "email": "ali@example.com",
    "phoneNumber": "03001234567",
    "address": "House 12, Street 4, Sector F-8",
    "city": "Islamabad",
    "country": "Pakistan",
    "zipCode": "44000",
    "paymentMood": "Cash",
    "storeId": 1,
    "totalAmount": 3999,
    "finalAmount": 4199,
    "items": [
      {
        "productId": 101,
        "productVariantId": null,
        "quantity": 1,
        "price": 3999
      }
    ]
  }
  ```

### 5.5 Store Application API
- **Endpoint**: `POST /api/storerequest`
- **Payload**: Merchant business credentials (`name`, `contact`, `cnicNumber`, `ntnNumber`, `address`, `email`, `city`, `bankName`, `bacnkAccountNumber`, `bacnkIBANNumber`, `ownerName`).

---

## 6. Merchant Lifecycle & Multi-Vendor Architecture

1. **Merchant Application**: The prospective seller submits a store request via `/createstore`.
2. **Verification & Approval**: BazarExa administrators review business information, CNIC/NTN credentials, and banking setup.
3. **Store Board Provisioning**: Once approved, the store account is activated under a designated `StoreType` tier with product upload limits and promotional allowances.
4. **Catalog & Inventory Control**: The merchant adds products, defines variant matrices (colors, sizes, prices, stock), assigns categories, and uploads high-resolution media.
5. **Multi-Vendor Order Routing**: When a buyer places an order containing items from multiple stores, BazarExa generates distinct order instances partitioned by `storeId` to facilitate independent shipping, tracking, and payout calculation.

---

## 7. SEO, Structured Data & LLM Discovery Standards

- **OpenGraph & Twitter Card Meta Tags**: Configured across static and dynamic product pages with Cloudinary-hosted visual previews.
- **Schema.org Structured Data (JSON-LD)**:
  - `WebSite` with `SearchAction` potentialAction for search indexing.
  - `ItemList` representing top site navigation elements and categories.
  - `Product` and `AggregateRating` schemas on individual product detail pages.
- **Robots Directives**:
  - `Allow: /`
  - `Disallow: /storeboard/`, `/profile/`, `/checkout/`, `/cart/`, `/anonymousorder/`, `/api/`
  - Sitemaps: `https://www.bazarexa.com/sitemap.xml`
  - LLM Indexes: `https://www.bazarexa.com/llms.txt`, `https://www.bazarexa.com/llms-full.txt`

---

## 8. Customer Service & Operational Policies

- **Delivery Timeline**: 2 to 5 business days across major cities (Karachi, Lahore, Islamabad, Rawalpindi, Faisalabad, Multan, Peshawar, Quetta) and 4 to 7 business days for remote locations.
- **Payment Options**: Cash on Delivery (COD) across Pakistan; digital bank transfers and online card processing where enabled.
- **Return & Refund Policy**: 7-day return window for defective, damaged, or mismatched products under standard buyer protection terms.
- **Customer Support**: Inquiries and support tickets handled via official website contact channels and email notifications.