BrandWala Retail – Market-Aware Cross-Border Commerce Platform

Executive Summary

BrandWala Retail (BW Retail) is a production-grade, market-aware cross-border commerce platform designed for cross-border consumer goods verticals — with its flagship deployment powering the K-Beauty (Korean Beauty) retail market.

The platform bridges international wholesale suppliers in the United Kingdom (Kobareseller, Koba International) with local resellers, retailers, and direct consumers in Bangladesh. Engineered with React 19, Vite 7, Tailwind CSS, TanStack React Query, and Firebase Firestore Lite, BW Retail automates the complete lifecycle: automated catalog scraping, market-scoped routing, dynamic 5-layer commission accounting, and quota-optimized customer intelligence.

flowchart TB
    subgraph Sourcing ["UK Wholesale Sourcing"]
        SCRAPE["Python ETL Scrapers<br/>Session/CSRF & WooCommerce APIs"] --> BRANDS["40+ K-Beauty Brands<br/>Auto-Tagging Engine"]
    end

    subgraph Data ["Firebase Cloud Firestore"]
        BRANDS --> PROD["markets/{market_id}/products"]
        PROD --> CART["carts/{email}/items"]
        CART --> ORDERS["markets/{market_id}/orders"]
        ORDERS --> PROJ["customer_order_book<br/>(Derived Projection)"]
        ORDERS --> ACCT["kbeauty_accounting_entries"]
    end

    subgraph Client ["React 19 Frontend SPA"]
        ROUTER["Market-Scoped Router<br/>/#/m/{marketSlug}/{vendorSlug}/*"]
        QUERY["TanStack Query v5<br/>Cache & Cursor Pagination"]
        UI["Radix / ShadCN Primitives<br/>Tailwind CSS"]
        CALC["5-Layer Commission Engine<br/>(ui_calculation snapshot)"]
    end

    Data <--> QUERY
    QUERY --> ROUTER --> UI
    UI --> CALC

The Cross-Border Problem

Operating cross-border commerce between the UK and Bangladesh creates unique architectural and operational challenges:

flowchart TD
    subgraph Legacy ["Legacy Manual Operations"]
        A["Browse UK wholesale sites manually"] --> B["Manually copy GBP prices to sheets"]
        B --> C["Hand-calculate COD %, packing, and margin"]
        C --> D["Take orders via WhatsApp chats"]
        D --> E["No repeat customer history or risk scoring"]
        E --> F["Firestore read costs explode from un-indexed scans"]
    end

Technical Architecture

1. Market-Aware & Vendor-Scoped Routing

The application enforces strict URL hierarchy and domain isolation using React Router:

• Products Catalog: /#/m/{marketSlug}/{vendorSlug}/products
• Shopping Cart: /#/m/{marketSlug}/{vendorSlug}/cart
• Order Management: /#/m/{marketSlug}/{vendorSlug}/orders
• Customer Purchase Book: /#/m/{marketSlug}/{vendorSlug}/customers

Global services (authentication, session state, market navigation) remain completely decoupled from market domain logic, allowing new retail verticals to plug into the platform without modifying core infrastructure.

flowchart LR
    URL["Route: /#/m/kbeauty/retail-1/orders"] --> GUARD["Market & Role Guards"]
    GUARD --> FEATURE["features/kbeauty/pages/OrdersPage.jsx"]
    FEATURE --> QUERY["useOrdersQuery (TanStack Query)"]
    QUERY --> FIRESTORE["Firestore: markets/kbeauty/orders"]

2. The 5-Layer Commission Engine

Every order computes net commissions deterministically through domain calculation pipelines (orderCommission.js & uiCommission.js), storing an immutable ui_calculation map directly on the order document:

flowchart TD
    subgraph Items ["Item Layer"]
        BASE["Base Wholesale Price (GBP)"]
        CUSTOM["Custom Reseller Sell Price (BDT)"]
        COMM["Base Product Commission"]
        EXTRA["Extra Profit = (Sell Price − Base Price) × Qty"]
    end

    subgraph Adjustments ["Order Deductions & Charges"]
        DEL["Delivery Adjustment (District / Thana)"]
        COD["COD Charge (Total × COD Rate %)"]
        PACK["Packing Flat Fee"]
        INV["Invoice Flat Fee"]
        FREE["Free Delivery Subsidy / Deduction"]
    end

    subgraph Output ["Settlement"]
        NET["Net Reseller Commission<br/>= Products Commission + Delivery Adjustment<br/>− COD Amount − Packing − Invoice − Free Delivery Deduction"]
    end

    BASE & CUSTOM & COMM --> EXTRA
    EXTRA & DEL & COD & PACK & INV & FREE --> NET

3. Quota Optimization & Derived Projections

To eliminate N+1 query fanout and high read costs on Firebase Firestore, BW Retail implements a comprehensive query optimization suite:

1. Debounced Query Execution: 250ms debounce on search bars preventing per-keystroke document reads.
2. Cursor-Based Pagination: Paginated document cursors with strict limit bounds.
3. No-Op Write Guards: Quantity update handlers compare dirty state before dispatching writes.
4. Derived Customer Order Book: A dedicated customer_order_book projection collection enabling instant KPI aggregation (effective quantities, order counts, gross spend) with lazy-loaded row expansions.

flowchart TD
    CRM["Customer Book Page"] --> CHECK{"Projection Exists?"}
    CHECK -- Yes --> PROJ["Projection Mode<br/>Read customer_order_book (1 read/customer)"]
    CHECK -- No --> FALLBACK["Legacy Fallback<br/>Aggregate active orders"]
    PROJ --> ROW["User Clicks Customer Row"]
    ROW --> LAZY["Lazy-Fetch Orders & Items on Demand"]

4. SQL & PostgreSQL Migration Readiness

To prepare the platform for enterprise relational throughput, a complete PostgreSQL migration architecture was designed:

• Core Relational Schemas: sql/postgres/001_core_schema.sql
• Performance Indexes: sql/postgres/002_indexes.sql
• Customer Order Book SQL Views: sql/postgres/003_customer_order_book_view.sql

Personal Engineering Contributions

• React 19 Frontend Architecture: Designed the market-aware component hierarchy, Radix/ShadCN UI design system, and TanStack Query state orchestration.
• Python Automated Sourcing ETL: Developed web scrapers with session auth and CSRF management for UK wholesale platforms, implementing automated regex brand detection for 40+ brands.
• Deterministic Commission Accounting: Authored the full 5-layer commission calculation engine, ensuring zero discrepancies across order creation, status changes, and quantity saves.
• Firestore Cost Optimization: Reduced Firestore read volume by over 60% through debounced search pipelines, cursor pagination, and derived projection collections.
• SQL Migration Strategy: Architected PostgreSQL database schemas, indexes, and SQL analytical views for long-term database scalability.