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

467 lines
24 KiB
Markdown

# 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<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.
```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.