flowchart TD
    classDef fe fill:#dbeafe,stroke:#3b82f6,color:#1e40af,font-size:12px
    classDef be fill:#dcfce7,stroke:#16a34a,color:#166534,font-size:12px
    classDef db fill:#fef9c3,stroke:#ca8a04,color:#78350f,font-size:12px
    classDef ext fill:#f3e8ff,stroke:#9333ea,color:#4c1d95,font-size:12px
    classDef err fill:#fee2e2,stroke:#dc2626,color:#7f1d1d,font-size:12px
    classDef ok fill:#d1fae5,stroke:#059669,color:#064e3b,font-size:12px
    classDef warn fill:#fff7ed,stroke:#ea580c,color:#7c2d12,font-size:12px

    A([Seller opens Product Listing Form]):::fe

    subgraph S1 [Step 1 — Core Product Details]
        A --> FORM1[/Item Name max 200 chars\nBrand Name dropdown\nProduct Description rich text HTML\nBullet Points rich text fields min 3\nTarget Gender dropdown\nMaterial + Color + Manufacturer\nCountry of Origin + Dangerous Goods\nItem Weight kg\nItem Dimensions LxWxH cm REQUIRED\nSKU unique platform-wide\nHSN Code 4-8 digits auto-fills GST\nItem Condition dropdown\nTotal Stock required/]:::fe
        FORM1 --> SKU_BLUR[On blur: GET /api/v1/seller/products/sku-check\nReal-time uniqueness validation]:::be
        SKU_BLUR -->|Taken| SKU_ERR[Inline error: SKU already in use]:::err
        SKU_BLUR -->|Free| SKU_OK[Green checkmark shown]:::ok
        FORM1 --> HSN_BLUR[On blur: GET /api/v1/seller/products/hsn-lookup\nAuto-fill GST rate field]:::be
    end

    subgraph S2 [Step 2 — Images]
        S1 --> IMG_UP[Upload 2 to 10 images to Cloudinary\nDirect upload via Cloudinary widget\npublic_id returned to backend\nExactly one image = main image\nDrag-and-drop reorder supported]:::fe
        IMG_UP -->|Less than 2 images| IMG_ERR[Minimum 2 images required]:::err
        IMG_UP -->|No main selected| MAIN_ERR[Mark one image as main]:::err
    end

    subgraph S3 [Step 3 — Video Optional]
        S2 --> VID_UP[Upload one product demo video to Cloudinary\npublic_id stored on product record\nDisplayed on product detail page]:::fe
    end

    subgraph S4 [Step 4 — Pricing and Offers]
        S3 --> PRICE_FORM[/Stock total available units\nYour Price must be less than or equal to MRP\nMRP Maximum Retail Price/]:::fe
        PRICE_FORM --> PRICE_VALIDATE[Frontend Zod:\nPrice less than or equal to MRP\nStock must be a positive integer]:::fe
        PRICE_VALIDATE -->|Invalid| PRICE_ERR[Inline validation errors]:::err
    end

    subgraph S5 [Step 5 — Variants Optional]
        S4 --> VAR_TOGGLE{Add variants?}
        VAR_TOGGLE -->|Yes| VAR_FORM[/Per variant:\nSize + Color + Material override\nNumber of items override\nStock per variant\nPrice per variant lte  MRP\nMRP per variant/]:::fe
        VAR_TOGGLE -->|No| SUBMIT_STEP
    end

    subgraph S6 [Step 6 — SEO]
        VAR_FORM --> SEO_FORM[/SEO Title meta title\nMeta Description\nKeywords tags\nIf left blank: auto-generated\nfrom title + description + brand + category/]:::fe
        SEO_FORM --> SUBMIT_STEP
    end

    SUBMIT_STEP --> FORM_ACTIONS{Form Action}
    FORM_ACTIONS -->|Cancel| DISCARD[Discard all unsaved changes]:::warn
    FORM_ACTIONS -->|Save as Draft| DRAFT[(POST /api/v1/seller/products/draft\nstatus = DRAFT\nNo Algolia indexing yet)]:::db
    FORM_ACTIONS -->|Submit| FINAL_SUBMIT[POST /api/v1/seller/products\nMultipart body with all form data]:::be

    FINAL_SUBMIT --> SANITIZE[Server-side DOMPurify\nAll rich-text HTML fields sanitized]:::be
    SANITIZE --> SAVE[(Save Product record:\nLinked to sellerId\nImage public_ids array stored\nVideo public_id stored\nstatus = ACTIVE)]:::db
    SAVE --> ALGOLIA[SearchIndexService upserts Algolia record\nIndex name: products\nFields: productName, category, sku]:::be
    ALGOLIA --> DONE([Product live on marketplace]):::ok
        

