# iFixKart Platform: Master Business Requirements & Architectural Implementation Plan This master document consolidates the complete business requirements, functional specifications, operational plans, and architectural guidelines for the **iFixKart Unified Commerce, Service & Operations Platform**. --- ## Document Control & Overview | Attribute | Details | | :--- | :--- | | **Project Name** | iFixKart — Unified Commerce, Service & Operations Platform | | **Business Scope** | Electronics retail (parts, mobiles, tablets, laptops) and device repair service | | **Geographic Target** | Chennai, Tamil Nadu, India | | **Document Version** | 1.0 (Master Integration) | | **Prepared By** | Trionix Solution | | **Prepared For** | iFixKart Stakeholders, Development Team, Investors | | **Classification** | Confidential — Internal & Client Use | ### Version History * **v1.0 (26 Jun 2026)**: Initial consolidation of E-commerce storefront plans, OMS, CRM, invoicing, billing, payments, shipping, inventory, and reliability/operational modules. ### Purpose of This Document This document serves as the single source of truth for: 1. **The Development Team**: A build specification detailing data models, API mappings, routing, components, and constraints. 2. **The Client (iFixKart)**: A plain-language explanation of functional modules, workflows, and business value. 3. **Investors / Partners**: A clear business case showing market advantages, revenue growth mechanisms, and operational scalability. --- ## 1. Executive Summary iFixKart is a Chennai-based electronics retail and repair services business. Historically, product sales (e-commerce parts and retail) and repair bookings have operated as fragmented, loosely-connected workflows. This platform replaces fragmentation with a unified system consisting of **two front-ends**, **three backend components**, and **two databases**, sharing order, inventory, customer, and financial data so that sales and service operations are run in sync. ### Key Outcomes This Platform Is Designed to Deliver * **Unified Operations**: A single dashboard running sales, service, inventory, CRM, billing, and marketing. * **Higher Conversion**: A structured CRM pipeline and internal alerts to prevent lead drop-off. * **Lower Revenue Leakage**: Automated payment reconciliation, inventory locking, and audit logging. * **Scalable Infrastructure**: A modular monolith architecture designed to handle a 10x transaction volume without proportional headcount growth. --- ## 2. Business Context & Problem Statement Electronics retail and repair businesses in India typically suffer from administrative overhead, untracked inventory, and missed customer follow-ups due to fragmented workflows. ### Problems & Platform Solutions | Problem (Current State) | Root Cause | Platform Solution | | :--- | :--- | :--- | | **Separated tracking** | No shared backend between retail and service | Unified Order Management System (OMS) with a shared event bus and inventory state | | **Stock overselling** | No real-time, locked inventory state during checkout | Inventory state machine with distributed locking (`Available` $\rightarrow$ `Soft-Locked` $\rightarrow$ `Hard-Deducted`) | | **Lost marketing leads** | No structured CRM; follow-up is memory-dependent | CRM pipeline (`Lead` $\rightarrow$ `Proposal` $\rightarrow$ `Won/Lost`) with Bailey alerts | | **Outstanding balance leaks** | Manual invoice tracking after partial service advance | Automated invoice engine issuing 30% advance & final completion invoices | | **Manual reconciliation** | No automated matching process for Razorpay payouts | Automated daily reconciliation jobs flagging transaction discrepancies | | **Lack of accountability** | No audit trail or role-based permissions | Role-Based Access Control (RBAC) + audit logs on all sensitive actions | | **Warranties untracked** | Warranty notes written as unstructured free-text | Structured Warranty Management tied to device IMEI/serial | --- ## 3. High-Level Architecture Overview The system establishes a clean separation between public customer commerce and internal business management, communicating through structured API data flows. ```mermaid graph TD %% Frontends subgraph Frontends ["Front-End Layer (Next.js)"] SF[Customer Storefront & Repair Portal] AB[Admin & Management Board] end %% Backends subgraph Backends ["Backend Layer (FastAPI)"] EB[E-commerce Backend API] A_API[Admin Board Backend API] Bailey[Bailey Internal Notification App] end %% Databases subgraph Databases ["Database Layer (MySQL)"] EDB[(E-commerce Database)] ADB[(Admin Board Database)] end %% Integrations subgraph Integrations ["Third-Party Integrations"] RP[Razorpay Gateway] SR[ShippingRocket] META[Meta Graph API] end %% Connections SF -->|APIs /v1/| EB AB -->|APIs /v1/| A_API EB --> EDB A_API --> ADB EB <==>|Data Sync Flows| A_API EB -.->|Triggers Alerts| Bailey A_API -.->|Triggers Alerts| Bailey EB --> RP A_API --> SR AB --> META classDef main fill:#f4f7fe,stroke:#1b2559,stroke-width:2px; classDef db fill:#e2e8f0,stroke:#475569,stroke-width:2px; classDef ext fill:#fef3c7,stroke:#d97706,stroke-width:1px; class SF,AB,EB,A_API,Bailey main; class EDB,ADB db; class RP,SR,META ext; ``` ### Components List 1. **Customer Storefront (Next.js)**: Public portal for buying parts, laptops, mobiles, and booking repairs. 2. **Admin Board (Next.js)**: Internal dashboard used by staff to manage orders, inventory, CRM, billing, and reports. 3. **E-commerce Backend (FastAPI / MySQL)**: Services storefront traffic, checkout, slot booking, and payments. 4. **Admin Backend (FastAPI / MySQL)**: Services CRM, inventory ledger, billing, reporting, and RBAC. 5. **Bailey**: A private internal app sending WhatsApp notifications to the team for operational follow-ups. --- ## 4. Architectural Rules & Constraints > [!IMPORTANT] > **The Golden Rule:** > **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 architecture to imitate the template. Build the TechShop experience using iFixKart architecture—not the other way around.* ### AI Implementation Rules & Constraints * **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 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. --- ## 5. Portal Domain Architecture The customer storefront app (`Ecommerce Page`) is divided into two distinct 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 (9-Step Workflow) Before implementing any page or component, follow this workflow: 1. **Analyze Reference Website**: Inspect visual layout, typography, colors, shadows on `https://demo.templatemonster.com/demo/501755.html`. 2. **Identify UI Components**: Catalog all 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 flips, 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. --- ## 6. Design Token Policy All styling must strictly enforce the design system tokens defined in `app/globals.css`: * **Primary Accent**: `var(--primary)` (`#e4382f`) * **Foreground Text**: `var(--foreground)` (`#1b2559`) * **Background**: `var(--background)` (`#f4f7fe`) * **Card & Surface**: `var(--card)` (`#ffffff`) * **Borders & System Borders**: `var(--border)` * **Border Radius**: `--radius-sm` (6px), `--radius-md` (8px), `--radius-lg` (12px) --- ## 7. Component Inventory & Status | Category | Component Name | Action / 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 | **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` | --- ## 8. API Dependency Mapping (`/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 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()` | --- ## 9. Functional Modules Detail ### 9.1 E-Commerce Sales & Service (Storefront) * **Ecommerce Sales**: Retails device parts, phones, tablets, and laptops. Features dynamic search, compatibility filtering (essential for repair parts), and stock checking. * **Ecommerce Service**: Custom interface for picking a device type, selecting an issue, seeing a price estimate, and booking a repair. ### 9.2 Order Management System (OMS) Manages the lifecycle of retail orders and service bookings using the following states: 1. `New Order`: Placed, awaiting payment. 2. `Paid`: Confirmed via Razorpay. 3. `Processing`: Picking stock or assigning service technician. 4. `Shipped`: Handed over to ShippingRocket. 5. `Delivered`: Received by customer. 6. `Cancelled`: Order voided, refund triggered. > [!NOTE] > Webhooks utilize unique idempotency keys to prevent duplicate charges or double shipments on retried payloads. ### 9.3 Inventory Management System * Tracks catalog items and handles availability status: `Available`, `Soft-Locked` (item currently in checkout), `Hard-Deducted` (payment finalized), `Unavailable` (out of stock), and `Archived` (hidden from storefront but preserved in historical logs). * Distributed locking prevents race conditions on low-stock items. ### 9.4 Slot Booking System for Service * Integrates calendar slot availability based on technician work calendars. * Requires a **30% advance payment** via Razorpay to lock the booking. * Triggers automated customer-facing booking confirmations. ### 9.5 Client Resource Management (CRM) * Consolidates storefront shoppers, walk-in clients, and Meta social ads inquiries into a single profile database. * Tracks sales pipeline stage: `Lead` $\rightarrow$ `Proposal` $\rightarrow$ `Won / Lost` $\rightarrow$ `Active Customer`. * Escalates stalled leads (leads sitting in `Proposal` stage > 3 days) to sales managers. ### 9.6 Invoicing & Billing Systems * **Online Invoices**: Immutable, GST-compliant invoices generated on checkout/service completion. * **Walk-In Billing (POS)**: POS terminal inside the store that syncs directly with the CRM. Features an offline mode that queues transactions during internet outages. ### 9.7 Payment Management (Razorpay) * Processes full storefront payments, 30% service booking advances, outstanding balance payments, and refunds. * Utilizes daily reconciliation checks to detect mismatches between Razorpay settlements and internal ledgers. ### 9.8 Service History & Warranties * Tracks device repair histories keyed by IMEI/Serial Number. * Stores active warranty durations, covered components, and handles claims with automated verification. --- ## 10. Automation & Reliability Modules ### 10.1 Role-Based Access Control (RBAC) & Auditing Restricts view and mutation access to endpoints based on defined organization roles: * **Super Admin**: Complete control (can configure roles). * **Admin/Manager**: Full operations; can approve refunds above set limits. * **Sales Staff**: Direct order fulfillment, billing, and CRM; cannot modify catalog prices. * **Technician**: Access to assigned repairs and parts inventories only. * **Finance**: Ledger, invoicing, and refund tools; no catalog write permissions. * **Marketing**: Social media, SEO tools, and CRM pipelines. Every sensitive mutation (price overrides, custom discounts, database edits, and role changes) writes to an immutable **Audit Log** indicating user ID, timestamp, target record, and before/after values. ### 10.2 Returns / RMA Workflow Differentiates storefront returns from standard cancellations: 1. Customer requests Return Merchandise Authorization (RMA) with a reason. 2. In-store / shipping receiving inspection logs the return. 3. Item is routed to `Restocked`, `Unavailable (Damaged)`, or `Written Off`. 4. Invoice engine outputs a GST credit note linking back to the original invoice. ### 10.3 Bailey (Internal Notification Engine) * Uses a private, one-way system to push priority notifications from the platform to the internal team's WhatsApp group. * Alerts staff to new orders, payment events, low stock, and stalled slot bookings. * *Note: Does not utilize the customer-facing WhatsApp Business API, which is reserved for Phase 4.* ### 10.4 Automated Payment Reconciliation Engine A daily cron task that extracts Razorpay payout settlements and cross-matches them with local database transactions. Discrepancies are flagged and emailed to the finance team, closing potential leaks. ### 10.5 Abandoned Cart & Booking Recovery * Identifies customers who added items to their cart or selected a service slot but did not finalize the payment step. * Notifies sales staff internally via Bailey to trigger direct customer follow-ups. ### 10.6 Reliability & Infrastructure Layer * **Dead Letter Queues (DLQ)**: Captures events that failed to process (e.g., inventory deduction errors after checkout) for admin analysis. * **Circuit Breakers**: Wraps external integrations (Razorpay, ShippingRocket) so that slow API responses degrade gracefully without freezing customer storefront sessions. * **Automatic Backups**: Nightly encrypted MySQL database backups with weekly validation tests. --- ## 11. Technology Stack | Layer | Technology | Specification / Notes | | :--- | :--- | :--- | | **Frontend** | Next.js | Used for both storefront and admin dashboards | | **Backend** | Python (FastAPI) | Domain-organized modular structure | | **Database** | MySQL | Two separate schemas (Storefront & Admin) | | **Caching & Locks** | Redis | Session state, distributed lock implementation | | **Payment Gateway** | Razorpay | Standard checkout, partial payment APIs | | **Logistics / Shipping** | ShippingRocket | Automated labeling and tracking sync | | **Internal Notifications**| Bailey | Dedicated internal app to team WhatsApp | | **Integrations** | Meta Graph API, X API | Social postings and inbound lead sync | | **Analytics & SEO** | GA4, Schema.org | Funnel analysis and product microdata | --- ## 12. Non-Functional Requirements ### 12.1 Availability & Performance * Target **99.5%+ uptime** for public-facing storefront services. * Page loading times below **2.5 seconds** on target mobile networks (India). * Core API checkouts and endpoint responses under **500ms** at the 95th percentile. ### 12.2 Security & Compliance * Minimization of PCI-DSS scope: Card handling is delegated entirely to Razorpay checkouts. * Encryption of passwords via Argon2/bcrypt; database secrets stored in HashiCorp Vault or environment vars. * Compliance with **India's Digital Personal Data Protection (DPDP) Act** (explicit consent toggles, data retention policies, and user request deletion mechanisms). --- ## 13. How the Platform Drives Sales ``` [Discovery (SEO/AEO & GMC)] │ ▼ [Lead Capture (CRM Pipeline & Ads Link)] │ ▼ [Consideration (Real-Time Stock & Estimates)] │ ▼ [Conversion (Partial Payment & Lockings)] ◄─── [Abandonment Recovery (Bailey Alerts)] │ ▼ [Fulfillment (ShippingRocket & Calendar Assign)] │ ▼ [Retention (Warranty Expiry & Loyalty Programs)] ``` ### The 5 Revenue Improvement Mechanisms 1. **No Lost Leads**: The Meta Ads and chat sync feeds directly into the CRM pipeline. Stalled bookings are flagged for staff follow-up via Bailey. 2. **Abandoned Transaction Recovery**: Carts and incomplete service requests are tracked. Bailey notifies sales reps to contact customers who abandoned, capturing ready-to-buy customers. 3. **Reduced Service Friction**: Requiring only a 30% booking deposit lowers payment friction and boosts conversion. 4. **Repeat Customer Activation**: Tracks warranty timelines and IMEI histories to prompt customers with relevant upgrade offers and loyalty points. 5. **Organic Traffic Acquisition**: Google Merchant Center and AEO schema markup capture search intents like *"laptop repair near Chennai"* organically. --- ## 14. Risks & Mitigations | Risk | Impact | Mitigation Strategy | | :--- | :--- | :--- | | **Scope Creep** | Launch delay of primary services | Implement strict phased rollout (Section 15) | | **Integration Breakages** | Disruption to checkout or shipping | Use adapter patterns to isolate third-party changes | | **Team Onboarding Friction** | Manual errors, administrative bypass | Conduct role-specific training using the unified dashboard | | **DPDP Compliance Audits** | Fines or legal challenges | Build data deletion and consent workflows directly into CRM v1 | --- ## 15. Implementation Roadmap A phased rollout isolates dependencies and ensures the core checkout and service booking logic are verified before scaling. ```mermaid gantt title iFixKart Phased Implementation Roadmap dateFormat YYYY-MM-DD section Phase 1: Foundation Next.js Storefront & Admin :active, p1_1, 2026-07-01, 30d OMS & Basic Invoices :active, p1_2, after p1_1, 20d Razorpay Slot Bookings :p1_3, after p1_2, 15d section Phase 2: CRM & Shipping CRM Pipeline & Contacts :p2_1, after p1_3, 20d ShippingRocket Integration :p2_2, after p2_1, 15d Walk-in POS Invoicing :p2_3, after p2_2, 15d section Phase 3: Automation Inventory Lock / Distributed :p3_1, after p2_3, 15d Bailey Whatsapp Engine :p3_2, after p3_1, 10d Daily Payment Reconciliation :p3_3, after p3_2, 15d section Phase 4: Scaling Warranties & RMAs :p4_1, after p3_3, 20d Technician Calendar & Apps :p4_2, after p4_1, 20d Loyalty & GMC SEO :p4_3, after p4_2, 15d ``` ### Phase Details #### Phase 1: Core Platform (Foundation) * Core storefront interface. * Unified OMS (basic workflow states). * Catalog listings (add/update/archive). * Slot bookings and Razorpay checkout (full and 30% advance payments). #### Phase 2: Customer & Revenue Systems * Lead pipelines and CRM contact managers. * Walk-in POS terminal integration. * Device service history ledger. * ShippingRocket automated labeling. #### Phase 3: Automation & Reliability * Distributed locks for stock states. * Daily automated payment reconciliations. * Bailey team alerts and notification engine. * Audit logging on mutations. #### Phase 4: Growth & Future-Proofing * RMA return management and Warranty tracker. * Technician assignment calendar app. * Customer self-service portal. * Loyalty program, Google Merchant feeds, SEO/AEO metadata. --- ## 16. Key Performance Indicators (KPIs) | Category | Metric | Target Metric | | :--- | :--- | :--- | | **Sales** | Booking abandonment rate | Decrease of 15% within 3 months of Phase 3 launch | | **Sales** | Lead-to-Won conversion rate | Increase of 10% from social channels | | **Sales** | Customer repeat visits | Tracked growth in loyalty points usage | | **Operations** | Average repair cycle time | Tracked job lifecycle durations in Technician module | | **Operations** | Reconciliation discrepancies | Reduced to < 0.1% of transactions | | **Reliability** | API Response latency | < 500ms (95th percentile) | | **Customer Exp** | Status inquiries | 30% reduction via self-service tracker adoption | --- ## 17. Appendix — Glossary * **BRD**: *Business Requirements Document* — Defines system capabilities and operational value. * **OMS**: *Order Management System* — Manages order/booking states. * **CRM**: *Client Resource Management* — System of record for contacts, proposals, and leads. * **RBAC**: *Role-Based Access Control* — Endpoint access permissions based on employee roles. * **RMA**: *Return Merchandise Authorization* — Workflow for inspecting and writing off returned items. * **DLQ**: *Dead Letter Queue* — Replay queue for failed message event executions. * **Idempotency**: Guarantee that an operation produces the same result when executed multiple times. * **Circuit Breaker**: System wrapper to prevent system hangs when third-party APIs are down. * **AEO**: *Answer Engine Optimization* — Adjusting schema to optimize surfacing in AI-driven search models. * **Bailey**: Private internal team notification app pushing updates to team WhatsApp groups.