The Question
FE Design

Scalable Retail Marketplace Frontend Architecture

Design a high-performance, SEO-optimized frontend system for a large-scale retail marketplace. The system must support millions of products, provide a seamless search-to-checkout journey, and handle complex state management for shopping carts and multi-step checkout flows while maintaining strict performance budgets.
React
Next.js
SSR
Zustand
TanStack Query
Tailwind CSS
Zod
XState
Questions & Insights

Clarifying Questions

Scale & Traffic: Are we designing for a global scale with millions of products and concurrent users, or a niche marketplace?
Assumption: High-scale global marketplace requiring SEO-optimized product discovery.
Core User Role: Should we focus on the Buyer, Seller, or Admin experience for the MVP?
Assumption*: Focus strictly on the Buyer Experience** (Search, View, Cart, Checkout).
Platform Strategy: Is this a Mobile-First, Desktop-First, or Cross-Platform (React Native/Web) play?
Assumption*: Responsive Web** to maximize reach and SEO indexing.
Performance Targets: What are the critical Core Web Vitals targets?
Assumption: LCP < 2.5s and CLS < 0.1 for Product Detail Pages (PDP) to ensure high conversion and SEO ranking.

Crash Strategy

Discovery-First Architecture: The core bottleneck is the "Search-to-Detail" funnel. The architecture must prioritize SSR for SEO and performance.
Progressive Critical Path:
How do we ensure search engines can index millions of product pages? (Hybrid SSR/SSG Strategy).
How do we handle a highly dynamic cart and inventory status without full page reloads? (Client-side State Sync).
How do we orchestrate a secure, multi-step checkout flow? (Finite State Machine / Form Orchestrator).
How do we ensure global performance? (Edge Caching & Image Optimization).

Elite Bonus Points

Speculative Prefetching: Using Intl.requestIdleCallback to prefetch the PDP data when a user hovers over a product card in the listing.
Design System Tokens: Implementing a themeable token system to allow "White Labeling" for different sub-brands or regions.
Image Intelligence: Implementing an automated Image Service that serves WebP/AVIF formats based on the Accept header and device DPR.
Resilient Offline Cart: Using Workbox/Service Workers to allow users to add items to their cart even during intermittent network failures.
Design Breakdown

Requirements

Functional Requirements:
Product Discovery (Search & Category Browsing).
Product Listing Page (PLP) with filtering/sorting.
Product Detail Page (PDP) with high-res imagery and specs.
Shopping Cart management (Add/Remove/Update).
Secure Checkout flow (Shipping, Payment, Confirmation).
Non-Functional Requirements:
Performance: SSR for initial paint; < 2s TTI.
SEO: Meta tag management, JSON-LD schema for products.
Scalability: Support for virtualization in PLP for thousands of items.
Accessibility: WCAG 2.1 Level AA compliance.

Design Summary

Concise Summary: A modular SSR-based web architecture focusing on high-performance product discovery and a centralized state-driven checkout system.
Major Components:
Product Discovery Engine: Manages SEO-friendly search, filtering, and listing with virtualization.
Centralized Cart Store: A synchronized state manager for real-time inventory and pricing updates.
Checkout Orchestrator: A secure multi-step form handler managing complex validation and payment integration.
Edge Data Provider: A layer that fetches and caches product data at the nearest edge node.
CUJ Walkthrough:
Search: User enters query in App Shell, Product Discovery Engine fetches results via SSR.
Browsing: User scrolls PLP, Leaf Product Cards trigger speculative prefetching.
Selection: User views PDP, Centralized Cart Store checks inventory.
Purchase: User enters Checkout Orchestrator, completing the transactional flow.
Simplicity Audit: This design avoids Micro-frontends for the MVP to reduce operational complexity, opting for a Modular Monolith that can be split later if team size scales beyond 50+ engineers.
Architecture Decision Rationale:
Why this?: SSR (Next.js/Remix style) is non-negotiable for marketplaces due to SEO. A centralized state for the cart ensures UI consistency across tabs.
Requirement Satisfaction: Meets SEO via SSR, performance via edge caching, and UX via optimistic UI updates in the cart.

System Diagram

Architecture Deep Dive

Presentation Layer

Component Hierarchy: Uses an Outer App Shell (persistent Nav/Footer), Main Layout (spacing/grid systems), Pages (Search/PDP/Checkout), Feature Containers (Self-contained logic like CartDrawer), and Leaf Components (Atomic Design: Button, PriceTag).
Interaction Layer:
Input Validation: Real-time Zod-based validation in Checkout Form.
Feedback: Skeleton screens for PLP transitions; Toast notifications for "Added to Cart."
Responsive: CSS Grid for product layouts; Drawer-based navigation for mobile.
Rendering Layer:
SSR: Used for Search Page and Product Page to ensure SEO.
CSR: Used for the Checkout Page and User Profile (private data).
Virtualization: Used in Product Grid to handle long-scroll categories.
UI Frameworks: React with Tailwind CSS for rapid styling and Radix UI for accessible primitives.

Application Layer

Data Fetching Layer: Uses TanStack Query for client-side caching, stale-while-revalidate, and prefetching. Server-side prefetching is handled during the SSR request phase.
State Management Layer:
Global Cart State: Managed via Zustand with persistence to localStorage.
Checkout State: A Finite State Machine (XState) to handle transitions between (Shipping -> Payment -> Review).
Routing & Navigation: File-based routing (Next.js pattern) with dynamic segments for /product/[id]. Route guards protect the /checkout route for authenticated users.

Domain Layer

Business Rules:
Cart Logic: Encapsulates rules like "Maximum quantity per item" and "Discount eligibility."
Price Calculator: Handles currency conversion and tax calculations independently of the UI.
Entities / Models:
Product Model: Maps API DTOs to UI-friendly objects (e.g., formatting raw cents into 9.99).
Cart Entity: Ensures immutability when updating quantities.

Infrastructure Layer

API / Network: RESTful client with Axios, featuring interceptors for Auth headers and global error handling (401/404/500).
Storage:
Local Storage: Persists the Cart ID and basic user preferences.
CDN: Cloudinary or Imgix for dynamic resizing and format optimization of product assets.
Wrap Up

Wrap-up

Trade-offs: We chose SSR over CSR for discovery pages to favor SEO, accepting a slightly higher server cost. We deferred Micro-frontends (YAGNI) in favor of a clean modular monolith to speed up MVP delivery.
Optimization: Post-MVP, we would introduce Incremental Static Regeneration (ISR) for product pages to reduce server load for frequently viewed but rarely updated items.
Security: Implement Content Security Policy (CSP) and ensure all payment data is handled via PCI-compliant iFrame bridges (e.g., Stripe Elements).