flowchart TD
    classDef fe fill:#dbeafe,stroke:#3b82f6,color:#1e40af,font-size:12px
    classDef be fill:#dcfce7,stroke:#16a34a,color:#166534,font-size:12px
    classDef db fill:#fef9c3,stroke:#ca8a04,color:#78350f,font-size:12px
    classDef ext fill:#f3e8ff,stroke:#9333ea,color:#4c1d95,font-size:12px
    classDef err fill:#fee2e2,stroke:#dc2626,color:#7f1d1d,font-size:12px
    classDef ok fill:#d1fae5,stroke:#059669,color:#064e3b,font-size:12px
    classDef warn fill:#fff7ed,stroke:#ea580c,color:#7c2d12,font-size:12px

    A([Seller opens Inventory]):::fe
    A --> LOAD[GET /api/v1/seller/products\nWHERE isDeleted = false]:::be
    LOAD --> DB[(Query with joins:\nVariants for stock totals\nOrderItems for sales\nProductViews for view counts)]:::db
    DB --> TABLE[Render inventory table:\nStatus badge + created date\nThumbnail + name + SKU\nSales + Units + Stock + Views + Price\nStock shown orange if lte  5 units\nActions: Edit Pause Resume Delete]:::fe

    TABLE --> FILT{Filter/Sort}
    FILT -->|A-Z| F1[Sort name ASC]:::be
    FILT -->|Z-A| F2[Sort name DESC]:::be
    FILT -->|Oldest| F3[Sort createdAt ASC]:::be
    FILT -->|Newest| F4[Sort createdAt DESC]:::be
    FILT -->|Active only| F5[WHERE status = ACTIVE]:::be
    FILT -->|Paused only| F6[WHERE status = PAUSED]:::be

    TABLE --> EDIT_ACT[Edit -> Open product form pre-filled\nPATCH /api/v1/seller/products/:id\nSearchIndexService upsert/remove]:::be

    TABLE --> PAUSE_BTN[Seller clicks Pause]:::fe
    PAUSE_BTN --> PAUSE_CONFIRM{Confirm dialog}
    PAUSE_CONFIRM -->|Cancel| TABLE
    PAUSE_CONFIRM -->|Confirm| PAUSE_API[PATCH /api/v1/seller/products/:id/pause]:::be
    PAUSE_API --> PAUSE_DB[(status = PAUSED\neffectiveStock = 0\nActual stock preserved\nStock-Back subscribers NOT notified)]:::db
    PAUSE_DB --> ALGOLIA_RM[SearchIndexService removeProduct\nProduct hidden from search]:::be
    ALGOLIA_RM --> PAUSE_OK[Status badge = Paused\nBuyers see Out of Stock]:::ok

    TABLE --> RESUME_BTN[Seller clicks Resume]:::fe
    RESUME_BTN --> RESUME_API[PATCH /api/v1/seller/products/:id/resume]:::be
    RESUME_API --> RESUME_DB[(status = ACTIVE\neffectiveStock = actual stock\nProduct visible again)]:::db
    RESUME_DB --> ALGOLIA_ADD[SearchIndexService upsertProduct]:::be
    RESUME_DB --> ALERT_BATCH[Stock-back notification happens when inventory update moves stock from 0 to positive\nCreate Notification rows\nSocket.IO notificationsChanged\nSet notified = true]:::be
    ALGOLIA_ADD & ALERT_BATCH --> RESUME_OK[Status = Active\nSubscribers notified]:::ok

    TABLE --> DEL_BTN[Seller clicks Delete]:::fe
    DEL_BTN --> DEL_CONFIRM{Confirm delete?}
    DEL_CONFIRM -->|Confirm| DEL_API[DELETE /api/v1/seller/products/:id]:::be
    DEL_API --> DEL_DB[(isDeleted = true\ndeletedAt = NOW\nRemoved from all buyer queries)]:::db
    DEL_DB --> ALGOLIA_DEL[SearchIndexService removeProduct]:::be
    ALGOLIA_DEL --> DEL_OK[Product gone from marketplace]:::ok

    TABLE --> ROW_CLICK[Click product row:\nSplit view — buyer PDP + seller metrics]:::fe
        

flowchart TD
    classDef fe fill:#dbeafe,stroke:#3b82f6,color:#1e40af,font-size:12px
    classDef be fill:#dcfce7,stroke:#16a34a,color:#166534,font-size:12px
    classDef db fill:#fef9c3,stroke:#ca8a04,color:#78350f,font-size:12px
    classDef ext fill:#f3e8ff,stroke:#9333ea,color:#4c1d95,font-size:12px
    classDef err fill:#fee2e2,stroke:#dc2626,color:#7f1d1d,font-size:12px
    classDef ok fill:#d1fae5,stroke:#059669,color:#064e3b,font-size:12px
    classDef warn fill:#fff7ed,stroke:#ea580c,color:#7c2d12,font-size:12px

    A([Buyer completes Razorpay payment\nWebhook: payment.captured]):::ext
    A --> ORDER_CREATE[(Create Order:\nstatus = PENDING_SELLER_APPROVAL\nEscrow: funds held in platform balance)]:::db
    ORDER_CREATE --> SELLER_NOTIFY[Notification row + RealtimeService\nseller:data-changed and notifications:changed\nNew order — accept or reject in 24h]:::be
    SELLER_NOTIFY --> BUYER_CONFIRM[Buyer sees: Order Pending Approval\nPayment confirmed — awaiting seller acceptance]:::fe

    subgraph SELLER_ORDERS [Seller Orders Dashboard]
        TAB1[Tab 1 — PENDING_SELLER_APPROVAL\nOrders awaiting accept/reject\n24h countdown shown per order]:::fe
        TAB2[Tab 2 — UNSHIPPED PROCESSING\nAccepted orders — enter tracking]:::fe
        TAB3[Tab 3 — SHIPPED\nOrders with tracking number added]:::fe
        TAB4[Tab 4 — DELIVERED + COMPLETE\nDelivered + closed orders history]:::fe
    end

    ORDER_CREATE --> TAB1

    TAB1 --> DECISION{Seller Decision within 24 hours}
    DECISION -->|ACCEPT| ACCEPT[(Order.status = PROCESSING\nnotify buyer: accepted)]:::db
    DECISION -->|REJECT — must provide reason| REJECT_FORM[/Enter rejection reason\nRequired field/]:::fe
    REJECT_FORM --> REJECT_API[PATCH /api/v1/seller/orders/:id/reject\nbody: rejectionReason]:::be
    REJECT_API --> REJECT_DB[(Order.status = CANCELLED\nrejectionReason saved\nInitiate Razorpay refund)]:::db
    REJECT_DB --> REFUND[POST /v1/refunds\nRefund processed 5-7 business days\nBuyer notified: order cancelled]:::ext
    DECISION -->|No action after 24h| AUTO_ACCEPT[OrdersService setInterval every 60s\nautoAcceptDuePendingOrders\nOrder.status = PROCESSING]:::be

    ACCEPT --> TAB2
    AUTO_ACCEPT --> TAB2

    TAB2 --> SHIP_FORM[/Enter tracking number\nSelect courier partner\nMark as SHIPPED/]:::fe
    SHIP_FORM --> SHIP_API[PATCH /api/v1/seller/orders/:id/ship\nbody: trackingNumber, courierName, courierTrackingUrl]:::be
    SHIP_API --> SHIP_DB[(Order.status = SHIPPED\nShipping details saved\nBuyer notified with tracking link)]:::db
    SHIP_DB --> TAB3

    TAB3 --> DELIVERY{Delivery event}
    DELIVERY -->|OUT_FOR_DELIVERY webhook| OFD[(Order.status = OUT_FOR_DELIVERY)]:::db
    OFD --> DELIVERED_WEBHOOK[Logistics webhook: ORDER_PICKED_UP\nOR manual mark as delivered]:::ext
    DELIVERED_WEBHOOK --> PICKED[(Order.status = DELIVERED\nReserve release triggered)]:::db

    PICKED --> LEDGER[(OrderAccountingService.releaseDeliveredProceeds:\nwallet_available += sellerProceeds x 0.80\nwallet_reserve decremented by released amount\n20 percent remains reserved)]:::db
    LEDGER --> SELLER_CREDIT[Seller wallet release notification]:::ok
    PICKED --> TAB4

    subgraph STATUS_TRACK [Order Status Timeline]
        ST[PENDING_SELLER_APPROVAL\n-> PROCESSING\n-> SHIPPED\n-> OUT_FOR_DELIVERY\n-> DELIVERED\n-> RETURN_INITIATED if buyer requests return\n-> RETURN_ACCEPTED or RETURN_REJECTED\n-> RETURN_SHIPPED\n-> REFUND_PROCESSING\n-> REFUNDED or CLOSED]:::fe
    end
        

