# Punjabi Mandi – New UI Migration & Implementation Plan

> **Status:** PLAN MODE — No implementation changes will be made during this phase.
> **Created:** 2026-10-01

---

## 1. Existing System Analysis

### 1.1 Technology Stack

| Component | Technology |
|---|---|
| Framework | **Laravel 13** (PHP 8.3) |
| Frontend CSS | Bootstrap 5.0.2 + custom `style.css` |
| Frontend JS | jQuery 3.4.1, OwlCarousel2, Toastr, RateYo, ElevateZoom+ |
| Build Tool | Vite |
| Template Engine | Blade (components + layouts) |
| Auth | Dual-guard: `admin` (Admin model) + `customer` (Customer model) |
| Payment | Authorize.Net |
| PDF | barryvdh/laravel-dompdf |
| Social Login | Laravel Socialite (Google) |
| Category Tree | `staudenmeir/laravel-adjacency-list` |
| CSS Framework | Tailwind (configured but mainly Bootstrap is used in frontend) |

### 1.2 Database Models (44 Models)

```mermaid
erDiagram
    Customer ||--o| Cart : has
    Customer ||--o{ Order : places
    Customer ||--o{ Address : has
    Customer ||--o{ WishList : has
    Cart ||--o{ CartItem : contains
    Cart }o--o| Coupon : uses
    Product ||--o{ ProductImage : has
    Product ||--o| ProductInventory : has
    Product ||--o{ ProductVariant : has
    Product ||--o{ ProductCategory : belongsTo
    Product ||--o{ Review : has
    Product }o--o| Brand : belongsTo
    Product }o--o| Tax : has
    Category ||--o{ Category : parent-child
    Category ||--o{ ProductCategory : has
    Order ||--o{ OrderItem : contains
    Order ||--o| OrderPayment : has
    Order ||--o{ Refund : has
```

