# mercurjs/b2c-marketplace-storefront architecture

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

- Interactive diagram: https://gitdiagram.com/mercurjs/b2c-marketplace-storefront
- Repository: https://github.com/mercurjs/b2c-marketplace-storefront

## Overview

##### Project type and purpose
- This is a Next.js-based B2C storefront (“b2c-marketplace-storefront”) built on the Mercur open-source marketplace platform.
- It serves as the presentation layer: browsing, filtering, and buying products; handling cart, checkout, wishlist, seller pages, user account pages, and chat.
- It connects to a headless MedusaJS backend for commerce data and integrates external services (Algolia, Stripe, TalkJS).

##### File structure
- Top-level configuration and build files:
– next.config.ts, tsconfig.json, tailwind.config.ts, .env.template
– Storybook config under .storybook/
- src/app/… — App router pages grouped by locale and feature (checkout, main, reset-password). SSR/SSG routes.
- src/components/… — Atomic Design structure: atoms, cells, molecules, organisms, sections.
- src/lib/… — Data layer: client.tsx (fetch wrapper), config/constants, data adapters for each resource.
- src/hooks/… — UI logic utilities (pagination, filters, screen size).
- src/public/… — Static assets (images, algolia import screenshot).
- Middleware and types support authentication, i18n, error handling.

##### README insights
- Purpose: fully customizable B2C storefront demo for Mercur.
- External dependencies:
– MEDUSA_BACKEND_URL (headless commerce API)
– Algolia (search and filtering)
– Stripe (payments)
– TalkJS (chat)
- Deployment: run via `npm run dev` or deploy on Vercel.

a. Main components
1) Client (Browser/Mobile)
2) CDN / Static asset host (images, JS bundles)
3) Next.js Server (App Router, SSR/SSG, API routes, middleware)
4) Data-fetch layer (src/lib/client.tsx)
5) UI component library (atoms → sections)
6) External Services:
- MedusaJS Backend (Commerce API & Database)
- Algolia Search Index
- Stripe Payment Gateway
- TalkJS Chat Service
b. Relationships & interactions
- Client ↔ Next.js Server: HTTP(S) for page render (SSR) and client navigation (RSC/Client-side).
- Next.js ↔ Medusa API: REST calls (cart, products, orders, users).
- Next.js ↔ Algolia: search and facets queries.
- Next.js ↔ Stripe: payment intent creation or verification via API routes or direct SDK.
- Next.js ↔ TalkJS: chat session initialization in user pages.
- Static assets served from CDN or Next.js static folder.
c. Architectural patterns & design principles
- Hybrid rendering: SSR for SEO and initial load; SSG/ISR for public listing pages; client-side hydration for interactivity.
- Atomic Design for UI composition (atoms → sections).
- Separation of concerns:
– “app/” directory handles routing and layouts.
– “lib/” directory abstracts API communication.
– “hooks/” directory handles reusable UI logic.
- Environment-driven configuration (via .env.local).
d. Key technologies & frameworks
- Next.js (App Router, server and client components)
- React + TypeScript
- Tailwind CSS
- Storybook for component development
- MedusaJS (headless commerce)
- Algolia (search & filtering)
- Stripe (payment processing)
- TalkJS (real-time chat)