flowchart TD
    classDef fe fill:#dbeafe,stroke:#3b82f6,color:#1e40af,font-size:12px
    classDef be fill:#dcfce7,stroke:#16a34a,color:#166534,font-size:12px
    classDef db fill:#fef9c3,stroke:#ca8a04,color:#78350f,font-size:12px
    classDef ext fill:#f3e8ff,stroke:#9333ea,color:#4c1d95,font-size:12px
    classDef err fill:#fee2e2,stroke:#dc2626,color:#7f1d1d,font-size:12px
    classDef ok fill:#d1fae5,stroke:#059669,color:#064e3b,font-size:12px
    classDef warn fill:#fff7ed,stroke:#ea580c,color:#7c2d12,font-size:12px

    A([Seller opens A+ Content Manager]):::fe
    A --> LOAD_PRODUCTS[GET /api/v1/seller/products?status=ACTIVE\nDropdown: select product to add A+ content]:::be
    LOAD_PRODUCTS --> SELECT{Select product}

    SELECT -->|View existing A+| VIEW[GET /api/v1/seller/aplus/:productId\nRender read-only preview]:::be
    SELECT -->|Edit existing A+| EDIT[Load block editor\npre-filled with saved blocks\nfrom product.aPlusContent]:::fe
    SELECT -->|Delete| DEL[DELETE /api/v1/seller/aplus/:productId\nRemove all A+ blocks from product]:::be
    SELECT -->|Create new| CREATE[/Step 1: Enter Content Name + Language\nEN English / HI Hindi / GU Gujarati/]:::fe

    CREATE --> EDITOR[Step 2 — Block Editor\nAdd content blocks in order:]:::fe

    subgraph BLOCKS [Available Content Blocks — drag-and-drop reorder]
        EDITOR --> B1[Image Block\nFull-width or side-by-side\nOptional caption text\nUpload to Cloudinary]:::fe
        EDITOR --> B2[Heading Block\nH2 or H3 level\nSection heading text]:::fe
        EDITOR --> B3[Text Block\nRich text paragraph\nFormatting: bold italic lists]:::fe
        EDITOR --> B4[Video Block\nProduct demo or brand video\nUpload to Cloudinary]:::fe
        B1 & B2 & B3 & B4 --> REORDER[Drag-and-drop to reorder blocks\nOrder stored as array index]:::fe
    end

    EDITOR --> MEDIA_UP[Image/Video upload:\nCloudinary upload widget\npublic_id returned to frontend\nStored in block.mediaPublicId]:::ext

    REORDER --> PREVIEW[Step 3 — Live Preview\nRenders exactly as buyer will see it\nCohesive banner-like layout\nAll blocks visually connected\nIdentical to Amazon A+ display]:::fe

    PREVIEW --> ACTIONS{Action}
    ACTIONS -->|Save Draft| DRAFT[(POST /api/v1/seller/aplus\nbody:  productId, contentName, language, blocks \nstatus = DRAFT\nLinked to product + seller account)]:::db
    ACTIONS -->|Publish| PUBLISH[(status = PUBLISHED\nA+ content live on product detail page\nDisplayed below product description)]:::db
    ACTIONS -->|Delete| DELETE_CONFIRM[Confirm -> remove all A+ blocks]:::warn

    PUBLISH --> PDP[Product Detail Page:\nA+ content renders below description\nCohesive banner layout\nAll media loaded from Cloudinary public_ids\nBuyer sees seamless branded experience]:::ok
        

