- 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
8.6 KiB
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 Ecommerceremains the primary Admin ERP/CRM management application. - ADR-3:
Ecommerce Pageshares 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:
- 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/). - Identify UI Components: Catalog all visual cards, sliders, drawers, navigation menus, modals, and badges.
- Identify Interactions: Document click events, tab switching, hover overlays, slide-overs, and quick view toggles.
- Identify Animations: Map micro-interactions, Framer Motion slide transitions, image flip effects, and spinner states.
- Identify Spacing & Layout Rules: Note grid columns, padding bounds, container widths, and mobile breakpoints.
- Compare with Existing iFixKart Implementation: Audit existing primitives, hooks, stores, and API clients.
- Reuse Existing Components: Use existing Shadcn UI primitives, buttons, inputs, dialogs, and utility classes first.
- Extend Existing Components: Add required variants or props to existing components if necessary.
- 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:
- Pixel-accurate to reference
- Responsive (Desktop, Laptop, Tablet, Mobile)
- Accessible (ARIA, focus outlines, keyboard nav)
- Uses versioned APIs (
/api/v1/...) without hardcoded data - 0 TypeScript errors, 0 linter errors, 0 console errors