Web storefront

​

Technology stack

• Next.js 16 with App Router and React Server Components
• React 19 with React Compiler enabled
• TypeScript for type safety
• Tailwind CSS v4 for utility-first styling
• TanStack Query for server state management
• Zustand for client state (cart, session, wishlist)
• Radix UI for accessible component primitives
• Zod for runtime validation

​

Key features

​

Commerce capabilities

• Product listing and detail pages with rich merchandising
• Shopping cart with real-time updates
• Multi-step checkout flow
• User authentication and account management
• Order history and tracking
• Wishlist functionality
• Search with autocomplete

​

Personalization engine

• Interaction profile tracking (views, category affinity, cart adds)
• Weighted recommendation scoring and blending
• Personalized home page recommendations
• Personalized product list sorting

​

A/B testing framework

• Feature flags with weighted bucket assignment
• Persistent variant assignment
• Exposure tracking events
• Active experiments for homepage hero, pricing, and CTAs

​

Conversion optimization

• Exit intent recovery modals
• Stock urgency indicators with countdown timers
• Recently viewed products section
• Cross-sell and upsell recommendations
• Free shipping progress indicator

​

Performance optimization

• Cached catalog and product data with unstable_cache
• Incremental Static Regeneration (ISR) for product pages
• Suspense-based section loading
• Prefetch-on-hover for product cards
• Bundle analyzer integration

​

PWA support

• Service worker with offline caching
• Web app manifest
• Add-to-home-screen prompt
• Mobile swipe gestures in product gallery

​

Analytics

• Page views, product clicks, add-to-cart events
• Checkout step tracking and conversions
• Experiment exposure tracking
• Debug panel (open with Shift + A)

​

SEO optimization

• Product and breadcrumb JSON-LD
• Dynamic metadata and canonical links
• Robots.txt configuration
• Dynamic sitemap generation

​

Project structure

src/
├── app/              # Next.js App Router pages
│   ├── account/      # User account pages
│   ├── auth/         # Authentication flows
│   ├── cart/         # Shopping cart
│   ├── checkout/     # Checkout flow
│   ├── orders/       # Order history
│   ├── products/     # Product pages
│   └── wishlist/     # Wishlist management
├── components/       # React components
│   ├── analytics/    # Analytics components
│   ├── auth/         # Auth UI components
│   ├── cart/         # Cart components
│   ├── checkout/     # Checkout components
│   ├── layout/       # Layout components
│   ├── product/      # Product components
│   └── ui/           # Base UI components
├── domains/          # Domain logic modules
│   ├── analytics/    # Analytics domain
│   ├── catalog/      # Product catalog
│   └── personalization/ # Personalization
├── lib/              # Utilities and APIs
│   ├── api/          # API client
│   ├── analytics/    # Analytics utilities
│   ├── experiments/  # A/B testing
│   ├── personalization/ # Personalization logic
│   └── search/       # Search engine
├── hooks/            # Custom React hooks
├── store/            # Zustand stores
└── types/            # TypeScript definitions

​

Getting started

pnpm install

cp apps/web/.env.example apps/web/.env.local

NEXT_PUBLIC_AUTH_API_BASE_URL=http://localhost:4000/api/v1/auth

pnpm --filter web dev

​

Available scripts

pnpm --filter web dev

​

Demo credentials

• Email: [email protected]
• Password: demo123

​

Configuration

​

Next.js configuration

• React Compiler enabled for automatic optimization
• Standalone output for containerized deployments
• Remote image patterns for product images
• Bundle analyzer integration

​

PWA configuration

​

Important notes

• The mock database is in-memory and resets on server restart
• Personalization profiles, analytics, and cart data persist in browser localStorage
• The API Gateway runs on port 4000 and forwards auth requests to the auth service on port 4001