flowchart TD
    classDef fe fill:#dbeafe,stroke:#3b82f6,color:#1e40af,font-size:12px
    classDef be fill:#dcfce7,stroke:#16a34a,color:#166534,font-size:12px
    classDef db fill:#fef9c3,stroke:#ca8a04,color:#78350f,font-size:12px
    classDef ext fill:#f3e8ff,stroke:#9333ea,color:#4c1d95,font-size:12px
    classDef err fill:#fee2e2,stroke:#dc2626,color:#7f1d1d,font-size:12px
    classDef ok fill:#d1fae5,stroke:#059669,color:#064e3b,font-size:12px
    classDef warn fill:#fff7ed,stroke:#ea580c,color:#7c2d12,font-size:12px

    A([Seller opens Brand Management]):::fe
    A --> LOAD[GET /api/v1/seller/brand\nLoad current TradMark records]:::be
    LOAD --> STATUS{TradMark.tradeMarkStatus?}

    STATUS -->|PENDING_APPROVAL| WAIT_UI[Show pending status:\nSubmission date + expected approval\nProgress: Submitted -> Under Review -> Approved]:::warn
    STATUS -->|REJECTED| RESUBMIT_UI[Show rejection reason\nForm to resubmit with new brand name]:::err
    STATUS -->|ACTIVE| BRAND_VIEW[Show brand dashboard:\nBrand name + category + logo\nLinked products count\nLocked brands cannot be updated]:::ok

    BRAND_VIEW --> ACTIONS{Actions}
    ACTIONS -->|Update unlocked trademark| LOGO_UP[PATCH /api/v1/seller/brand/:id\nbody: categoryId, logoPublicId, logoUrl, description, websiteUrl]:::be
    ACTIONS -->|Update description/details| DESC_UP[PATCH /api/v1/seller/brand/:id\nsame UpdateBrandDto fields]:::be
    ACTIONS -->|View Linked Products| PRODUCTS[GET /api/v1/seller/products?brandId=xxx\nList all products under this brand]:::be

    RESUBMIT_UI --> RESUBMIT_FORM[/Enter new Brand Name\nOptional category, logo, description, website/]:::fe
    RESUBMIT_FORM --> RESUBMIT_SUBMIT[POST /api/v1/seller/brand/resubmit\nbody: name, categoryId, logoPublicId, logoUrl, description, websiteUrl]:::be
    RESUBMIT_SUBMIT --> UNIQUE_CHK[(Check new name uniqueness\ncase-insensitive)]:::db
    UNIQUE_CHK -->|Taken| NAME_ERR[409 — Brand name already registered]:::err
    UNIQUE_CHK -->|Free| RESUBMIT_DB[(Update rejected TradMark:\ntradeMarkStatus = PENDING_APPROVAL\nsubmittedAt + reviewDueAt\nUser accountSetupPhase = TRADEMARK_SUBMITTED)]:::db

    subgraph ADMIN [Admin Brand Review]
        ADMIN_LIST[Admin views pending brand submissions\nsorted by submittedAt]:::ext
        ADMIN_LIST --> ADMIN_DEC{Decision}
        ADMIN_DEC -->|Approve| APPR[(TradMark.tradeMarkStatus = ACTIVE\nUser ACTIVE only if bankReady\nEmail notification)]:::ok
        ADMIN_DEC -->|Reject| REJ[(TradMark.tradeMarkStatus = REJECTED\nrejectMessage stored\nUser accountSetupPhase = BANK_VERIFIED)]:::err
    end
        

