# sophiabrandt/nextjs-ecommerce architecture

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

- Interactive diagram: https://gitdiagram.com/sophiabrandt/nextjs-ecommerce
- Repository: https://github.com/sophiabrandt/nextjs-ecommerce

## Overview

1. **Top-level shape**
   - This repo is a two-app monorepo: a **Keystone.js backend** in `backend/` and a **Next.js frontend** in `frontend/`.
   - The contract between them is **GraphQL**; the frontend does not talk to the database directly.

2. **Backend responsibility**
   - `backend/keystone.ts` is the Keystone entry point and `backend/schemas/` defines the data model.
   - Core entities are **User**, **Role**, **Product**, **ProductImage**, **CartItem**, **Order**, and **OrderItem**.
   - Keystone provides the admin/CMS layer plus a GraphQL API for CRUD and queries.

3. **Backend domain boundaries**
   - `backend/access.ts` and `backend/lib/accessEnv.ts` implement **role-based access control** and environment-driven permissions.
   - The schema layer is where relationships are modeled: products have images, orders contain order items, and users have cart items and roles.
   - This means authorization is enforced server-side, not just in the UI.

4. **Backend custom business flows**
   - `backend/mutations/addToCart.ts` and `backend/mutations/checkout.ts` are the main custom transactional operations.
   - These mutations are where the app turns “shop actions” into persistent records: adding items to a cart, placing an order, and clearing/transitioning cart state.
   - `backend/lib/stripe.ts` and `backend/lib/mail.ts` indicate checkout integrates with **Stripe payments** and **Mailgun email**.

5. **Backend persistence and data initialization**
   - The data store is **MongoDB**; the repo includes seed dumps under `backend/seed-data/`.
   - That seed data suggests the app can be bootstrapped with realistic products, users, orders, and supporting collections.
   - The backend is therefore both the API and the source of truth for commerce state.

6. **Frontend app structure**
   - The frontend is a Next.js app organized by feature: `authentication`, `cart`, `checkout`, `navigation-header`, `order`, `product`, `products`, and `search`.
   - Pages under `frontend/pages/` map to routes such as product detail, product edit, product listing, orders, sign-in, and reset-password.
   - Shared UI lives in `frontend/components/`, while design-system/theme setup is in `frontend/infrastructure/theme/`.

7. **Frontend data layer**
   - `frontend/lib/apollo.ts` sets up the Apollo Client, making GraphQL the main data access path.
   - `frontend/lib/graphql/` contains the app’s GraphQL operations, and `frontend/lib/graphql/generated/` holds typed operation artifacts.
   - This strongly suggests the UI is built around typed GraphQL queries/mutations rather than ad hoc fetch calls.

8. **Frontend shopping/cart behavior**
   - Cart behavior is split between **local client state** and **server state**.
   - `frontend/lib/cart/` contains cart calculation and update helpers, while cart feature components render and mutate the cart UI.
   - The app uses Apollo cache manipulation heavily to keep the experience responsive after add/remove operations.

9. **Rendering strategy**
   - The app mixes rendering modes:
     - **SSG/ISR** for product pages and product listings,
     - **SSR** for orders and product updates where fresh/authenticated data matters.
   - This is important architecturally because the frontend is not purely client-rendered; it uses Next.js data fetching to balance SEO, freshness, and interactivity.

10. **Authentication and authorization UX**
   - Authentication is handled in the `features/authentication` area with sign-in, sign-up, reset-request, reset, and sign-out flows.
   - The frontend queries the current user and conditionally shows actions like edit/delete based on permissions.
   - The real enforcement still lives on the backend, but the UI mirrors those permissions for usability.

11. **Search and catalog browsing**
   - The search feature is a distinct subsystem, with debounced search UI and GraphQL-backed product lookup.
   - Catalog browsing centers on product listing, pagination, and product detail pages, indicating the storefront is optimized for browsing large product sets.

12. **Infrastructure and delivery**
   - The repo is containerized with Docker and Docker Compose, with separate frontend/backend production compose files.
   - `Caddyfile` is included for local HTTPS/domain routing, and the README mentions GitLab CI and Docker Swarm for deployment.
   - In architecture terms, traffic flows through a reverse proxy to the frontend and backend services, with MongoDB as the persistent store and Stripe/Mailgun as external service dependencies.

