# storefront-foundation/react-storefront architecture

> Architecture diagram of the GitHub repository storefront-foundation/react-storefront, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/storefront-foundation/react-storefront
- Repository: https://github.com/storefront-foundation/react-storefront

## Overview

##### Project Type and Purpose
- React Storefront is an open-source framework built on Next.js for creating high-performance, server-rendered, headless eCommerce PWAs with built-in support for AMP, predictive prefetching, caching, and code splitting.

##### High-Level Architectural Layers
Break the system into these logical layers:
a. Client Runtime (Browser/PWA)
- React hydration layer (Next.js client entry points)
- Service Worker (src/serviceWorker.js + src/sw/configureServiceWorker.js) for offline support, caching strategies, and background sync
- AMP renderer (Auto-AMP creation)
b. Presentation/UI Component Library
- src/*.js top-level components (Accordion, Breadcrumbs, etc.)
- Feature modules: /carousel, /menu, /plp (Product Listing), /search, /nav, /option, /session, etc.
- Storybook stories (/.storybook) that illustrate each component in isolation
c. Data & Business Logic
- src/api — adapters to fetch from real eCommerce backends (getAPIURL, addVersion)
- src/mock-connector — local mock data server for development/testing
- src/props — helper methods for Next.js data fetching (fetchServerSideProps, fulfillAPIRequest)
- src/hooks and src/utils — reusable React hooks and utilities (useLocalStorage, useIntersectionObserver, withCaching, mod, merge, etc.)
d. Server-Side Framework Extensions
- src/server — Next.js route listing and dynamic route generation (getRoutes, listRoutes)
- Plugins (/src/plugins) — e.g., withReactStorefront.js, withServiceWorker.js to extend Next.js’s Webpack and runtime
- Middleware (withAmpFormParser)
e. Build, Testing & Documentation
- Jest test suites under /test covering components, hooks, api, server, sw, etc.
- Storybook config in /.storybook
- Documentation scripts (docs/buildDocs.js, docs/moduleParser.js)
- CI/CD workflows (/.github/workflows/*.yml) for testing, publishing, release drafting

##### Component Interactions and Data Flow
- At build time, Next.js + React Storefront plugins generate pages, AMP variants, and skeleton loading states.
- On the first request, the Node.js server (Next.js SSR enhanced by src/server) fetches data via src/props → src/api connectors (or mock-connector in dev) and applies caching rules.
- The server renders HTML + JSON state, sends to the browser.
- The client bootstraps React, hydrates UI components, and uses service worker to cache assets and API responses for offline and fast navigations.
- Predictive prefetcher (built into core) observes user interactions (via NavigationEvent hooks) and preloads data/components.
- Data flows: Browser ⇄ Service Worker ⇄ Server SSR ⇄ External eCommerce APIs

##### Architectural Patterns & Principles
- Isomorphic/Universal JavaScript: same code runs on server and client
- Headless architecture: decoupled frontend consuming any backend via REST/GraphQL APIs
- Plugin-based extensibility: Next.js customization is encapsulated in /src/plugins
- Modular UI library: feature folders each expose composable React components
- Caching & PWA: service worker strategies, data hydration, client-side caching utilities

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer" 
        direction TB
        Browser["Browser (PWA)"]:::client
        ServiceWorker["Service Worker"]:::client
        AMPRenderer["AMP Renderer"]:::client
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        Accordion["Accordion"]:::ui
        Breadcrumbs["Breadcrumbs"]:::ui
        ActionButton["ActionButton"]:::ui
        subgraph "Carousel Components"
            direction TB
            Carousel["Carousel"]:::ui
            CarouselArrows["CarouselArrows"]:::ui
            CarouselDots["CarouselDots"]:::ui
        end
    end

    %% Data & Business Logic Layer
    subgraph "Data & Business Logic Layer"
        direction TB
        APIAdapters["API Adapters"]:::data
        MockConnector["Mock Connector"]:::data
        PropsHelpers["Props Helpers"]:::data
        Hooks["Hooks"]:::data
        Utils["Utils"]:::data
    end

    %% Server Layer
    subgraph "Server Layer"
        direction TB
        NextSSR["Next.js SSR"]:::server
        RouteGen["Route Generation"]:::server
        Plugins["Plugins"]:::server
        Middleware["Middleware"]:::server
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        EcommerceAPI["Headless eCommerce APIs"]:::external
        CDN["CDN / PaaS"]:::external
    end

    %% Build & Testing
    subgraph "Build, Testing & Documentation"
        direction TB
        Storybook["Storybook"]:::tool
        Jest["Jest Tests"]:::tool
        Docs["Docs Scripts"]:::tool
        CI["CI/CD Workflows"]:::tool
    end

    %% Connections
    Browser -->|requests| ServiceWorker
    ServiceWorker -->|caches assets/API| Browser
    Browser -->|hydrates| Accordion
    Browser --> AMPRenderer
    Accordion -->|"uses hooks/utils"| Hooks
    Carousel --> Hooks
    Hooks --> Utils
    Accordion --> PropsHelpers
    PropsHelpers --> APIAdapters
    APIAdapters --> EcommerceAPI
    MockConnector -.-> PropsHelpers
    NextSSR --> PropsHelpers
    NextSSR --> RouteGen
    NextSSR --> Plugins
    NextSSR --> Middleware
    Browser -->|prefetch| NextSSR
    NextSSR --> EcommerceAPI
    EcommerceAPI --> CDN
    Storybook --> Accordion
    Storybook --> Carousel
    Jest --> APIAdapters
    Jest --> Hooks
    Docs -->|"generate docs for"| Accordion
    CI --> Storybook
    CI --> Jest
    CI --> Docs

    %% Click Events
    click ServiceWorker "https://github.com/storefront-foundation/react-storefront/blob/master/src/serviceWorker.js"
    click AMPRenderer "https://github.com/storefront-foundation/react-storefront/blob/master/src/sw/configureServiceWorker.js"
    click Accordion "https://github.com/storefront-foundation/react-storefront/blob/master/src/Accordion.js"
    click Breadcrumbs "https://github.com/storefront-foundation/react-storefront/blob/master/src/Breadcrumbs.js"
    click ActionButton "https://github.com/storefront-foundation/react-storefront/blob/master/src/ActionButton.js"
    click Carousel "https://github.com/storefront-foundation/react-storefront/blob/master/src/carousel/Carousel.js"
    click CarouselArrows "https://github.com/storefront-foundation/react-storefront/blob/master/src/carousel/CarouselArrows.js"
    click APIAdapters "https://github.com/storefront-foundation/react-storefront/blob/master/src/api/getAPIURL.js"
    click MockConnector "https://github.com/storefront-foundation/react-storefront/blob/master/src/mock-connector/index.js"
    click PropsHelpers "https://github.com/storefront-foundation/react-storefront/blob/master/src/props/fetchServerSideProps.js"
    click Hooks "https://github.com/storefront-foundation/react-storefront/blob/master/src/hooks/useLocalStorage.js"
    click Utils "https://github.com/storefront-foundation/react-storefront/blob/master/src/utils/merge.js"
    click RouteGen "https://github.com/storefront-foundation/react-storefront/blob/master/src/server/getRoutes.js"
    click Plugins "https://github.com/storefront-foundation/react-storefront/blob/master/src/plugins/withReactStorefront.js"
    click Middleware "https://github.com/storefront-foundation/react-storefront/blob/master/src/middlewares/withAmpFormParser.js"
    click Storybook "https://github.com/storefront-foundation/react-storefront/blob/master/.storybook/main.js"
    click Jest "https://github.com/storefront-foundation/react-storefront/blob/master/jest.config.js"
    click Docs "https://github.com/storefront-foundation/react-storefront/blob/master/docs/buildDocs.js"
    click CI "https://github.com/storefront-foundation/react-storefront/blob/master/.github/workflows/test.yml"

    %% Styles
    classDef client fill:#AEDFF7,stroke:#036; 
    classDef ui fill:#B3DFFF,stroke:#036; 
    classDef data fill:#C6F6D5,stroke:#076; 
    classDef server fill:#FEEBC8,stroke:#E65; 
    classDef external fill:#E2E8F0,stroke:#667; 
    classDef tool fill:#F0FFF4,stroke:#48A;
```