flowchart TD
    classDef fe fill:#dbeafe,stroke:#3b82f6,color:#1e40af,font-size:12px
    classDef be fill:#dcfce7,stroke:#16a34a,color:#166534,font-size:12px
    classDef db fill:#fef9c3,stroke:#ca8a04,color:#78350f,font-size:12px
    classDef ext fill:#f3e8ff,stroke:#9333ea,color:#4c1d95,font-size:12px
    classDef err fill:#fee2e2,stroke:#dc2626,color:#7f1d1d,font-size:12px
    classDef ok fill:#d1fae5,stroke:#059669,color:#064e3b,font-size:12px
    classDef warn fill:#fff7ed,stroke:#ea580c,color:#7c2d12,font-size:12px

    A([Seller opens Deals and Coupons\nSidebar: Advertising section]):::fe
    A --> TABS{Choose type}

    subgraph DEALS [Deals — Lightning Deal and Best Deal]
        TABS -->|Deals| DEAL_LIST[GET /api/v1/seller/deals\nList tabs: Active / Scheduled / Ended\nSorted by startDate]:::be
        DEAL_LIST --> DEAL_ACTIONS{Action}
        DEAL_ACTIONS -->|Create| DEAL_STEP1[Step 1 — Select Product:\nChoose one eligible active product\nDeal eligibility check:\nMust have approved brand trademark\nMinimum 15 percent discount required\nPrice must be lower than current price]:::fe
        DEAL_STEP1 --> DEAL_STEP2[Step 2 — Set Deal Terms:\nDeal type: Lightning Deal 4-12 hours\nor Best Deal 1-14 days\nDeal price or discount percent\nMinimum deal quantity units\nStart date-time selection\nEnd date auto-set for Lightning Deals\nDeal badge preview shown]:::fe
        DEAL_STEP2 --> DEAL_STEP3[Step 3 — Review + Submit:\nOriginal price vs deal price comparison\nEstimated units & revenue shown\nSubmit deal for activation]:::fe
        DEAL_STEP3 --> DEAL_SAVE[(POST /api/v1/seller/deals\nstatus = DRAFT / SCHEDULED / ACTIVE\nDealProduct rows store originalPrice and dealPrice\nStatus refreshed by timestamp on list reads)]:::db
        DEAL_ACTIONS -->|Edit active deal| EDIT_RESTRICT[Edit restriction:\nCannot increase discount percentage\nCan only decrease discount amount\nor move end date earlier\nAnti-abuse protection]:::warn
        DEAL_ACTIONS -->|Delete| DEL_DEAL[(Soft delete isDeleted = true\nDeal price removed from product immediately\nAnalytics preserved)]:::db
        DEAL_ACTIONS -->|View| VIEW_DEAL[Performance view:\nUnits sold at deal price\nRevenue generated\nConversion uplift percentage\nDeal duration & reach]:::fe
    end

    subgraph COUPONS [Coupons — Checkout Code UX]
        TABS -->|Coupons| COUP_LIST[GET /api/v1/seller/coupons\nList tabs: Active / Scheduled / Expired]:::be
        COUP_LIST --> COUP_ACTIONS{Action}
        COUP_ACTIONS -->|Create| COUP_STEP1[Step 1 — Coupon Code + Type:\nCoupon code: custom seller-defined OR auto-generated\nCode uniqueness validated platform-wide\nType: Percentage off / Fixed amount off INR\nDiscount value entry]:::fe
        COUP_STEP1 --> COUP_STEP2[Step 2 — Applicability + Limits:\nApply to: All seller products / Specific products / Category\nMin order value required\nMax discount cap if percentage type\nStart date & End date\nMax total redemptions\nMax uses per customer]:::fe
        COUP_STEP2 --> COUP_STEP3[Step 3 — Review + Create:\nCoupon budget impact preview\nGreen clip badge preview shown]:::fe
        COUP_STEP3 --> COUP_SAVE[(POST /api/v1/seller/coupons\nStatus = DRAFT / SCHEDULED / ACTIVE\nBuyer enters code at checkout)]:::db
        COUP_ACTIONS -->|Edit| COUP_EDIT[Cannot increase discount while active\nCan decrease discount or shorten validity\nCan reduce max redemptions]:::warn
        COUP_ACTIONS -->|Cancel or Delete| COUP_DEL[(Coupon.isActive = false\nStatus CANCELLED or soft deleted\nFuture validation rejects it)]:::db
        COUP_ACTIONS -->|View| COUP_VIEW[Seller list shows status, scope,\nredemption limits, date window,\nand discount settings]:::fe
    end

    subgraph BUYER_APPLY [Buyer Clips and Applies Coupon]
        CLIP[Buyer enters seller coupon code\non checkout order summary]:::fe
        CLIP --> CHECKOUT[Coupon preview applies if cart qualifies]:::fe
        CHECKOUT --> VALIDATE[POST /api/v1/buyer/coupons/validate\nbody: code]:::be
        VALIDATE --> CODE_CHK[(Find coupon WHERE isActive = true\nAND startDate <= NOW <= endDate)]:::db
        CODE_CHK -->|Not found or expired| INVALID[Return 404 COUPON_NOT_FOUND]:::err
        CODE_CHK -->|Found| REDEMPT_CHK[(Check redemptions < maxRedemptions\nCheck buyer use count < maxPerCustomer\nCheck cartTotal >= minOrderValue)]:::db
        REDEMPT_CHK -->|Limits exceeded| EXCEEDED[Return 422 COUPON_LIMIT_REACHED]:::err
        REDEMPT_CHK -->|Valid| APPLY[Discount returned to checkout\nCouponRedemption RESERVED during payment create\nAPPLIED after payment verify and order transaction]:::ok
    end
        

flowchart TD
    classDef fe fill:#dbeafe,stroke:#3b82f6,color:#1e40af,font-size:12px
    classDef be fill:#dcfce7,stroke:#16a34a,color:#166534,font-size:12px
    classDef db fill:#fef9c3,stroke:#ca8a04,color:#78350f,font-size:12px
    classDef ext fill:#f3e8ff,stroke:#9333ea,color:#4c1d95,font-size:12px
    classDef err fill:#fee2e2,stroke:#dc2626,color:#7f1d1d,font-size:12px
    classDef ok fill:#d1fae5,stroke:#059669,color:#064e3b,font-size:12px
    classDef warn fill:#fff7ed,stroke:#ea580c,color:#7c2d12,font-size:12px

    A([Buyer opens delivered order detail]):::fe
    A --> RATE_FORM[/Buyer adds product review:\n1-5 stars + optional text\n/]:::fe
    RATE_FORM --> SUBMIT[POST /api/v1/buyer/reviews\nbody: sellerOrderId, orderItemId, productId, stars, title, comment]:::be
    SUBMIT --> AUTH_CHK[(Verify: order.buyerId = currentUser\norder.status = DELIVERED\nNo existing rating for this orderId)]:::db
    AUTH_CHK -->|Not eligible| ERR[403 — not eligible to rate]:::err
    AUTH_CHK -->|Eligible| SAVE[(Save SellerRating:\nstars, feedback, buyerId, sellerId, orderId\nCreate public record)]:::db
    SAVE --> UPDATE_AVG[(Recalculate seller averageRating:\nAVG stars + total count\nUpdate SellerProfile.avgRating)]:::db
    UPDATE_AVG --> RT[Notification row: RATING_RECEIVED\nSeller dashboard reflects new average on refetch]:::be
    UPDATE_AVG --> PUBLIC[Rating appears on:\nSeller profile page\nProduct detail page seller info section\nDashboard summary card]:::ok

    subgraph SELLER_RESPONSE [Seller Response to Review]
        PUBLIC --> SELLER_VIEW[Seller opens Ratings section\nGET /api/v1/seller/ratings\nList: all reviews with star + text + buyer]:::be
        SELLER_VIEW --> REPLY_BTN[Seller clicks Reply on any review]:::fe
        REPLY_BTN --> REPLY_FORM[/Enter public response\nMax 1000 chars/]:::fe
        REPLY_FORM --> REPLY_SUBMIT[PATCH /api/v1/seller/ratings/product-reviews/:id/reply\nor PATCH /api/v1/seller/ratings/:id/reply\nbody: replyText]:::be
        REPLY_SUBMIT --> REPLY_SAVE[(Save reply on SellerRating record\nPublicly visible below review)]:::db
    end
        

