# Customer Storefront & Repair Portal Architectural Implementation Plan **Reference UI**: `https://demo.templatemonster.com/demo/501755.html` (`https://wordpressthemes.live/WCM9/WCM210_techshop/default/`) **Target Codebase Location**: `/run/media/sonu/FAM/SERVER/IfixKartEcommerce/Ecommerce Page` **Documentation Location**: `/run/media/sonu/FAM/SERVER/IfixKartEcommerce/Documentation` --- ## Architecture Decision Record (ADR) - **ADR-1**: Customer Storefront & Repair Portal is built as a dedicated Next.js application inside `/run/media/sonu/FAM/SERVER/IfixKartEcommerce/Ecommerce Page`. - **ADR-2**: `Admin Ecommerce` remains the primary Admin ERP/CRM management application. - **ADR-3**: `Ecommerce Page` shares the identical FastAPI backend (`http://127.0.0.1:8000`), JWT authentication, design system tokens, Tailwind CSS styling, and data models. - **ADR-4**: Zero duplicate business logic or hardcoded catalog data is permitted. Everything is dynamically fetched from backend APIs. - **ADR-5**: All newly created modules must remain modular, decoupled, and reusable across future portals. --- ## The Golden Rule ⭐⭐⭐⭐⭐ > [!CAUTION] > **The reference website defines the visual experience.** > **The existing iFixKart platform defines the architecture.** > **Whenever there is a conflict: Architecture always wins.** > > Never compromise the existing platform to imitate the template. Build the TechShop experience using iFixKart architecture—not the other way around. --- ## Portal Domain Architecture The Customer Portal is strictly separated into two distinct sub-domains: ``` Customer Portal (Ecommerce Page) ├── Storefront Domain │ ├── Home Page (Dynamic Hero Banners, Dynamic Categories, Featured Showcase, Deals, Brands) │ ├── Product Catalog & Detail (Live Filters, Multi-variant Picker, Stock Ledger, Specs) │ ├── Shopping Cart & Slide-over Cart Drawer │ ├── Multi-step Checkout │ └── Customer Account (Orders, Tracking, Address Book, Returns) │ └── Repair Portal Domain ├── Device Lookup & Selection (Brand -> Series -> Model) ├── Repair Service Booking (Screen, Battery, Camera, Water Damage, Logic Board) ├── Real-time Repair Status Tracker ├── Service History & Warranty Verification └── Technician Claim / Booking Submission ``` --- ## Reference Analysis Policy ⭐⭐⭐⭐⭐ Before implementing any page or component, the system strictly enforces the following 9-step analysis workflow: 1. **Analyze Reference Website**: Inspect visual layout, typography, colors, shadows, and element positioning on `https://demo.templatemonster.com/demo/501755.html` (`https://wordpressthemes.live/WCM9/WCM210_techshop/default/`). 2. **Identify UI Components**: Catalog all visual cards, sliders, drawers, navigation menus, modals, and badges. 3. **Identify Interactions**: Document click events, tab switching, hover overlays, slide-overs, and quick view toggles. 4. **Identify Animations**: Map micro-interactions, Framer Motion slide transitions, image flip effects, and spinner states. 5. **Identify Spacing & Layout Rules**: Note grid columns, padding bounds, container widths, and mobile breakpoints. 6. **Compare with Existing iFixKart Implementation**: Audit existing primitives, hooks, stores, and API clients. 7. **Reuse Existing Components**: Use existing Shadcn UI primitives, buttons, inputs, dialogs, and utility classes first. 8. **Extend Existing Components**: Add required variants or props to existing components if necessary. 9. **Create New Components Only When Necessary**: Build new store components under `components/store/` only after verifying no existing component fulfills the requirement. --- ## AI Implementation Rules & Constraints > [!IMPORTANT] > When generating or implementing code, the AI must strictly adhere to: > - **Never overwrite existing functionality** or break current admin ERP/CRM features. > - **Never modify unrelated files** outside the explicitly declared scope. > - **Never remove existing business logic** or comment out broken tests/assertions. > - **Always explain why a file is modified** before performing any edit. > - **Prefer extending existing code** over creating duplicate new helper modules. > - **Stop and request clarification** if the existing architecture conflicts with the requested implementation. --- ## Component Inventory | Category | Component Name | Status | Source / Asset Path | | :--- | :--- | :--- | :--- | | **Existing UI Primitives** | Button, Input, Dialog, Card, Data Table | **REUSE** | Tailwind design tokens in `app/globals.css` | | **Layout System** | App Container, Grid System, Flex Utilities | **REUSE** | Tailwind CSS layout engine | | **State Management** | Storefront Cart & Wishlist Store | **CREATE** | `store/cartStore.ts` | | **API Client** | `apiFetch` HTTP Client with Auth Injection | **REUSE** | `services/api/client.ts` | | **API Endpoint Registry** | API Endpoints Constants (Versioned `/api/v1/...`) | **EXTEND** | `services/api/config.ts` | | **Catalog Services** | Brands, Categories, Parts, Devices, Products APIs | **REUSE** | `services/api/catalogService.ts` | | **Icons System** | Lucide React Icons | **REUSE** | `lucide-react` | | **Store Header & Search** | `StoreHeader`, `LiveSearch` (Debounced Autocomplete) | **CREATE** | `components/store/StoreHeader.tsx`, `LiveSearch.tsx` | | **Dynamic Mega Menu** | `MegaMenu` (Database Categories Tree) | **CREATE** | `components/store/MegaMenu.tsx` | | **Hero Slider** | `HeroBanner` (FastAPI Dynamic Banners) | **CREATE** | `components/store/HeroBanner.tsx` | | **Product Card & Grid** | `ProductCard`, `ProductGrid` (Native Schema & Stock) | **CREATE** | `components/store/ProductCard.tsx`, `ProductGrid.tsx` | | **Cart Drawer** | `CartDrawer` (Slide-over Cart Preview) | **CREATE** | `components/store/CartDrawer.tsx` | | **Quick View** | `QuickViewModal` (Product Detail Preview) | **CREATE** | `components/store/QuickViewModal.tsx` | | **Repair Booking** | `RepairBookingWizard` (Device Repair Flow) | **CREATE** | `components/store/RepairBookingWizard.tsx` | --- ## Design Token Policy All styling strictly enforces our existing design system tokens defined in `app/globals.css`: - **Primary Accent**: `var(--primary)` (`#e4382f`) - **Foreground**: `var(--foreground)` (`#1b2559`) - **Background**: `var(--background)` (`#f4f7fe`) - **Card & Surfaces**: `var(--card)` (`#ffffff`) - **Border Radius**: `--radius-sm` (6px), `--radius-md` (8px), `--radius-lg` (12px) --- ## API Dependency Mapping & Versioning (`/api/v1/...`) | Module / Feature | Versioned API Endpoint | Service Method Wrapper | | :--- | :--- | :--- | | **Header Live Search** | `GET /api/v1/storefront/live-search?q=...` | `storefrontService.getLiveSearch(query)` | | **Mega Menu Bar** | `GET /api/v1/catalog/categories/all`, `GET /api/v1/catalog/device-models/all` | `catalogService.getCategories()`, `catalogService.getDeviceModels()` | | **Hero Banners** | `GET /api/v1/storefront/banners` | `storefrontService.getBanners()` | | **Category Grid** | `GET /api/v1/catalog/categories/all` | `catalogService.getCategories()` | | **Product Showcase** | `GET /api/v1/catalog/products/all` | `catalogService.getProducts()` | | **Brands Carousel** | `GET /api/v1/catalog/brands/all` | `catalogService.getBrands()` | | **Repair Portal Booking** | `GET /api/v1/catalog/service-types/all`, `GET /api/v1/catalog/repair-services/all` | `catalogService.getServiceTypes()`, `catalogService.getRepairServices()` | | **Product Detail** | `GET /api/v1/catalog/products/all` | `catalogService.getProducts()` | | **Stock & Cart Check** | `GET /api/v1/catalog/parts/all`, `GET /api/v1/catalog/stock-movements/history` | `catalogService.getParts()`, `catalogService.getStockHistory()` | --- ## Security & Observability Requirements - **Input Validation**: Sanitize and validate all inputs with Zod. - **Route Protection**: Customer profile, checkout, and orders routes require valid JWT tokens. - **RBAC Isolation**: Admin management endpoints remain strictly isolated from customer routes. - **Logging & Monitoring**: Log API failures, latency warnings (> 1500ms), and checkout errors. --- ## Feature Completion Workflow & Definition of Complete ``` Implement -> Type Check -> Lint -> Manual Test -> Responsive Test -> Accessibility Test -> Performance Check -> Regression Test -> Merge ``` A feature is complete when it is: 1. Pixel-accurate to reference 2. Responsive (Desktop, Laptop, Tablet, Mobile) 3. Accessible (ARIA, focus outlines, keyboard nav) 4. Uses versioned APIs (`/api/v1/...`) without hardcoded data 5. 0 TypeScript errors, 0 linter errors, 0 console errors