Main entry points: [`frontend/pages/index.tsx`](https://github.com/sophiabrandt/nextjs-ecommerce/blob/main/frontend/pages/index.tsx) (Pages), [`frontend/lib/apollo.ts`](https://github.com/sophiabrandt/nextjs-ecommerce/blob/main/frontend/lib/apollo.ts) (GraphQL Client), [`backend/keystone.ts`](https://github.com/sophiabrandt/nextjs-ecommerce/blob/main/backend/keystone.ts) (Keystone), [`backend/mutations/index.ts`](https://github.com/sophiabrandt/nextjs-ecommerce/blob/main/backend/mutations/index.ts) (Mutations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_backend_entry["Keystone<br/>entrypoint<br/>[keystone.ts]"]
  node_backend_schema["Schema<br/>domain model<br/>[index.ts]"]
  node_backend_access["Access Control<br/>authorization<br/>[access.ts]"]
  node_backend_mutations["Mutations<br/>business flows<br/>[index.ts]"]
  node_backend_stripe["Stripe<br/>payment adapter<br/>[stripe.ts]"]
  node_backend_mail["Mailgun<br/>notification adapter<br/>[mail.ts]"]
  node_backend_seed[("Seed Data<br/>mongo seed<br/>[db.dump]")]
end

subgraph group_frontend["Frontend"]
  node_frontend_pages["Pages<br/>routes<br/>[index.tsx]"]
  node_frontend_features_products["Catalog<br/>feature<br/>[index.tsx]"]
  node_frontend_features_product_admin["Product Admin<br/>feature<br/>[index.tsx]"]
  node_frontend_features_cart["Cart<br/>feature<br/>[index.tsx]"]
  node_frontend_features_checkout["Checkout<br/>feature<br/>[index.tsx]"]
  node_frontend_features_auth["Auth<br/>feature<br/>[index.tsx]"]
  node_frontend_features_orders["Orders<br/>feature<br/>[index.tsx]"]
  node_frontend_search["Search<br/>feature<br/>[index.tsx]"]
  node_frontend_graphql["GraphQL Client<br/>data layer<br/>[apollo.ts]"]
  node_frontend_cart_lib["Cart Logic<br/>client state<br/>[index.ts]"]
  node_frontend_theme["Theme<br/>ui foundation<br/>[index.ts]"]
end

subgraph group_infra["Infra"]
  node_docker_stack["Compose<br/>deployment<br/>[docker-compose.yml]"]
  node_caddy["Caddy<br/>reverse proxy"]
end

node_backend_entry -->|"loads model"| node_backend_schema
node_backend_entry -->|"applies rules"| node_backend_access
node_backend_entry -->|"registers flows"| node_backend_mutations
node_backend_schema -.->|"backed by"| node_backend_seed
node_backend_mutations -->|"charges payment"| node_backend_stripe
node_backend_mutations -->|"sends email"| node_backend_mail
node_frontend_pages -->|"renders"| node_frontend_features_products
node_frontend_pages -->|"renders"| node_frontend_features_product_admin
node_frontend_pages -->|"renders"| node_frontend_features_cart
node_frontend_pages -->|"renders"| node_frontend_features_checkout
node_frontend_pages -->|"renders"| node_frontend_features_auth
node_frontend_pages -->|"renders"| node_frontend_features_orders
node_frontend_pages -->|"renders"| node_frontend_search
node_frontend_features_products -->|"queries"| node_frontend_graphql
node_frontend_features_product_admin -->|"mutates"| node_frontend_graphql
node_frontend_features_cart -->|"updates state"| node_frontend_cart_lib
node_frontend_features_cart -->|"mutates"| node_frontend_graphql
node_frontend_features_checkout -->|"creates order"| node_frontend_graphql
node_frontend_features_auth -->|"auth ops"| node_frontend_graphql
node_frontend_features_orders -->|"queries"| node_frontend_graphql
node_frontend_search -->|"searches"| node_frontend_graphql
node_frontend_graphql -->|"API boundary"| node_backend_entry
node_frontend_theme -.->|"styles"| node_frontend_pages
node_docker_stack -->|"runs"| node_backend_entry
node_docker_stack -->|"runs"| node_frontend_pages
node_caddy -->|"routes to"| node_docker_stack

click node_backend_entry "https://github.com/sophiabrandt/nextjs-ecommerce/blob/main/backend/keystone.ts"
click node_backend_schema "https://github.com/sophiabrandt/nextjs-ecommerce/blob/main/backend/schemas/index.ts"
click node_backend_access "https://github.com/sophiabrandt/nextjs-ecommerce/blob/main/backend/access.ts"
click node_backend_mutations "https://github.com/sophiabrandt/nextjs-ecommerce/blob/main/backend/mutations/index.ts"
click node_backend_stripe "https://github.com/sophiabrandt/nextjs-ecommerce/blob/main/backend/lib/stripe.ts"
click node_backend_mail "https://github.com/sophiabrandt/nextjs-ecommerce/blob/main/backend/lib/mail.ts"
click node_backend_seed "https://github.com/sophiabrandt/nextjs-ecommerce/blob/main/backend/seed-data/db.dump"
click node_frontend_pages "https://github.com/sophiabrandt/nextjs-ecommerce/blob/main/frontend/pages/index.tsx"
click node_frontend_features_products "https://github.com/sophiabrandt/nextjs-ecommerce/blob/main/frontend/features/products/index.tsx"
click node_frontend_features_product_admin "https://github.com/sophiabrandt/nextjs-ecommerce/blob/main/frontend/features/product/index.tsx"
click node_frontend_features_cart "https://github.com/sophiabrandt/nextjs-ecommerce/blob/main/frontend/features/cart/index.tsx"
click node_frontend_features_checkout "https://github.com/sophiabrandt/nextjs-ecommerce/blob/main/frontend/features/checkout/index.tsx"
click node_frontend_features_auth "https://github.com/sophiabrandt/nextjs-ecommerce/blob/main/frontend/features/authentication/index.tsx"
click node_frontend_features_orders "https://github.com/sophiabrandt/nextjs-ecommerce/blob/main/frontend/features/order/index.tsx"
click node_frontend_search "https://github.com/sophiabrandt/nextjs-ecommerce/blob/main/frontend/features/search/index.tsx"
click node_frontend_graphql "https://github.com/sophiabrandt/nextjs-ecommerce/blob/main/frontend/lib/apollo.ts"
click node_frontend_cart_lib "https://github.com/sophiabrandt/nextjs-ecommerce/blob/main/frontend/lib/cart/index.ts"
click node_frontend_theme "https://github.com/sophiabrandt/nextjs-ecommerce/blob/main/frontend/infrastructure/theme/index.ts"
click node_docker_stack "https://github.com/sophiabrandt/nextjs-ecommerce/blob/main/docker-compose.yml"
click node_caddy "https://github.com/sophiabrandt/nextjs-ecommerce/tree/main/Caddyfile"

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_backend_entry,node_backend_schema,node_backend_access,node_backend_mutations,node_backend_stripe,node_backend_mail,node_backend_seed toneBlue
class node_frontend_pages,node_frontend_features_products,node_frontend_features_product_admin,node_frontend_features_cart,node_frontend_features_checkout,node_frontend_features_auth,node_frontend_features_orders,node_frontend_search,node_frontend_graphql,node_frontend_cart_lib,node_frontend_theme toneAmber
class node_docker_stack,node_caddy toneMint
```

## Components

### Backend

Keystone.js commerce API, schema, and business mutations.

- [Keystone](https://github.com/sophiabrandt/nextjs-ecommerce/blob/main/backend/keystone.ts): entrypoint · Keystone bootstrap and app composition. · `backend/keystone.ts`
- [Schema](https://github.com/sophiabrandt/nextjs-ecommerce/blob/main/backend/schemas/index.ts): domain model · Core CMS and commerce entities plus relationships. · `backend/schemas/index.ts`
- [Access Control](https://github.com/sophiabrandt/nextjs-ecommerce/blob/main/backend/access.ts): authorization · Role-based permissions and environment-driven access rules. · `backend/access.ts`
- [Mutations](https://github.com/sophiabrandt/nextjs-ecommerce/blob/main/backend/mutations/index.ts): business flows · Custom add-to-cart and checkout operations. · `backend/mutations/index.ts`
- [Stripe](https://github.com/sophiabrandt/nextjs-ecommerce/blob/main/backend/lib/stripe.ts): payment adapter · Payment integration used during checkout. · `backend/lib/stripe.ts`
- [Mailgun](https://github.com/sophiabrandt/nextjs-ecommerce/blob/main/backend/lib/mail.ts): notification adapter · Email delivery integration used during checkout and account flows. · `backend/lib/mail.ts`
- [Seed Data](https://github.com/sophiabrandt/nextjs-ecommerce/blob/main/backend/seed-data/db.dump): mongo seed · MongoDB dump and collection snapshots for bootstrapping commerce data. · `backend/seed-data/db.dump`

### Frontend

Next.js storefront and admin-facing UI.

- [Pages](https://github.com/sophiabrandt/nextjs-ecommerce/blob/main/frontend/pages/index.tsx): routes · Next.js route entrypoints for catalog, auth, orders, and product management. · `frontend/pages/index.tsx`
- [Catalog](https://github.com/sophiabrandt/nextjs-ecommerce/blob/main/frontend/features/products/index.tsx): feature · Product browsing, listing, detail, and pagination UI. · `frontend/features/products/index.tsx`
- [Product Admin](https://github.com/sophiabrandt/nextjs-ecommerce/blob/main/frontend/features/product/index.tsx): feature · Create, update, delete, and sell product actions. · `frontend/features/product/index.tsx`
- [Cart](https://github.com/sophiabrandt/nextjs-ecommerce/blob/main/frontend/features/cart/index.tsx): feature · Client cart state, add/remove controls, and cart display. · `frontend/features/cart/index.tsx`
- [Checkout](https://github.com/sophiabrandt/nextjs-ecommerce/blob/main/frontend/features/checkout/index.tsx): feature · Checkout flow and order submission UI. · `frontend/features/checkout/index.tsx`
- [Auth](https://github.com/sophiabrandt/nextjs-ecommerce/blob/main/frontend/features/authentication/index.tsx): feature · Sign-in, sign-up, reset, and sign-out flows. · `frontend/features/authentication/index.tsx`
- [Orders](https://github.com/sophiabrandt/nextjs-ecommerce/blob/main/frontend/features/order/index.tsx): feature · Order history and order detail screens. · `frontend/features/order/index.tsx`
- [Search](https://github.com/sophiabrandt/nextjs-ecommerce/blob/main/frontend/features/search/index.tsx): feature · Debounced catalog search backed by GraphQL. · `frontend/features/search/index.tsx`
- [GraphQL Client](https://github.com/sophiabrandt/nextjs-ecommerce/blob/main/frontend/lib/apollo.ts): data layer · Apollo setup and typed operations for backend communication. · `frontend/lib/apollo.ts`
- [Cart Logic](https://github.com/sophiabrandt/nextjs-ecommerce/blob/main/frontend/lib/cart/index.ts): client state · Local cart calculations and cache updates. · `frontend/lib/cart/index.ts`
- [Theme](https://github.com/sophiabrandt/nextjs-ecommerce/blob/main/frontend/infrastructure/theme/index.ts): ui foundation · Shared styling, fonts, colors, and page scaffolding. · `frontend/infrastructure/theme/index.ts`

### Infra

Containers, reverse proxy, and deployment wiring.

- [Compose](https://github.com/sophiabrandt/nextjs-ecommerce/blob/main/docker-compose.yml): deployment · Containerized frontend/backend deployment and reverse proxy routing. · `docker-compose.yml`
- [Caddy](https://github.com/sophiabrandt/nextjs-ecommerce/tree/main/Caddyfile): reverse proxy · Local HTTPS and domain routing layer. · `Caddyfile`

## Connections

- Keystone → Schema: loads model · Bootstraps the schema and exposes the domain objects.
- Keystone → Access Control: applies rules · Wires authorization into the Keystone app.
- Keystone → Mutations: registers flows · Attaches custom business mutations to the API.
- Schema → Seed Data: backed by · Seed data mirrors the commerce collections and relationships.
- Mutations → Stripe: charges payment · Checkout uses Stripe for payment processing.
- Mutations → Mailgun: sends email · Checkout and account actions can trigger outbound mail.
- Pages → Catalog: renders · Routes compose catalog browsing screens.
- Pages → Product Admin: renders · Routes compose product management screens.
- Pages → Cart: renders · Routes and page shells host cart interactions.
- Pages → Checkout: renders · Routes host checkout flow.
- Pages → Auth: renders · Routes host authentication screens.
- Pages → Orders: renders · Routes host order history and order detail screens.
- Pages → Search: renders · Routes expose catalog search UI.
- Catalog → GraphQL Client: queries · Catalog pages fetch product data through GraphQL.
- Product Admin → GraphQL Client: mutates · Admin product screens create, update, and delete via GraphQL.
- Cart → Cart Logic: updates state · Cart UI relies on local calculations and Apollo cache updates.
- Cart → GraphQL Client: mutates · Add and remove cart actions call the API.
- Checkout → GraphQL Client: creates order · Checkout submits the order mutation through GraphQL.
- Auth → GraphQL Client: auth ops · Authentication flows use typed GraphQL operations.
- Orders → GraphQL Client: queries · Order views load server-side order data through GraphQL.
- Search → GraphQL Client: searches · Search UI runs product lookup queries.
- GraphQL Client → Keystone: API boundary · Apollo client talks to the Keystone GraphQL API.
- Theme → Pages: styles · Shared theme and page chrome support all screens.
- Compose → Keystone: runs · Compose deploys the backend service.
- Compose → Pages: runs · Compose deploys the frontend service.
- Caddy → Compose: routes to · Reverse proxy fronts the containerized services.