flowchart TD
    classDef fe fill:#dbeafe,stroke:#3b82f6,color:#1e40af,font-size:12px
    classDef be fill:#dcfce7,stroke:#16a34a,color:#166534,font-size:12px
    classDef db fill:#fef9c3,stroke:#ca8a04,color:#78350f,font-size:12px
    classDef ext fill:#f3e8ff,stroke:#9333ea,color:#4c1d95,font-size:12px
    classDef err fill:#fee2e2,stroke:#dc2626,color:#7f1d1d,font-size:12px
    classDef ok fill:#d1fae5,stroke:#059669,color:#064e3b,font-size:12px
    classDef warn fill:#fff7ed,stroke:#ea580c,color:#7c2d12,font-size:12px

    A([Authenticated buyer asks a question\non product detail page]):::fe
    A --> Q_SUBMIT[POST /api/v1/qa\nbody: productId, questionText]:::be
    Q_SUBMIT --> Q_SAVE[(Save Question:\nbuyerId, productId, questionText\nstatus = UNANSWERED)]:::db
    Q_SAVE --> NOTIFY_SELLER[Notification row + RealtimeService\nnotifications:changed and seller:data-changed\nNew question on product]:::be

    NOTIFY_SELLER --> SELLER_QA[Seller opens QandA Management\nGET /api/v1/seller/questions\nFilter: Unanswered / Answered / All\nSorted by: oldest first]:::be
    SELLER_QA --> TABLE[Table columns:\nQuestion text + buyer name masked\nProduct name + asked date\nSLA indicator: orange if more than 24h\nred if more than 48h\nAnswer status badge]:::fe

    TABLE --> ANSWER_FORM[/Seller clicks Answer:\nEnter answer text\nMax 2000 characters/]:::fe
    ANSWER_FORM --> ANSWER_SUBMIT[POST /api/v1/seller/questions/:id/answer\nbody: answerText]:::be
    ANSWER_SUBMIT --> ANSWER_SAVE[(Save answer on Question record\nstatus = ANSWERED\nPublicly visible on PDP)]:::db
    ANSWER_SAVE --> NOTIFY_BUYER[Notify buyer:\nIn-app + email: Your question was answered]:::be
    ANSWER_SAVE --> PDP_UPDATE[QandA section on product detail page\nshows question + answer publicly]:::ok

    TABLE --> REPORT_BTN[Seller can filter by status and productId\nAdmin can moderate through /api/v1/admin/questions]:::warn
        

flowchart TD
    classDef fe fill:#dbeafe,stroke:#3b82f6,color:#1e40af,font-size:12px
    classDef be fill:#dcfce7,stroke:#16a34a,color:#166534,font-size:12px
    classDef db fill:#fef9c3,stroke:#ca8a04,color:#78350f,font-size:12px
    classDef ext fill:#f3e8ff,stroke:#9333ea,color:#4c1d95,font-size:12px
    classDef err fill:#fee2e2,stroke:#dc2626,color:#7f1d1d,font-size:12px
    classDef ok fill:#d1fae5,stroke:#059669,color:#064e3b,font-size:12px
    classDef warn fill:#fff7ed,stroke:#ea580c,color:#7c2d12,font-size:12px

    A([Seller opens Messages section]):::fe
    A --> INBOX[GET /api/v1/seller/messages/threads\nAll threads sorted: last message DESC\nUnread count per thread shown]:::be
    INBOX --> THREAD_LIST[Render inbox:\nEach row: buyer avatar + name + last msg preview\nUnread indicator dot\nTimestamp]:::fe

    THREAD_LIST --> OPEN_THREAD[Seller clicks on thread\nGET /api/v1/seller/messages/threads/:id/messages\npageSize=50 oldest first]:::be
    OPEN_THREAD --> MARK_READ[(Mark all messages in thread as read\nhasUnreadBySeller = false\nDashboard unread count decrements)]:::db
    MARK_READ --> CHAT_UI[Render chat UI:\nMessages in WhatsApp-style bubbles\nSeller messages right-aligned\nBuyer messages left-aligned\nTimestamp per message]:::fe

    subgraph SEND_MSG [Seller Sends Message]
        CHAT_UI --> TEXT_INPUT[/Type message text\nPaper clip icon for image/]:::fe
        TEXT_INPUT --> SEND_TEXT[POST /api/v1/seller/messages\nbody: threadId, text]:::be
        SEND_TEXT --> MSG_SAVE[(Save ChatMessage:\nsenderId = sellerId\nreceiverID = buyerId\nmessageText, timestamp)]:::db
        MSG_SAVE --> EMIT_BUYER[RealtimeService emits message:created\nand threads:changed to buyer user room]:::ext
    end

    subgraph SEND_IMG [Seller Sends Image]
        CHAT_UI --> IMG_PICK[Seller selects image file]:::fe
        IMG_PICK --> CLOUDINARY_UP[Upload to Cloudinary\npublic_id returned]:::ext
        CLOUDINARY_UP --> SEND_IMG_MSG[POST /api/v1/seller/messages\nbody: threadId, imagePublicId, cloudinaryUrl]:::be
        SEND_IMG_MSG --> IMG_SAVE[(Save ChatMessage:\nimagePublicId + cloudinaryUrl\ntimestamp, senderId)]:::db
        IMG_SAVE --> EMIT_IMG[Socket.IO emit image message to buyer]:::ext
    end

    subgraph INCOMING [Buyer Message Arrives]
        BUYER_SEND[Buyer sends message or image]:::fe
        BUYER_SEND --> SAVE_BUYER[(Save ChatMessage:\nsenderId = buyerId\nreceiverID = sellerId)]:::db
        SAVE_BUYER --> EMIT_SELLER[RealtimeService emits message:created\nthreads:changed and notifications:changed]:::ext
        EMIT_SELLER --> NOTIF[Notification record stored\nseller popover and toast refresh]:::be
    end
        

