- Backend: FastAPI app with all models, services, schemas, routes - Admin Panel: Next.js dashboard with all modules (CRM, POS, repairs, warranties, billing, notifications, etc.) - Ecommerce: storefront (submodule) + product catalog - AI Agents: .agents/ skill library for Antigravity IDE - Docs: architecture, billing, notification gateway markdown - Submodules: Backend/OpenWA, Ecommerce/File 2/storefront
150 lines
8.6 KiB
Markdown
150 lines
8.6 KiB
Markdown
# 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<T>` 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
|