- 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
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:
- The Development Team: A build specification detailing data models, API mappings, routing, components, and constraints.
- The Client (iFixKart): A plain-language explanation of functional modules, workflows, and business value.
- 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
- Customer Storefront (Next.js): Public portal for buying parts, laptops, mobiles, and booking repairs.
- Admin Board (Next.js): Internal dashboard used by staff to manage orders, inventory, CRM, billing, and reports.
- E-commerce Backend (FastAPI / MySQL): Services storefront traffic, checkout, slot booking, and payments.
- Admin Backend (FastAPI / MySQL): Services CRM, inventory ledger, billing, reporting, and RBAC.
- 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:
- Analyze Reference Website: Inspect visual layout, typography, colors, shadows on
https://demo.templatemonster.com/demo/501755.html. - Identify UI Components: Catalog all 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 flips, 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.
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:
New Order: Placed, awaiting payment.Paid: Confirmed via Razorpay.Processing: Picking stock or assigning service technician.Shipped: Handed over to ShippingRocket.Delivered: Received by customer.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), andArchived(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\rightarrowProposal\rightarrowWon / Lost\rightarrowActive Customer. - Escalates stalled leads (leads sitting in
Proposalstage > 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:
- Customer requests Return Merchandise Authorization (RMA) with a reason.
- In-store / shipping receiving inspection logs the return.
- Item is routed to
Restocked,Unavailable (Damaged), orWritten Off. - 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
- 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.
- Abandoned Transaction Recovery: Carts and incomplete service requests are tracked. Bailey notifies sales reps to contact customers who abandoned, capturing ready-to-buy customers.
- Reduced Service Friction: Requiring only a 30% booking deposit lowers payment friction and boosts conversion.
- Repeat Customer Activation: Tracks warranty timelines and IMEI histories to prompt customers with relevant upgrade offers and loyalty points.
- 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.