flowchart TD
    classDef fe fill:#dbeafe,stroke:#3b82f6,color:#1e40af,font-size:12px
    classDef be fill:#dcfce7,stroke:#16a34a,color:#166534,font-size:12px
    classDef db fill:#fef9c3,stroke:#ca8a04,color:#78350f,font-size:12px
    classDef ext fill:#f3e8ff,stroke:#9333ea,color:#4c1d95,font-size:12px
    classDef err fill:#fee2e2,stroke:#dc2626,color:#7f1d1d,font-size:12px
    classDef ok fill:#d1fae5,stroke:#059669,color:#064e3b,font-size:12px
    classDef warn fill:#fff7ed,stroke:#ea580c,color:#7c2d12,font-size:12px

    A([Payment capture / checkout verification]):::ext
    A --> RESERVE[(OrderAccountingService.reserveSellerProceeds\nwallet_total_sales += SellerProceeds\nwallet_reserve += SellerProceeds\nWalletTransaction ORDER_CREDIT\npolicy = 100_reserved_until_delivery)]:::db
    RESERVE --> RESERVED_NOTIFY[Notification: Sale reserved in wallet]:::be
    RESERVED_NOTIFY --> DELIVERED[Seller marks order delivered]:::be
    DELIVERED --> RELEASE[(OrderAccountingService.releaseDeliveredProceeds\nMove 80 percent from reserve to available\nKeep 20 percent in reserve\nWalletTransaction RESERVE_RELEASE)]:::db

    subgraph WALLET_UI [Seller Wallet Dashboard — Never Cached]
        RELEASE --> OPEN[Seller opens Payouts section\nGET /api/v1/seller/wallet\nAlways fresh DB read — never Redis cached]:::be
        OPEN --> WALLET_DATA[(Load:\nwallet_total_sales\nwallet_available = balance - pending\nwallet_reserve\nwallet_withdrawn)]:::db
        WALLET_DATA --> RENDER[Render Wallet Dashboard:\nAvailable Balance card\nTotal Earned all-time\nTotal Withdrawn all-time\nPending Withdrawals\nTransaction history paginated 20/page\nRequest Withdrawal button]:::fe
        RENDER --> TXN_TYPES[Transaction types in history:\nORDER_CREDIT — green\nWITHDRAWAL_INITIATED — orange\nWITHDRAWAL_COMPLETE — blue\nWITHDRAWAL_FAILED — red\nREFUND_DEBIT — red]:::fe
    end

    subgraph WITHDRAWAL [Withdrawal Request Flow]
        RENDER --> WITHDRAW_BTN[Seller clicks Request Withdrawal]:::fe
        WITHDRAW_BTN --> VERIFY_CHK[(Check: sellerProfile.bankVerificationStatus = VERIFIED\nand SellerBankAccountDetails.isVerified = true)]:::db
        VERIFY_CHK -->|Not VERIFIED| NOT_VERIFIED[403 BANK_NOT_VERIFIED\nComplete bank verification first]:::warn
        VERIFY_CHK -->|VERIFIED| AMOUNT_FORM[/Enter withdrawal amount\nMin: INR 500\nMax: wallet_available balance\nSelect bank account/]:::fe
        AMOUNT_FORM --> PRE_CHECKS[(Validate:\nAmount gte  500\nAmount lte  wallet_available\npayoutsToday less than  2\nBankAccount.isVerified = true)]:::db
        PRE_CHECKS -->|Fail| VALIDATION_ERR[422 specific error:\nInsufficient balance OR\nBelow minimum OR\nDaily limit reached]:::err
        PRE_CHECKS -->|Pass| HOLD[(Atomic: deduct from wallet_available\nCreate PayoutRequest status=PENDING\nInsert WalletTransaction type=WITHDRAWAL_INITIATED)]:::db
        HOLD --> DISPATCH[Ensure Cashfree beneficiary\nCreate Cashfree payout transfer immediately\nReturn payout response]:::be
    end

    subgraph PROCESSING [Cashfree Payout Status]
        DISPATCH --> CF[Cashfree createBeneficiary if needed\nCashfree createPayout transfer\nStore transfer ids and status codes]:::ext
        CF --> RESULT{Cashfree status}
        RESULT -->|processed| COMPLETE[(PayoutRequest.status = COMPLETED\nwallet_withdrawn += amount\nWalletTransaction WITHDRAWAL_COMPLETE\nNotify seller success)]:::ok
        RESULT -->|pending / processing| PROCESSING_STATE[(PayoutRequest.status = PROCESSING\nSeller can call POST /api/v1/seller/payouts/refresh)]:::warn
        RESULT -->|failed / reversed| FAILED[(PayoutRequest.status = FAILED or REVERSED\nwallet_available += amount\nWalletTransaction WITHDRAWAL_FAILED\nNotify seller failure)]:::err
    end

    subgraph REFUND_IMPACT [Refund Impact on Wallet]
        REF([Refund approved for order]):::be
        REF --> REF_CHK[(Check if seller already credited\nfor this order)]:::db
        REF_CHK -->|Already credited| DEBIT[(Debit wallet_reserve -= refundAmount\nIf reserve insufficient: goes negative\nInsert WalletTransaction REFUND_DEBIT\nNotify seller)]:::db
        REF_CHK -->|Not credited| SKIP[No action required\nBuyer refunded from platform]:::ok
    end

    subgraph EXIT [Account Deletion — Final Settlement]
        EXIT_PROT[Current deletion gate:\nBlock if wallet.available > 0\nRetire email, phone, brand names\nSoft-delete user\nRevoke sessions\nRemove stored Cashfree beneficiary ids when possible]:::warn
    end
        

