FlexSell Wholesale Application Documentation
Complete technical documentation covering full-stack architecture, 17 Mongoose schemas, GST tax engine, Razorpay HMAC verification, and B2B document lifecycles.
01. Product Overview & Persona Segments
FlexSell Wholesale is an enterprise-grade B2B, B2C, and Dropshipping e-commerce platform engineered specifically for manufacturers, importers, wholesale distributors, and resellers. It features multi-tier pricing, GST tax compliance, automated Shiprocket dispatch, Razorpay payment verification, and B2B document generation.
Bulk Sourcing & Quotes
Tiered bulk prices, per-variant MOQs, formal quotation conversion, and GST-compliant tax invoices containing business GSTINs.
Direct Consumer Retail
Single-unit retail purchases, instant UPI/Razorpay payments, automated shipping calculation, and live tracking.
Reseller Fulfillment
Resellers place direct-to-customer orders with customized packing slips omitting wholesale cost information.
02. Layered Application Architecture
High-Level Flow Diagram
Key Architecture Principles
- Unified Client Services: All UI components invoke services in
src/services/that support an offlinelocalStoragesandbox whenisMockMode = trueand Next.js REST API routing when live. - Atomic Inventory Deductions: Product sub-variant stock is atomically decremented during order creation using MongoDB
$incand array filters. - Stateless JWT & CSRF: Sessions are maintained via
httpOnlycookies validated throughauthGuard.tsalongside double-submit CSRF token headers.
03. Technology Stack Inventory
| Category | Technology | Version | Purpose |
|---|---|---|---|
| Framework | Next.js (App Router) | 16.2.10 | Full-stack React framework with server components & route handlers |
| UI Engine | React / React DOM | 19.2.4 | Component rendering & concurrent mode hooks |
| Database | MongoDB / Mongoose | 9.7.4 | Document storage, schema validation & indexing |
| State Management | Zustand | 5.0.14 | Scoped client stores with localStorage persistence |
| Payments | Razorpay SDK | 2.9.8 | Online order creation & HMAC signature verification |
04. Application Routes Specification
Storefront homepage featuring CMS banners, categories, trending products & new arrivals.
Catalog listing with category filters, price sorting, tag search & pagination.
B2B bulk quotation request form for negotiated wholesale orders.
Multi-step checkout with coupon validation, GST calculation & Razorpay payment.
05. Database Schema & Mongoose Models (17 Models)
Customer Model (customers)
Stores B2C, B2B, and Dropshipping buyer accounts, bcrypt hashed passwords, address book, GSTINs, and failedLoginAttempts for account lockout.
Product Model (products)
Maintains catalog products, color variants, subvariant matrices (Size × Weight × Price Tiers), HSN codes, and barcode scanner numbers.
Order Model (orders)
Stores purchase orders, line item snapshots, shipping addresses, payment status (Pending, Paid), and order status transitions.
Invoice Model (invoices)
Manages B2B documents: Quotes (QUO-xxxx), Receipts (RCP-xxxx), and Tax Invoices (INV-xxxx) with GST breakdowns.
06. Authentication, Lockout & CSRF Rules
Account Lockout Protocol
07. Product Catalog & Multi-Tier Pricing Architecture
Supports multi-dimensional variant configurations (Color × Size × Weight) paired with a 3-tier price resolution matrix designed for Indian wholesale, retail, and dropshipping commerce.
Variant Matrix Architecture
Title, slug, categoryId, hsnCode, gstRate, priceIncludesGst
Color name, images array, subVariants list
Size, Weight, MRP, B2C Price, B2B Price, Dropship Price, Stock, SKU, Barcode
Standard single-unit retail price applied to guest visitors and standard consumer accounts.
Discounted bulk rate unlocked when minimum order quantity (MOQ) is met by B2B buyers.
Wholesale reseller rate applied when dropshipping items directly to end customers.
08. Atomic Inventory Management & Audit Ledger
Atomic Stock Decrement Query
  { _id: productId, "colorVariants.subVariants": { $elemMatch: { sku, stock: { $gte: qty } } } },
  { $inc: { "colorVariants.$[cv].subVariants.$[sv].stock": -qty, totalStock: -qty } },
  { arrayFilters: [{ "cv.color": color }, { "sv.sku": sku }] }
)
09. Indian GST Tax Engine Specifications
Buyer State == Seller State (e.g. MP == MP)
SGST = Total GST / 2
Buyer State != Seller State (e.g. MH != MP)
CGST = 0, SGST = 0
10. Order Fulfillment State Machine
11. Quote âž” Receipt âž” Invoice Lifecycle
Draft negotiable quotation for bulk wholesale orders. Fully editable before acceptance.
Payment pending receipt voucher issued upon order submission before online payment verification.
Immutable legal tax invoice generated automatically once payment verification succeeds.
12. Razorpay HMAC Signature Verification
Online Razorpay payments must pass server-side HMAC-SHA256 signature verification in /api/razorpay/verify before an order status is set to Paid:
  .update("order_id|payment_id")
  .digest("hex")
13. Shiprocket Fulfillment & Webhooks
Integrated directly with Shiprocket REST APIs for live courier serviceability, automated order fulfillment, shipping label generation, and real-time AWB tracking webhooks.
14. Admin Modules & REST API Directory
15. Security Control Matrix & Cryptography
HTTP headers restricting script execution to self, Razorpay, and Google.
Double-submit cookie pattern with X-CSRF-Token validation.
Upstash Redis sliding window limiter preventing brute-force API attacks.
Encrypted storage for sensitive API credentials in database settings.