ifixkart-admin/Documentation/Storefront_Architecture_Plan.md
Adithiyan bbd3a3e959 feat: initial commit — full platform snapshot
- 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
2026-10-13 12:59:47 +05:30

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 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