flowchart TD
    classDef fe fill:#dbeafe,stroke:#3b82f6,color:#1e40af,font-size:12px
    classDef be fill:#dcfce7,stroke:#16a34a,color:#166534,font-size:12px
    classDef db fill:#fef9c3,stroke:#ca8a04,color:#78350f,font-size:12px
    classDef ext fill:#f3e8ff,stroke:#9333ea,color:#4c1d95,font-size:12px
    classDef err fill:#fee2e2,stroke:#dc2626,color:#7f1d1d,font-size:12px
    classDef ok fill:#d1fae5,stroke:#059669,color:#064e3b,font-size:12px
    classDef warn fill:#fff7ed,stroke:#ea580c,color:#7c2d12,font-size:12px

    A([Seller initiates account deletion\nfrom Profile Settings]):::fe
    A --> REASON[/Select deletion reason and optional detail/]:::fe
    REASON --> OTP_REQUEST[POST /api/v1/auth/seller/delete/request\nGenerate deletion OTP\nTTL 60 seconds\nSend to verified email]:::be

    OTP_REQUEST --> WARN_SCREEN[/Display privacy policy warning:\nEmail & phone will be permanently retired\nCannot create a new account with same credentials\nUser must acknowledge before OTP entry/]:::fe
    WARN_SCREEN --> OTP_INPUT[/Enter 6-digit OTP\nConfirm deletion intent/]:::fe
    OTP_INPUT --> VERIFY_OTP[(Verify OTP hash + expiry)]:::db
    VERIFY_OTP -->|Invalid| OTP_ERR[OTP error]:::err
    VERIFY_OTP -->|Valid| SUBMIT_REQUEST[DELETE /api/v1/auth/seller/delete/verify\nbody: otp + reason + reasonDetail]:::be
    SUBMIT_REQUEST --> GATE1[(Check seller wallet.available)]:::db
    GATE1 -->|Balance exists| FAIL1[Block deletion\nWithdraw available wallet first]:::err
    GATE1 -->|Zero balance| SOFT_DELETE[(DeletionRequest RESOLVED\nSet User.isDeleted = true\nSet userProfileStatus = DELETED\nAll sessions invalidated\nRetire email, phone, brand names)]:::db
    SOFT_DELETE --> CASHFREE[Remove stored Cashfree beneficiary ids when possible]:::ext
    CASHFREE --> DONE([Account deleted\nCredentials permanently retired]):::ok

    subgraph RETIRED [Retired Credential Enforcement]
        REUSE[Attempt signup or login with retired email/phone]:::fe
        REUSE --> RET_CHK[(Check retired_credentials table)]:::db
        RET_CHK -->|Match found| HTTP410[Return HTTP 410 Gone:\nThis credential was associated with\na deleted account. Per Privacy Policy,\ndeleted credentials are permanently retired.\nContact support if this is an error.]:::err
    end
        

flowchart TD
    classDef fe fill:#dbeafe,stroke:#3b82f6,color:#1e40af,font-size:12px
    classDef be fill:#dcfce7,stroke:#16a34a,color:#166534,font-size:12px
    classDef db fill:#fef9c3,stroke:#ca8a04,color:#78350f,font-size:12px
    classDef ok fill:#d1fae5,stroke:#059669,color:#064e3b,font-size:12px
    classDef warn fill:#fff7ed,stroke:#ea580c,color:#7c2d12,font-size:12px

    A([Seller dashboard shell]):::fe --> NAV[Sidebar routes:
Dashboard, Products, Inventory, Orders,
Messages, Product Q&A, Deals & Coupons,
Payouts, A+ Content, Brand, Ratings,
Profile, API Testing]:::fe

    NAV --> PROMO_PAGE[Seller promotions page\n/seller/promotions]:::fe
    PROMO_PAGE --> LOAD[Load products, categories, deals, coupons]:::fe
    LOAD --> PRODUCTS[GET /api/v1/seller/products?limit=100]:::be
    LOAD --> CATS[GET /api/v1/seller/products/categories]:::be
    LOAD --> DEALS[GET /api/v1/seller/deals]:::be
    LOAD --> COUPONS[GET /api/v1/seller/coupons]:::be

    PROMO_PAGE --> CREATE_DEAL[POST /api/v1/seller/deals]:::be
    CREATE_DEAL --> DEAL_RULES{Validate}
    DEAL_RULES -->|Seller-owned active product| DEAL_DB[(Deal + DealProduct)]:::db
    DEAL_RULES -->|Variant mismatch or price invalid| DEAL_ERR[Return proper validation error]:::warn
    DEAL_DB --> DEAL_STATUS[Status resolved from startAt/endAt:
DRAFT, SCHEDULED, ACTIVE, ENDED, CANCELLED]:::ok

    PROMO_PAGE --> CREATE_COUPON[POST /api/v1/seller/coupons]:::be
    CREATE_COUPON --> COUP_RULES{Validate}
    COUP_RULES -->|Unique code and valid scope| COUP_DB[(Coupon + CouponProduct)]:::db
    COUP_RULES -->|Duplicate or invalid scope| COUP_ERR[Return proper validation error]:::warn

    DEALS --> CANCEL_DEAL[PATCH /api/v1/seller/deals/:id/cancel]:::be
    COUPONS --> CANCEL_COUPON[PATCH /api/v1/seller/coupons/:id/cancel]:::be
    CANCEL_DEAL --> SOFT[Soft state retained for analytics]:::db
    CANCEL_COUPON --> SOFT

    NAV --> TEST[Seller API testing page\n/seller/api-testing]:::fe
    TEST --> FIXTURES[Auto-load live fixtures:
seller product, categories, deal, coupon]:::be
    TEST --> RUN[Run GET/POST/PATCH endpoints with confirmation for mutations]:::ok

    PRODUCTS --> CACHE[Category/country/HSN metadata uses in-process cache
Free Redis preserved for OTP, lockout, checkout, queues]:::ok