How sophiabrandt/nextjs-ecommerce works
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: index.tsx Pages · apollo.ts GraphQL Client · keystone.ts Keystone · index.ts Mutations
Components 20
Backend
Keystone.js commerce API, schema, and business mutations.
- Keystone · Keystone bootstrap and app composition.
backend/keystone.ts - Schema · Core CMS and commerce entities plus relationships.
backend/schemas/index.ts - Access Control · Role-based permissions and environment-driven access rules.
backend/access.ts - Mutations · Custom add-to-cart and checkout operations.
backend/mutations/index.ts - Stripe · Payment integration used during checkout.
backend/lib/stripe.ts - Mailgun · Email delivery integration used during checkout and account flows.
backend/lib/mail.ts - Seed Data · MongoDB dump and collection snapshots for bootstrapping commerce data.
backend/seed-data/db.dump
Frontend
Next.js storefront and admin-facing UI.
- Pages · Next.js route entrypoints for catalog, auth, orders, and product management.
frontend/pages/index.tsx - Catalog · Product browsing, listing, detail, and pagination UI.
frontend/features/products/index.tsx - Product Admin · Create, update, delete, and sell product actions.
frontend/features/product/index.tsx - Cart · Client cart state, add/remove controls, and cart display.
frontend/features/cart/index.tsx - Checkout · Checkout flow and order submission UI.
frontend/features/checkout/index.tsx - Auth · Sign-in, sign-up, reset, and sign-out flows.
frontend/features/authentication/index.tsx - Orders · Order history and order detail screens.
frontend/features/order/index.tsx - Search · Debounced catalog search backed by GraphQL.
frontend/features/search/index.tsx - GraphQL Client · Apollo setup and typed operations for backend communication.
frontend/lib/apollo.ts - Cart Logic · Local cart calculations and cache updates.
frontend/lib/cart/index.ts - Theme · Shared styling, fonts, colors, and page scaffolding.
frontend/infrastructure/theme/index.ts
Connections 26
- 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.