ifixkart-admin/Documentation/Documentation.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

24 KiB

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.

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

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.