# shopnex-ai/shopnex architecture

> Architecture diagram of the GitHub repository shopnex-ai/shopnex, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shopnex-ai/shopnex
- Repository: https://github.com/shopnex-ai/shopnex

## Overview

ShopNex is a Payload CMS-based commerce platform with a storefront, administrative commerce data, and optional extensions. Its principal customer journey is browsing products, managing a cart, completing checkout/payment, and receiving an order confirmation. The tree also includes alternative storefronts, an email-template editor, and plugins. Several connections below reflect README-documented capabilities; sampled source was limited, so internal wiring beyond explicit API/config and auth behavior is not inferred.

Main entry points: [`apps/simple-shop/src/app/(payload)/api/[...slug]/route.ts`](https://github.com/shopnex-ai/shopnex/blob/main/apps/simple-shop/src/app/(payload)/api/%5B...slug%5D/route.ts) (Payload API), [`apps/shop/src/app/(checkout)/checkout`](https://github.com/shopnex-ai/shopnex/tree/main/apps/shop/src/app/(checkout)/checkout) (Checkout Steps), [`apps/simple-shop/src/app/(storefront)`](https://github.com/shopnex-ai/shopnex/tree/main/apps/simple-shop/src/app/(storefront)) (Simple Storefront), [`apps/simple-shop/src/collections/Orders/Orders.ts`](https://github.com/shopnex-ai/shopnex/blob/main/apps/simple-shop/src/collections/Orders/Orders.ts) (Order Processing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_storefront["Storefronts"]
  node_shop_routes["Shop Routes"]
  node_catalog_pages["Catalog Views"]
  node_cart_page["Cart Page<br/>[page.tsx]"]
  node_checkout_pages["Checkout Steps"]
  node_accounts["Account Pages"]
  node_builder_store["Builder Storefront"]
  node_simple_store["Simple Storefront"]
end

subgraph group_commerce["Commerce Core"]
  node_cart_orders[("Cart and Orders")]
  node_products[("Products<br/>[Products.ts]")]
  node_order_collection[("Order Processing<br/>[Orders.ts]")]
  node_payment_data[("Payment Records<br/>[Payments.ts]")]
  node_shipping_data[("Shipping Setup<br/>[Shipping.ts]")]
  node_payload_api["Payload API<br/>[route.ts]"]
  node_payload_config["Payload Config<br/>[payload.config.ts]"]
  node_cms_admin["CMS Admin"]
end

subgraph group_content["Content Tools"]
  node_puck_editor["Puck Page Editor"]
  node_builder_plugin["Builder.io Plugin"]
end

subgraph group_extensions["Extensions"]
  node_auth_plugin["App Authentication<br/>[app.ts]"]
  node_analytics_plugin["Analytics Dashboard"]
  node_cj_plugin["CJ Integration<br/>[error-handler.ts]"]
end

subgraph group_email["Email Editor"]
  node_email_editor["Email Template Editor<br/>[useEmailEditor.ts]"]
  node_payload_sdk["Payload SDK<br/>[sdk.ts]"]
end

node_shopper(("Shopper"))
node_stripe["Stripe"]
node_fulfillment["Shipping Providers"]

node_shopper -->|"browses"| node_shop_routes
node_shop_routes -->|"renders"| node_catalog_pages
node_shopper -->|"manages cart"| node_cart_page
node_cart_page -->|"starts checkout"| node_checkout_pages
node_checkout_pages -->|"creates order"| node_order_collection
node_checkout_pages -->|"processes payment"| node_payment_data
node_order_collection -.->|"charges through"| node_stripe
node_order_collection -.->|"ships through"| node_fulfillment
node_shopper -->|"shops"| node_simple_store
node_simple_store -->|"browses"| node_products
node_simple_store -->|"uses cart"| node_cart_orders
node_payload_api -->|"loads config"| node_payload_config
node_cms_admin -->|"manages data"| node_payload_api
node_puck_editor -->|"stores pages"| node_payload_api
node_builder_store -.->|"uses content"| node_builder_plugin
node_shopper -->|"manages account"| node_accounts
node_accounts -.->|"authenticates with"| node_auth_plugin
node_email_editor -->|"loads and saves"| node_payload_sdk
node_payload_sdk -.->|"requests templates"| node_payload_api

click node_shop_routes "https://github.com/shopnex-ai/shopnex/tree/main/apps/shop/src/app/(main)"
click node_catalog_pages "https://github.com/shopnex-ai/shopnex/tree/main/apps/shop/src/templates"
click node_cart_page "https://github.com/shopnex-ai/shopnex/blob/main/apps/shop/src/app/(main)/cart/page.tsx"
click node_checkout_pages "https://github.com/shopnex-ai/shopnex/tree/main/apps/shop/src/app/(checkout)/checkout"
click node_accounts "https://github.com/shopnex-ai/shopnex/tree/main/apps/shop/src/app/(main)/account"
click node_builder_store "https://github.com/shopnex-ai/shopnex/tree/main/apps/builder-shop/src/app"
click node_simple_store "https://github.com/shopnex-ai/shopnex/tree/main/apps/simple-shop/src/app/(storefront)"
click node_cart_orders "https://github.com/shopnex-ai/shopnex/tree/main/apps/simple-shop/src/collections/Carts"
click node_products "https://github.com/shopnex-ai/shopnex/blob/main/apps/simple-shop/src/collections/Products/Products.ts"
click node_order_collection "https://github.com/shopnex-ai/shopnex/blob/main/apps/simple-shop/src/collections/Orders/Orders.ts"
click node_payment_data "https://github.com/shopnex-ai/shopnex/blob/main/apps/simple-shop/src/collections/Payments.ts"
click node_shipping_data "https://github.com/shopnex-ai/shopnex/blob/main/apps/simple-shop/src/collections/Shipping.ts"
click node_payload_api "https://github.com/shopnex-ai/shopnex/blob/main/apps/simple-shop/src/app/(payload)/api/%5B...slug%5D/route.ts"
click node_payload_config "https://github.com/shopnex-ai/shopnex/blob/main/apps/simple-shop/src/payload.config.ts"
click node_cms_admin "https://github.com/shopnex-ai/shopnex/tree/main/apps/simple-shop/src/app/(payload)/admin"
click node_puck_editor "https://github.com/shopnex-ai/shopnex/tree/main/apps/simple-shop/src/collections/Pages"
click node_builder_plugin "https://github.com/shopnex-ai/shopnex/tree/main/packages/builder-io-plugin/src"
click node_auth_plugin "https://github.com/shopnex-ai/shopnex/blob/main/packages/auth-plugin/src/plugins/app.ts"
click node_analytics_plugin "https://github.com/shopnex-ai/shopnex/tree/main/packages/analytics-plugin/src"
click node_cj_plugin "https://github.com/shopnex-ai/shopnex/blob/main/packages/cj-plugin/src/error-handler.ts"
click node_email_editor "https://github.com/shopnex-ai/shopnex/blob/main/apps/shopnex-email/clients/hooks/useEmailEditor.ts"
click node_payload_sdk "https://github.com/shopnex-ai/shopnex/blob/main/apps/shopnex-email/clients/utils/sdk.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_shop_routes,node_catalog_pages,node_cart_page,node_checkout_pages,node_accounts,node_builder_store,node_simple_store toneBlue
class node_cart_orders,node_products,node_order_collection,node_payment_data,node_shipping_data,node_payload_api,node_payload_config,node_cms_admin toneAmber
class node_puck_editor,node_builder_plugin toneMint
class node_auth_plugin,node_analytics_plugin,node_cj_plugin toneRose
class node_email_editor,node_payload_sdk,node_shopper,node_stripe,node_fulfillment toneIndigo
```

## Components

### Storefronts

- [Shop Routes](https://github.com/shopnex-ai/shopnex/tree/main/apps/shop/src/app/(main)): `apps/shop/src/app/(main)`
- [Catalog Views](https://github.com/shopnex-ai/shopnex/tree/main/apps/shop/src/templates): `apps/shop/src/templates`
- [Cart Page](https://github.com/shopnex-ai/shopnex/blob/main/apps/shop/src/app/(main)/cart/page.tsx): `apps/shop/src/app/(main)/cart/page.tsx`
- [Checkout Steps](https://github.com/shopnex-ai/shopnex/tree/main/apps/shop/src/app/(checkout)/checkout): `apps/shop/src/app/(checkout)/checkout`
- [Account Pages](https://github.com/shopnex-ai/shopnex/tree/main/apps/shop/src/app/(main)/account): `apps/shop/src/app/(main)/account`
- [Builder Storefront](https://github.com/shopnex-ai/shopnex/tree/main/apps/builder-shop/src/app): `apps/builder-shop/src/app`
- [Simple Storefront](https://github.com/shopnex-ai/shopnex/tree/main/apps/simple-shop/src/app/(storefront)): `apps/simple-shop/src/app/(storefront)`

### Commerce Core

- [Cart and Orders](https://github.com/shopnex-ai/shopnex/tree/main/apps/simple-shop/src/collections/Carts): `apps/simple-shop/src/collections/Carts`
- [Products](https://github.com/shopnex-ai/shopnex/blob/main/apps/simple-shop/src/collections/Products/Products.ts): `apps/simple-shop/src/collections/Products/Products.ts`
- [Order Processing](https://github.com/shopnex-ai/shopnex/blob/main/apps/simple-shop/src/collections/Orders/Orders.ts): `apps/simple-shop/src/collections/Orders/Orders.ts`
- [Payment Records](https://github.com/shopnex-ai/shopnex/blob/main/apps/simple-shop/src/collections/Payments.ts): `apps/simple-shop/src/collections/Payments.ts`
- [Shipping Setup](https://github.com/shopnex-ai/shopnex/blob/main/apps/simple-shop/src/collections/Shipping.ts): `apps/simple-shop/src/collections/Shipping.ts`
- [Payload API](https://github.com/shopnex-ai/shopnex/blob/main/apps/simple-shop/src/app/(payload)/api/%5B...slug%5D/route.ts): `apps/simple-shop/src/app/(payload)/api/[...slug]/route.ts`
- [Payload Config](https://github.com/shopnex-ai/shopnex/blob/main/apps/simple-shop/src/payload.config.ts): `apps/simple-shop/src/payload.config.ts`
- [CMS Admin](https://github.com/shopnex-ai/shopnex/tree/main/apps/simple-shop/src/app/(payload)/admin): `apps/simple-shop/src/app/(payload)/admin`

### Content Tools

- [Puck Page Editor](https://github.com/shopnex-ai/shopnex/tree/main/apps/simple-shop/src/collections/Pages): `apps/simple-shop/src/collections/Pages`
- [Builder.io Plugin](https://github.com/shopnex-ai/shopnex/tree/main/packages/builder-io-plugin/src): `packages/builder-io-plugin/src`

### Extensions

- [App Authentication](https://github.com/shopnex-ai/shopnex/blob/main/packages/auth-plugin/src/plugins/app.ts): `packages/auth-plugin/src/plugins/app.ts`
- [Analytics Dashboard](https://github.com/shopnex-ai/shopnex/tree/main/packages/analytics-plugin/src): `packages/analytics-plugin/src`
- [CJ Integration](https://github.com/shopnex-ai/shopnex/blob/main/packages/cj-plugin/src/error-handler.ts): `packages/cj-plugin/src/error-handler.ts`

### Email Editor

- [Email Template Editor](https://github.com/shopnex-ai/shopnex/blob/main/apps/shopnex-email/clients/hooks/useEmailEditor.ts): `apps/shopnex-email/clients/hooks/useEmailEditor.ts`
- [Payload SDK](https://github.com/shopnex-ai/shopnex/blob/main/apps/shopnex-email/clients/utils/sdk.ts): `apps/shopnex-email/clients/utils/sdk.ts`

### Other components

- **Shopper**
- **Stripe**
- **Shipping Providers**

## Connections

- Shopper → Shop Routes: browses
- Shop Routes → Catalog Views: renders
- Shopper → Cart Page: manages cart
- Cart Page → Checkout Steps: starts checkout
- Checkout Steps → Order Processing: creates order
- Checkout Steps → Payment Records: processes payment
- Order Processing → Stripe: charges through
- Order Processing → Shipping Providers: ships through
- Shopper → Simple Storefront: shops
- Simple Storefront → Products: browses
- Simple Storefront → Cart and Orders: uses cart
- Payload API → Payload Config: loads config
- CMS Admin → Payload API: manages data
- Puck Page Editor → Payload API: stores pages
- Builder Storefront → Builder.io Plugin: uses content
- Shopper → Account Pages: manages account
- Account Pages → App Authentication: authenticates with
- Email Template Editor → Payload SDK: loads and saves
- Payload SDK → Payload API: requests templates