##### Detail without over-fragmenting
- Every external dependency and major internal layer.
- Avoid drawing each individual UI component; instead group them as “UI Component Library (atoms → sections)”.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client/UI Layer
    subgraph "Client/UI Layer"
        direction TB
        Browser["Browser (User)"]:::client
        CDN[(CDN / Static Assets)]:::cloud
    end

    %% Application Server Layer
    subgraph "Application Server"
        direction TB
        NX["Next.js Server<br/>(App Router & SSR/SSG)"]:::server
        MW["Middleware<br/>(Auth, i18n, Error)"]:::service
        CLIENT["Data-fetch Layer<br/>(HTTP Client)"]:::service
        APIAB["API Abstractions<br/>(MedusaJS calls)"]:::service
        CONFIG["Config & Constants"]:::service
        UICOMP["UI Component Library<br/>(atoms → sections)"]:::service
        HOOKS["Hooks<br/>(UI logic utilities)"]:::service
    end

    %% Backend/Datastore Layer
    subgraph "Backend / Datastore"
        direction TB
        MEDUSA["MedusaJS Backend"]:::databaseService
        MEDDB[(Medusa Database)]:::database
        ALG_IDX[(Algolia Search Index)]:::database
    end

    %% External Services Layer
    subgraph "Third-party Services"
        direction TB
        STRIPE["Stripe Payment Gateway"]:::external
        TALKJS["TalkJS Chat Service"]:::external
    end

    %% Relationships
    Browser -->|HTTP/HTTPS| NX
    Browser -->|Fetch Static Assets| CDN
    CDN -->|Served to| Browser
    NX -->|Middleware| MW
    NX -->|Uses| CLIENT
    CLIENT -->|Calls| APIAB
    APIAB -->|REST API| MEDUSA
    MEDUSA -->|Read/Write| MEDDB
    NX -->|Search Queries| ALG_IDX
    NX -->|Payment Intents| STRIPE
    NX -->|Chat Initialization| TALKJS
    NX -->|Renders & Hydrates UI| Browser

    %% Click Events
    click CDN "https://github.com/mercurjs/b2c-marketplace-storefront/tree/main/public/"
    click NX "https://github.com/mercurjs/b2c-marketplace-storefront/tree/main/src/app/"
    click MW "https://github.com/mercurjs/b2c-marketplace-storefront/blob/main/src/middleware.ts"
    click CLIENT "https://github.com/mercurjs/b2c-marketplace-storefront/blob/main/src/lib/client.tsx"
    click APIAB "https://github.com/mercurjs/b2c-marketplace-storefront/blob/main/src/lib/data/cart.ts"
    click APIAB "https://github.com/mercurjs/b2c-marketplace-storefront/blob/main/src/lib/data/products.ts"
    click APIAB "https://github.com/mercurjs/b2c-marketplace-storefront/blob/main/src/lib/data/orders.ts"
    click APIAB "https://github.com/mercurjs/b2c-marketplace-storefront/blob/main/src/lib/data/customer.ts"
    click APIAB "https://github.com/mercurjs/b2c-marketplace-storefront/blob/main/src/lib/data/regions.ts"
    click APIAB "https://github.com/mercurjs/b2c-marketplace-storefront/blob/main/src/lib/data/fulfillment.ts"
    click APIAB "https://github.com/mercurjs/b2c-marketplace-storefront/blob/main/src/lib/data/wishlist.ts"
    click APIAB "https://github.com/mercurjs/b2c-marketplace-storefront/blob/main/src/lib/data/reviews.ts"
    click APIAB "https://github.com/mercurjs/b2c-marketplace-storefront/blob/main/src/lib/data/seller.ts"
    click CONFIG "https://github.com/mercurjs/b2c-marketplace-storefront/blob/main/src/lib/config.ts"
    click UICOMP "https://github.com/mercurjs/b2c-marketplace-storefront/tree/main/src/components/"
    click HOOKS "https://github.com/mercurjs/b2c-marketplace-storefront/tree/main/src/hooks/"

    %% Styles
    classDef client fill:#A0D2EB,stroke:#004E66,color:#000
    classDef cloud fill:#ADE8F4,stroke:#0077B6,color:#000
    classDef server fill:#B8E986,stroke:#2F5233,color:#000
    classDef service fill:#C3F584,stroke:#5A7D23,color:#000
    classDef database fill:#E0C2F1,stroke:#6A2C70,color:#000
    classDef databaseService fill:#D0B4F2,stroke:#5E1D7A,color:#000
    classDef external fill:#FFD28E,stroke:#B06E00,color:#000
```
