# Universal E-Commerce Growth Blueprint: Tenant-Configured Dynamic Merchandising, Zero-Manual Discovery & First-Time Visitor Attraction ## Executive Summary This blueprint provides a **100% automated, zero-manual-effort** e-commerce engine. All badge thresholds, freshness windows, stock urgency limits, and bundle discounts are **fully configurable per tenant in Company Profile**. The system dynamically computes badges and product pairings in real time, keeps MongoDB indexes fast with a nightly lifecycle cron, captivates first-time visitors with high-impact visual hooks, and tracks live customer behavior in the Admin Activities portal. --- ## 1. Company Profile Merchandising Configuration Architecture Instead of hardcoded rules, each merchant/tenant configures their own business thresholds directly inside **Settings → Company Profile**: ```mermaid flowchart TD subgraph AdminProfile ["Admin: Settings → Company Profile"] ConfigForm["Merchandising & Smart Badges Settings Card"] T1["🗓️ New Arrival Window (e.g. 7, 14, 30 days)"] T2["🔥 Low Stock Urgency Threshold (e.g. 3, 5, 10 items)"] T3["🏷️ Min Discount % for Offer Badge (e.g. 10%, 20%)"] T4["🌟 Bestseller Minimum Orders / Views Threshold"] T5["🎁 'Frequently Bought Together' Bundle Discount (e.g. 5%, 10%, 15%)"] end subgraph BackendEngine ["Backend Dynamic Engine"] CompanySettings[Company Profile Settings Cached per Tenant] ProductAPI[Product List & PDP APIs] DynamicResolution[Dynamic Badge & Bundle Resolver] Cron[Nightly productLifecycleCron.js] end subgraph StorefrontUI ["Storefront Experience (Visitor Facing)"] Shimmer["✨ 'JUST LAUNCHED' (Animated Glowing Shimmer)"] Urgency["🔥 'ONLY X LEFT' (Urgency FOMO)"] Discount["🏷️ '25% OFF' (Computed from Offer Price)"] Combos["📦 Autonomous 1-Click 'Frequently Bought Together' Bundles"] end ConfigForm --> CompanySettings CompanySettings --> DynamicResolution ProductAPI --> DynamicResolution CompanySettings --> Cron DynamicResolution --> Shimmer DynamicResolution --> Urgency DynamicResolution --> Discount DynamicResolution --> Combos ``` ### Additive Schema in [`company-detail-model.js`](file:///c:/thriveni/folder%20f/POS/EGF_POS/evergreen_pos_be/src/models/Company/company-detail-model.js): ```javascript // Non-breaking additive sub-schema in CompanySchema merchandisingSettings: { // New Arrival / Launch window newArrivalDaysThreshold: { type: Number, default: 14, min: 1, max: 90 }, enableNewArrivalShimmer: { type: Boolean, default: true }, // Low stock urgency trigger lowStockThreshold: { type: Number, default: 5, min: 1, max: 50 }, enableLowStockBadge: { type: Boolean, default: true }, // Discount & Offer badge minDiscountPercentageForBadge: { type: Number, default: 10, min: 1, max: 90 }, enableDiscountBadge: { type: Boolean, default: true }, // Bestseller & Popularity triggers bestsellerMinOrders: { type: Number, default: 10, min: 1 }, bestsellerMinViews: { type: Number, default: 100, min: 1 }, enableBestsellerBadge: { type: Boolean, default: true }, // Autonomous Combinations & Bundles ("Frequently Bought Together") enableDynamicBundles: { type: Boolean, default: true }, bundleDiscountPercentage: { type: Number, default: 10, min: 0, max: 50 }, maxBundleItems: { type: Number, default: 3, min: 2, max: 4 } } ``` --- ## 2. First-Time Visitor Attraction Journey (Cold-Start to Conversion) How the system dynamically captivates a visitor who has never visited the store before: ```mermaid flowchart LR Step1["1. Landing (0-3s)
• Glowing Shimmer on New Launches
• 'Trending Now' Velocity Carousel
• Brand Spotlight Chips"] --> Step2["2. Browsing (3-30s)
• Dynamic Category Facets (Brand/Color/Size/Material)
• 'Only 3 Left' FOMO Badges
• '25% OFF' Offer Highlights"] --> Step3["3. PDP & Combo (30-60s)
• Autonomous 3-Item Bundle
• 'Save 10% on this bundle'
• 1-Click 'Add All 3 to Cart'"] --> Step4["4. Fast Checkout
• Persistent Guest Cart
• Seamless Mobile/OTP Guest-to-Account
• Instant Live Telemetry to Admin"] ``` ### Detailed Breakdown of Visitor Hooks: 1. **0–3 Seconds (Visual Magnetism)**: - **"Recently Launched" Animated Shimmer**: CSS animation with glowing gradient border (`animate-shimmer`) draws instant visual focus to new inventory. - **"Trending Velocity" Feed**: Products scored dynamically based on recent storefront interest rise automatically to the top. 2. **3–30 Seconds (Zero-Friction Discovery)**: - **Dynamic Facet Filters**: Color swatches, Brand chips, and Size/Material filters render dynamically based on available inventory. - **Dynamic Badges**: - If `stock <= company.lowStockThreshold` $\rightarrow$ shows **"🔥 Only X Left"** - If `discount >= company.minDiscountPercentageForBadge` $\rightarrow$ shows **"🏷️ X% OFF"** - If `orders >= company.bestsellerMinOrders` $\rightarrow$ shows **"🌟 BESTSELLER"** 3. **30–60 Seconds (Basket Expansion / Higher AOV)**: - When a visitor views a product, an autonomous **"Frequently Bought Together"** bundle appears directly under the main product: - **Base Product + Companion Item 1 + Companion Item 2** - Real-Time Basket Co-occurrence (past orders) + Category Proximity Fallback (zero-history items). - **1-Click "Add Bundle to Cart"** button applying `company.bundleDiscountPercentage`. 4. **Checkout (Frictionless Conversion)**: - Anonymous session ID preserves cart even if tab is closed. - OTP checkout automatically binds guest cart to customer profile. --- ## 3. Real-Time Dynamic Affinity Engine (Zero Manual Linking) The storefront calls `GET /api/v1/nus-shop/frequently-bought-together?productId=:id`: ```mermaid flowchart TD Req[Storefront Requests Bundle for Product X] --> QueryOrder["Check Completed Orders in order.model.js"] QueryOrder -- "Orders Exist" --> Tier1["Tier 1: Order Basket Co-Occurrence
Calculates top items purchased in the same cart as Product X"] QueryOrder -- "No Orders (Cold-Start)" --> Tier2["Tier 2: AI Category & Price Tier Proximity
1. Category Companion Matrix (e.g. Plant -> Planter + Fertilizer)
2. Price Sweet Spot (Companion priced at 10%-30% of base item)
3. Top Rated / Best Sellers in companion category"] Tier1 --> ApplyDiscount["Apply Company Profile bundleDiscountPercentage (e.g. 10% off)"] Tier2 --> ApplyDiscount ApplyDiscount --> BundleResponse["Return Bundle Object
{ baseProduct, companionProducts: [A, B], totalPrice, bundlePrice, savings }"] ``` --- ## 4. Nightly Background Sync Cron (`src/cron/productLifecycleCron.js`) To ensure MongoDB query performance remains lightning fast for filtered queries (e.g., `filter=new-arrivals` or `sort=trending`): * A nightly cron job runs at 00:00: 1. Fetches each tenant's `merchandisingSettings.newArrivalDaysThreshold` from Company Profile. 2. Runs a fast `updateMany` to maintain indexed `isNewArrival` flags. 3. Re-scores `trendingVelocity` based on the past 7 days' telemetry. * **Merchant Effort**: **ZERO minutes required**. --- ## 5. Phase-by-Phase Implementation Plan ```mermaid gantt title Phase-by-Phase Delivery Roadmap dateFormat YYYY-MM-DD section Phase 1: Company Profile Settings Backend merchandisingSettings Schema & APIs :p1_1, 2026-09-08, 2d Admin Company Profile Merchandising UI Section :p1_2, after p1_1, 2d section Phase 2: Dynamic Engine & Visual Hooks Dynamic Badge & Discovery Resolver :p2_1, after p1_2, 2d Storefront Shimmer Badges & Visual Hooks :p2_2, after p2_1, 2d Autonomous 1-Click "Frequently Bought Together" :p2_3, after p2_2, 3d section Phase 3: Nightly Cron & Indexing src/cron/productLifecycleCron.js Implementation :p3_1, after p2_3, 2d section Phase 4: Admin Live Activities Stream Telemetry Hook & Activity Logs Extension :p4_1, after p3_1, 2d Admin /settings/user-activities Upgraded Tabs :p4_2, after p4_1, 2d section Phase 5: Retention & Fast Checkout Wishlist, Save-For-Later & 1-Click Reorder :p5_1, after p4_2, 3d Guest-to-Account Conversion at Checkout :p5_2, after p5_1, 2d ``` --- ## 6. Verification Plan ### Automated Verification * Run unit/syntax tests for backend routes: `node -c src/controllers/nursery/shop-controller.js` and `node -c src/cron/productLifecycleCron.js`. * Test dynamic badge resolution API with different company threshold payloads (e.g. 7 days vs 30 days, low stock 3 vs 10). * Verify bundle endpoint returns valid companion items for both high-order SKUs and 0-order fresh SKUs. ### Manual Verification 1. **Admin Portal**: Change `newArrivalDaysThreshold` from 14 to 30 in Company Profile, verify storefront immediately reflects updated badges. 2. **Storefront**: Open PDP, verify "Frequently Bought Together" displays 2 companion products with correct bundle savings discount. 3. **Admin Activities**: Perform actions in Storefront (view product, search, add to cart), verify live stream updates in `/settings/user-activities`.