**Key Models:**
- [Product.php](file:///c:/laragon/www/punjabimandi/app/Models/Product.php) — 38 fillable fields, eager-loads `images`
- [Category.php](file:///c:/laragon/www/punjabimandi/app/Models/Category.php) — recursive tree via `HasRecursiveRelationships`, has `child()`, `descendants()`, polymorphic `image`, `icon`
- [Customer.php](file:///c:/laragon/www/punjabimandi/app/Models/Customer.php) — extends `Authenticatable`, has `cart`, `addresses`, `wishlist`, `orders`
- [Cart.php](file:///c:/laragon/www/punjabimandi/app/Models/Cart.php) — supports session-based (guest) + customer-based carts
- [CartItem.php](file:///c:/laragon/www/punjabimandi/app/Models/CartItem.php) — per-item tax, quantity, pricing
- [WishList.php](file:///c:/laragon/www/punjabimandi/app/Models/WishList.php) — simple customer_id + product_id

### 1.3 Routing Architecture

| Route | Controller | View |
|---|---|---|
| `GET /` | `ShopController@index` | `frontend.pages.index` |
| `GET /{slug}` (catch-all) | `ShopController@productByCategory` | `product-list` OR `product-details` |
| `GET /cart` | `CartController@cartView` | `frontend.pages.cart` |
| `POST /add/cart` | `CartController@store` | JSON response |
| `GET /cart-items` | `CartController@cartItems` | JSON + mini-cart HTML |
| `GET /checkout` | `ShopController@checkout` | `frontend.pages.checkout` |
| `GET /customer/login` | `CustomerController@login` | `frontend.auth.login` |
| `GET /customer/register` | `CustomerController@register` | `frontend.auth.register` |
| `GET /add/{id}/wishlist` | `CheckoutController@addToWishlist` | redirect back |
| `POST /serarch-products` | `ShopController@searchProduct` | JSON + `searched-items` partial |

> [!IMPORTANT]
> The catch-all route `Route::any('{any}', ...)` at [web.php:371](file:///c:/laragon/www/punjabimandi/routes/web.php#L371) handles both category pages AND product detail pages via slug detection. The controller checks if the slug matches a Category first, then falls back to Product lookup.

### 1.4 Existing View Architecture

```
resources/views/
├── frontend/
│   ├── layouts/
│   │   ├── master.blade.php    ← Main HTML skeleton (uses $slot)
│   │   ├── header.blade.php    ← Navigation, search, cart icon
│   │   ├── footer.blade.php    ← Footer with links, newsletter
│   │   └── b_footer.blade.php  ← Before-footer section
│   ├── pages/
│   │   ├── index.blade.php     ← Home page (includes sections)
│   │   ├── product-list.blade.php  ← Category/filter listing
│   │   ├── product-details.blade.php ← Product detail page
│   │   ├── cart.blade.php, checkout.blade.php, etc.
│   │   └── sections/           ← Home page sections (sliders, categories, etc.)
│   ├── customer/               ← Profile, orders, addresses, wishlist
│   └── auth/                   ← Login, register, email verify
├── components/
│   ├── products/
│   │   ├── card.blade.php      ← Reusable product card component
│   │   └── qty.blade.php       ← Quantity +/- input
│   ├── product-filter.blade.php ← Sidebar filters
│   └── partial-category.blade.php ← Category dropdown in nav
└── layouts/
    └── master layout uses <x-app-layout> component
```

### 1.5 Key Business Logic

1. **Special Price Logic**: Products have `special_price`, `special_price_from`, `special_price_to` — date-range sale pricing
2. **Cart System**: Dual-mode (guest via session `cart_id`, customer via `customer_id`) with tax calculation, coupon support
3. **Product Filtering**: URL query params (`sort`, `order`, `brand`, `flavour`, `source`, `form`, `price`, `sale`, `is_new`, `is_best_seller`, `is_featured`)
4. **Search**: AJAX-based search across product name, SKU, URL key, category slug, brand name
5. **Helper Facade**: `Punjabi::settings()`, `Punjabi::topCategories()`, `Punjabi::pages()`, `Punjabi::flyer()`

---

## 2. New UI Design Analysis

### 2.1 Template Origin

The new UI is based on a **PrestaShop theme** (CoderPlace PRS04082). It is a fully static HTML design with:

| File | Size | Description |
|---|---|---|
| [index.html](file:///c:/laragon/www/new_ui/index.html) | 315KB, 5458 lines | Home page |
| [products.html](file:///c:/laragon/www/new_ui/products.html) | 295KB, 4514 lines | Product listing/category |
| [product-detail.html](file:///c:/laragon/www/new_ui/product-detail.html) | 181KB, 3140 lines | Product detail |

### 2.2 New UI Asset Stack

| Asset | Files |
|---|---|
| CSS | `fonts.css`, `bootstrap.css`, 3 theme CSS files (page-specific), `style.css` |
| JS | 3 `bottom-*.js` bundles (page-specific), `main.js`, `products-filter.js`, `shop-common.js` |
| Fonts | Quicksand (Medium, SemiBold, Bold) via local `@font-face` |
| Icons | Material Icons (via entity references) |
| Images | Product images, banners, brand logos in `assets/img/` |

### 2.3 New UI Structural Sections

#### Home Page (`index.html`)
1. **Announcement Bar** — "Up to 20% off" promo strip
2. **Top Nav** — Delivery info, language/currency selectors, sign in, track order, account
3. **Header** — Logo, hamburger menu, category dropdown, search (with category filter), phone number, user icons, wishlist, compare, cart
4. **Horizontal Menu** — Organic, Cookies, Pretzels, Grills/Bites, Juice, Fresh — with mega-menu dropdowns + "Today's Hot Deals" link
5. **Hero Slider** — Large banner carousel
6. **Category Circles** — "Shop by Category" circular image grid
7. **Info Strip** — Delivery, quality, payment icons
8. **Featured Products** — "Popular Products" product card grid
9. **Category Tabs** — "Hot Categories" tabbed product sections
10. **Promotional Banners** — 2-column offer banners
11. **Best Sellers** — "Bestselling Products" carousel
12. **Testimonials** — Customer review slider
13. **Best Seller Brand Logos** — Brand carousel
14. **Dual Offer Banners** — Two promotional cards
15. **Newsletter** — Email subscription section
16. **Footer** — Multi-column: logo/address, products links, company links, trending categories, social icons, copyright

#### Products Page (`products.html`)
1. **Left Sidebar** — Category tree (collapsible), filter-by (Size, Color, Price slider), left banner image
2. **Content Area** — Grid/List toggle, product count, sort dropdown, product grid (4 columns)
3. **Product Card** — Image, sale badge, quick view, wishlist, compare, product name, price (regular + sale), add-to-cart button
4. **Right Sidebar** — "You might also like" products, "16 other products in the same category" grid
5. **Bottom Banners** — Two promotional images
6. **Pagination** — "Showing 1-12 of 22 items" with prev/next

#### Product Detail Page (`product-detail.html`)
1. **Breadcrumbs** — Home > Category > Product
2. **Image Gallery** — Main image + thumbnail strip (vertical), zoom on hover
3. **Product Info** — Name, brand, SKU, condition, color swatches, quantity selector, add-to-cart button, "Guarantee Safe Checkout" badge
4. **Tabs** — Description, Product Details, Shipping, Size Chart
5. **Related Products** — "You might also like" carousel
6. **Same Category Products** — Grid of products from same category
7. **Bottom Banners** — Two promo images

---

## 3. Feature-to-Feature Mapping: New UI ↔ Existing Backend

| New UI Feature | Existing Backend Support | Gap/Action |
|---|---|---|
| Announcement Bar | `Coupon` model | Use existing coupon code description |
| Category Mega Menu | `Category` tree + `PartialCategory` component | Restructure HTML to match new mega-menu layout |
| Search with Category Filter | `ShopController@searchProduct` | Extend search to accept category_id parameter |
| Hero Slider | `Slider` model | Already supported |
| Shop by Category circles | `Category` with images | Already supported via `Category::tree()` |
| Popular/Featured Products | `Product::is_featured` | Already supported |
| Best Sellers | `Product::is_best_seller` | Already supported |
| New Launches | `Product::is_new` | Already supported |
| Product Card (price, sale, add-to-cart) | `Product`, `ProductImage`, `ProductInventory` | Restructure card HTML |
| Sidebar Category Tree | `Category` hierarchy | Already supported |
| Sidebar Filters (Size, Color, Price) | Existing filter component (`product-filter.blade.php`) | Adapt to new faceted filter UI |
| Grid/List Toggle | Existing `?mode=list` support | Already supported |
| Product Detail image gallery | `ProductImage` | Restructure to vertical thumbnails |
| Product tabs (Description, Details, Shipping) | Existing tabs (Description, Benefits, Suggested Use, Disclaimer) | Remap tab labels |
| Quantity selector | Existing `qty.blade.php` component | Restructure HTML |
| Color swatches | `ProductVariant` with `variant` + `variant_value` | Already exists in data model |
| Wishlist (heart icon) | `WishList` model + routes | Already supported |
| Compare | **NOT IN EXISTING SYSTEM** | ⛔ Skip for now (will be added later if needed) |
| Language Selector | Static | ✅ Keep English only — remove other languages |
| Track Order | `CustomerController@orders` | ✅ Link to customer orders page (`customer.orders` route) |
| Newsletter | `Newsletter` model + routes | Already supported |
| Brand Logos | `Brand` model | Already supported |
| Customer Reviews/Testimonials | `Review` model | Already supported |
| "You might also like" | `getProductsByCategory()` | Already supported |
| "Same category products" | `getProductsByCategory()` | Already supported |
| Mini Cart | `CartController@cartItems` | Already supported (returns HTML partial) |

---

## 4. Implementation Strategy

### 4.1 Approach: New View Layer, Same Backend

> [!TIP]
> **Strategy:** Create entirely new Blade view files under a `newui` directory inside `resources/views/frontend/`. The existing views remain untouched as fallback. A configuration flag or route swap will activate the new UI.

**Rationale:**
- Zero risk to existing production system
- Allows side-by-side comparison and testing
- Can be rolled back instantly
- No changes to controllers, models, or business logic needed initially

### 4.2 Asset Migration Strategy

1. Copy `new_ui/assets/` → `public/newui/assets/`
2. Each new Blade view references assets from `{{ asset('newui/assets/...') }}`
3. Consolidate the 3 theme CSS variants into a unified system
4. Keep `style.css` as the custom override layer

---

## 5. Phased Implementation Plan

### Phase 1: Foundation — New Master Layout + Assets
**Scope:** New layout skeleton, CSS/JS assets, header, footer, announcement bar

| # | Task | Files to Create/Modify |
|---|---|---|
| 1.1 | Copy `new_ui/assets/` → `public/newui/assets/` | File copy |
| 1.2 | Create new master layout | `views/frontend/newui/layouts/master.blade.php` |
| 1.3 | Create new header component | `views/frontend/newui/layouts/header.blade.php` |
| 1.4 | Create new footer component | `views/frontend/newui/layouts/footer.blade.php` |
| 1.5 | Create announcement bar partial | `views/frontend/newui/layouts/announcement-bar.blade.php` |
| 1.6 | Create horizontal menu partial | `views/frontend/newui/layouts/horizontal-menu.blade.php` |
| 1.7 | Create new `AppLayout` component variant | `app/View/Components/NewUiLayout.php` |
| 1.8 | Keep English only, show "$ CAD" as sole currency | Strip other languages & currencies from header |
| 1.9 | Wire auth state (login/register/profile) in new header | Use `Auth::guard('customer')` |
| 1.10 | Wire search bar with category dropdown | Extend `searchProduct()` |
| 1.11 | Wire mini-cart in header | Reuse existing AJAX endpoint |
| 1.12 | Wire wishlist counter in header | New helper or AJAX |

**Verification:** New layout renders with header, footer, proper CSS/JS loading, auth state reflected.

---

### Phase 2: Home Page
**Scope:** All home page sections with dynamic data

| # | Task | Data Source |
|---|---|---|
| 2.1 | Hero Slider section | `Slider::all()` |
| 2.2 | "Shop by Category" circles | `Category::tree()->with('image')->where('parent_id', 1)` |
| 2.3 | Info strip (delivery/quality/payment) | Static or `HomeSetting` |
| 2.4 | "Popular Products" section | `Product::where('is_featured', true)` |
| 2.5 | "Hot Categories" tabbed section | Categories with product sub-queries |
| 2.6 | Promotional banners | `Banner::where('type', ...)` |
| 2.7 | "Bestselling Products" section | `Product::where('is_best_seller', true)` |
| 2.8 | Customer testimonials/reviews | `Review::where('status', true)` or new testimonial data |
| 2.9 | Brand logos carousel | `Brand::where('status', 1)` |
| 2.10 | Dual offer banners | `Banner::where('type', 2)` |
| 2.11 | Newsletter subscription | Existing `new.subscription` route |
| 2.12 | Create new product card component | `views/components/newui/product-card.blade.php` |

**Files to create:**
- `views/frontend/newui/pages/index.blade.php`
- `views/frontend/newui/pages/sections/slider.blade.php`
- `views/frontend/newui/pages/sections/categories.blade.php`
- `views/frontend/newui/pages/sections/popular-products.blade.php`
- `views/frontend/newui/pages/sections/hot-categories.blade.php`
- `views/frontend/newui/pages/sections/bestsellers.blade.php`
- `views/frontend/newui/pages/sections/testimonials.blade.php`
- `views/frontend/newui/pages/sections/brands.blade.php`
- `views/frontend/newui/pages/sections/newsletter.blade.php`
- `views/frontend/newui/pages/sections/banners.blade.php`
- `views/components/newui/product-card.blade.php`

**Verification:** Home page fully renders with live data from DB.

---

### Phase 3: Product Listing / Category Page
**Scope:** Category page with sidebar, filters, product grid, pagination

| # | Task | Data Source |
|---|---|---|
| 3.1 | Left sidebar — category tree | `Category` hierarchy with `child()` |
| 3.2 | Left sidebar — filter by (price range, brand) | Existing filter params |
| 3.3 | Product grid (4-column responsive) | `Product::paginate()` |
| 3.4 | Product card with sale badge, add-to-cart, wishlist | Reuse `newui/product-card` component |
| 3.5 | Grid/List toggle | `?mode=list` query param |
| 3.6 | Sort dropdown (name, price, newest) | `?sort=...&order=...` |
| 3.7 | Pagination | Laravel built-in + custom styled |
| 3.8 | "You might also like" section | Related products query |
| 3.9 | "Same category products" section | Products from same category |
| 3.10 | Bottom promotional banners | `Banner` model |
| 3.11 | Breadcrumbs | Category ancestors chain |
| 3.12 | Left promotional banner image | `Banner` or static |

**Files to create:**
- `views/frontend/newui/pages/product-list.blade.php`
- `views/components/newui/product-filter.blade.php`
- `views/components/newui/category-sidebar.blade.php`

**Verification:** Category page renders, filtering works, pagination works, add-to-cart works.

---

### Phase 4: Product Detail Page
**Scope:** Full product detail with gallery, tabs, related products

| # | Task | Data Source |
|---|---|---|
| 4.1 | Image gallery (main + vertical thumbnails) | `$product->images` |
| 4.2 | Product info (name, brand, SKU, weight) | `Product` model fields |
| 4.3 | Price display (regular + sale) | Special price logic |
| 4.4 | Color/variant swatches | `$product->variants` |
| 4.5 | Quantity selector + Add to Cart | Existing cart JS |
| 4.6 | Wishlist toggle | Existing wishlist route |
| 4.7 | "Guarantee Safe Checkout" badge | Static HTML |
| 4.8 | Tabs: Description | `$product->description` |
| 4.9 | Tabs: Product Details | `$product->ingredients` or custom |
| 4.10 | Tabs: Shipping | Static or from `HomeSetting` |
| 4.11 | Tabs: Size Chart | Static or new field |
| 4.12 | Review form (for authenticated customers) | Existing review system |
| 4.13 | "You might also like" carousel | `$relatedProducts` |
| 4.14 | "Same category products" grid | Same category query |
| 4.15 | Bottom promotional banners | `Banner` model |
| 4.16 | Breadcrumbs | Category ancestors |
| 4.17 | Image zoom on hover | New UI's built-in JS or ElevateZoom |

**Files to create:**
- `views/frontend/newui/pages/product-details.blade.php`

**Verification:** Product detail renders fully, image gallery works, tabs work, add-to-cart works, review form works.

---

### Phase 5: Controller Routing & Integration
**Scope:** Wire new views to existing controllers

| # | Task | Details |
|---|---|---|
| 5.1 | Add `NEW_UI=true` in `.env` file + `config('app.new_ui')` | Toggle between old/new views |
| 5.2 | Update `ShopController@index` | Return new view when flag is on |
| 5.3 | Update `ShopController@productByCategory` | Return new listing/detail view |
| 5.4 | Update `CartController@cartItems` | Return new mini-cart partial |
| 5.5 | Ensure all AJAX endpoints remain compatible | Cart add/update/delete, search, coupon |
| 5.6 | Update `searchProduct` to support category filter | Add `category_id` parameter |
| 5.7 | Wire the new `cart.js` equivalent | Port cart add/update/remove JS |

**No new files** — modify return statements in existing controllers only.

**Verification:** Complete user flow works: browse → search → filter → detail → add-to-cart → checkout.

---

### Phase 6: Supporting Pages
**Scope:** Cart, checkout, auth, customer account pages in new UI style

| # | Task |
|---|---|
| 6.1 | Cart page in new UI style |
| 6.2 | Checkout page in new UI style |
| 6.3 | Login page in new UI style |
| 6.4 | Register page in new UI style |
| 6.5 | Customer profile page |
| 6.6 | Customer orders page |
| 6.7 | Customer addresses page |
| 6.8 | Wishlist page |
| 6.9 | Contact us page |
| 6.10 | Static CMS pages |
| 6.11 | Thank you / order success page |

> [!NOTE]
> Phase 6 creates new views for pages that don't have a direct new_ui HTML template yet. These should follow the new UI's design system (fonts, colors, spacing) for consistency.

---

### Phase 7: Polish & Testing
**Scope:** Responsive testing, JS integration, performance

| # | Task |
|---|---|
| 7.1 | Mobile responsive testing (all breakpoints) |
| 7.2 | Cart functionality end-to-end (guest + logged in) |
| 7.3 | Wishlist functionality |
| 7.4 | Coupon apply/remove |
| 7.5 | Search functionality |
| 7.6 | Product filtering (price, brand, category) |
| 7.7 | Image zoom on product detail |
| 7.8 | Newsletter subscription |
| 7.9 | Google social login flow |
| 7.10 | Checkout + payment flow |
| 7.11 | SEO: meta tags, breadcrumbs, canonical URLs |
| 7.12 | Performance: asset minification, lazy loading |
| 7.13 | Remove old UI assets/views (after final sign-off) |

---

## 6. Features to EXCLUDE from New UI

These features exist in the new UI HTML but don't apply to Punjabi Mandi:

| Feature | Decision |
|---|---|
| Other languages (fr/es/it/de/ar) | Remove — keep English only |
| Other currencies (EUR/SAR/USD) | Remove — show "$ CAD" only |
| Compare products | Skip for now — will be added later if needed |
| Store Locator | Not in scope |
| Size/Color facet filters | Products don't have size attribute; adapt to existing filters (brand, flavour, source, form) |

---

## 7. Risk Assessment

| Risk | Severity | Mitigation |
|---|---|---|
| New UI CSS conflicts with existing styles | Medium | Separate asset directories, no shared CSS |
| Cart JS breaks with new HTML structure | High | Port cart.js with new selectors, thorough testing |
| OwlCarousel replaced by different carousel | Medium | Use new UI's built-in Swiper/carousel JS |
| Category tree HTML structure differs significantly | Medium | Create new `category-sidebar` Blade component |
| PrestaShop-specific JS (bootstrap) conflicts | Medium | Use the new UI's bootstrap bundle, not the old one |
| SEO disruption (URL changes) | Low | No URL changes — same routes |
| Mobile layout breaks | Medium | Test all breakpoints early in Phase 1 |

---

## 8. File Count Estimate

| Category | Estimated Files |
|---|---|
| New Blade views (layouts) | ~5 |
| New Blade views (pages) | ~3 primary + ~10 sections |
| New Blade components | ~4 |
| Asset copies | 1 directory (css, js, fonts, img) |
| Controller modifications | ~3 files (minimal changes) |
| Config changes | 1 (.env / config) |
| **Total new files** | **~25-30** |
| **Total modified existing files** | **~3-5** |

---

## 9. Execution Order Summary

```mermaid
gantt
    title New UI Migration Phases
    dateFormat  YYYY-MM-DD
    section Phase 1
    Foundation (Layout + Assets)     :p1, 2026-10-02, 3d
    section Phase 2
    Home Page                        :p2, after p1, 3d
    section Phase 3
    Product Listing Page             :p3, after p2, 3d
    section Phase 4
    Product Detail Page              :p4, after p3, 2d
    section Phase 5
    Controller Routing               :p5, after p4, 2d
    section Phase 6
    Supporting Pages                 :p6, after p5, 4d
    section Phase 7
    Polish & Testing                 :p7, after p6, 3d
```

---

## 10. Ready for Implementation

> [!IMPORTANT]
> **This plan is ready for review.** Once approved, implementation will proceed phase-by-phase following the **PLAN → IMPLEMENT → TEST → VERIFY** cycle. Each phase will be completed and verified before moving to the next.

**To begin implementation, confirm:**
1. ✅ Plan reviewed and approved
2. ✅ Which phase to start with (recommended: Phase 1)
3. ✅ Any features to add/remove from scope
4. ✅ Any design deviations from the static HTML to note