# yuangwei/payload-ecommerce architecture

> Architecture diagram of the GitHub repository yuangwei/payload-ecommerce, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yuangwei/payload-ecommerce
- Repository: https://github.com/yuangwei/payload-ecommerce

## Overview

##### Project type and purpose
- This is a full-stack, server-rendered React application built with Next.js (App Router).
- It embeds Payload CMS as a headless content management system, mounting its admin UI at `/admin` and its REST/GraphQL API under a catch-all API route.

##### File structure
- Top-level directories/files of interest:
- `app/` – Next.js App Router directory.
– `app/page.tsx` – main public-facing page.
– `app/admin/` – Payload admin UI.
– `app/api/[...slug]/route.ts` – catch-all Next.js API route that initializes Payload.
- `payload.config.ts` – Payload CMS configuration (collections, database).
- `collections/` – Payload collection definitions (e.g., `users.ts`).
- `next.config.ts`, `tsconfig.json` – Next.js and TypeScript config.
- Patterns: a single Next.js serverless entrypoint hosting both public pages and the CMS API/admin UI.

##### README
- Confirms a Next.js 13 project scaffolded via `create-next-app`.

a. Public Frontend (Next.js SSR/SSG)
b. Payload CMS Server (mounted in the API route)
c. Payload Admin UI (served at `/admin`)
d. Database (e.g., MongoDB or PostgreSQL)
e. External/Hosting (Vercel Serverless Functions, CDN for `public/` assets)

##### Relationships and data flows
- Public User → HTTP GET `/` or other page routes → Next.js Server
→ (during SSR/SSG) calls Payload CMS Server → Database → returns content → Next.js renders HTML → Public User.
- Admin User → navigates to `/admin` → Next.js serves static admin UI → Admin UI calls Payload CMS Server via REST/GraphQL → Database reads/writes → Admin UI updates.
- Build/Deploy pipeline (Vercel) picks up `next.config.ts`, environment variables, and deploys serverless functions for `app/api/[...slug]`.

##### Architectural patterns/design principles
- Headless CMS pattern: content is managed and exposed via a decoupled API.
- Server-side rendering (SSR) and static generation in Next.js for public pages.
- Single codebase for both front and back, with serverless functions hosting the CMS API.
- Separation of concerns:
- Presentation layer (React components in `app/`)
- Data layer (Payload collections + database)
- Integration layer (Next.js API route for Payload)

##### Relevant technologies/frameworks
- Next.js 13 (App Router, server components)
- React + TypeScript
- Payload CMS (with `payload.config.ts` + `collections/`)
- Tailwind CSS (`tailwind.config.ts`)
- Vercel (serverless hosting)
- MongoDB or PostgreSQL (configured via environment variables)

- Public Browser / User Agent
- Next.js App Server (App Router)
- Public Page Components (`app/page.tsx`, other routes)
- Admin UI Static Assets (`app/admin/*`)
- Payload CMS API (Next.js Serverless Function at `app/api/[...slug]`)
- Database (MongoDB/PostgreSQL)
- Vercel (Hosting & Serverless Execution)
- Page requests
- Data fetch (SSR)
- Admin UI API calls
- Database read/write
- Optional: CDN for `public/` assets, environment variables store

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Users
    User[/"Public User Browser"/]:::external
    AdminUser[/"Admin User Browser"/]:::external

    %% Next.js App Server
    subgraph "Next.js App Server" 
        direction TB
        PublicPages["Public Page Components"]:::frontend
        AdminUI["Payload Admin UI Static Assets"]:::cms
        API["Payload CMS API Route"]:::api
    end

    %% Config & Collections
    Config["Payload Config"]:::config
    Collections["Payload Collections"]:::config

    %% Database
    DB[(Database)]:::db

    %% External Services
    Vercel((Vercel Hosting)):::external
    CDN((CDN for public assets)):::external

    %% Arrows: Public Flow
    User -->|HTTP GET /| PublicPages
    PublicPages -->|REST/GraphQL| API
    API -->|Read/Write| DB
    DB -->|Results| API
    API -->|Content JSON| PublicPages
    PublicPages -->|Rendered HTML| User

    %% Arrows: Admin Flow
    AdminUser -->|HTTP GET /admin| AdminUI
    AdminUI -->|REST/GraphQL| API
    API -->|Read/Write| DB
    DB -->|Results| API
    API -->|JSON| AdminUI
    AdminUI -->|UI Update| AdminUser

    %% Build / Deploy
    Config & Collections --> Vercel
    PublicPages & AdminUI & API --> Vercel
    Vercel -.->|Serverless Functions| API
    Vercel -.->|Static Assets| AdminUI
    CDN -->|Serves files| AdminUI

    %% Mapping click events
    click PublicPages "https://github.com/yuangwei/payload-ecommerce/blob/main/app/layout.tsx"
    click PublicPages "https://github.com/yuangwei/payload-ecommerce/blob/main/app/page.tsx"
    click AdminUI "https://github.com/yuangwei/payload-ecommerce/blob/main/app/admin/[[...segments]]/page.tsx"
    click AdminUI "https://github.com/yuangwei/payload-ecommerce/blob/main/app/admin/[[...segments]]/not-found.tsx"
    click AdminUI "https://github.com/yuangwei/payload-ecommerce/blob/main/app/admin/importMap.js"
    click API "https://github.com/yuangwei/payload-ecommerce/blob/main/app/api/[...slug]/route.ts"
    click Config "https://github.com/yuangwei/payload-ecommerce/blob/main/payload.config.ts"
    click Collections "https://github.com/yuangwei/payload-ecommerce/blob/main/collections/index.ts"
    click Collections "https://github.com/yuangwei/payload-ecommerce/blob/main/collections/users.ts"
    click Vercel "https://github.com/yuangwei/payload-ecommerce/blob/main/next.config.ts"
    click Vercel "https://github.com/yuangwei/payload-ecommerce/blob/main/tsconfig.json"
    click Vercel "https://github.com/yuangwei/payload-ecommerce/blob/main/tailwind.config.ts"
    click CDN "https://github.com/yuangwei/payload-ecommerce/tree/main/public/"
    click Vercel "https://github.com/yuangwei/payload-ecommerce/blob/main/package.json"
    click Vercel "https://github.com/yuangwei/payload-ecommerce/blob/main/pnpm-lock.yaml"
    click Vercel "https://github.com/yuangwei/payload-ecommerce/blob/main/eslint.config.mjs"
    click Vercel "https://github.com/yuangwei/payload-ecommerce/blob/main/postcss.config.mjs"

    %% Styles
    classDef frontend fill:#def,stroke:#069,stroke-width:1px
    classDef cms fill:#fde,stroke:#906,stroke-width:1px
    classDef api fill:#eef,stroke:#339,stroke-width:1px
    classDef db fill:#efe,stroke:#393,stroke-width:1px
    classDef external fill:#f2f2f2,stroke:#666,stroke-width:1px,stroke-dasharray: 5 5
    classDef config fill:#ffd,stroke:#990,stroke-width:1px
```
