Template developers: Template Structure

Understand how the ecommerce boilerplate under web-builder/apps/templates/ecommerce-boilerplate is organized so you can update UIs without touching core plumbing.

Architecture at a glance

• Location: Clone the template into web-builder/apps/templates/ecommerce-boilerplate.
• App Router-first: Routes live in app/ with a shared layout in app/layout.tsx that wraps pages with ApolloWrapper and ClientLayout.
• Composable sections: Page JSON defines pageItems; React components in app/_components/sections/ render each section type.
• Data-aware: GraphQL operations in graphql/ and helper hooks in lib/ fetch CMS/client-portal data; static JSON in data/ backs local mocks.
• Shared UI: Shadcn UI primitives live in components/ui; reusable widgets (loaders, alerts, forms) live in components/common.
• UI-only scope: Do not add/remove sections or change core wiring. Limit changes to UI (markup/styles/states) inside existing files.

Top-level folders

• app/: All routes and page shells. Notable entries:
  • _components/: Layout chrome (Header, Footer, ClientLayout) and all section components under _components/sections/.
  • page.tsx: Home page that maps pageItems to section components via renderSections.
  • Route folders like about/, contact/, products/, profile/ that render CMS-backed pages with usePage.
• components/: Reusable UI.
  • ui/: Shadcn primitives (buttons, inputs, dialog, sheet, etc.).
  • common/: Shared widgets (loaders, dynamic forms, empty states, template alerts).
• data/: Local config and mock content.
  • configs.json: Template metadata (title, description), appearance tokens, menus, integrations.
  • pages/*.json: Page-level content (index.json, about.json, contact.json, etc.) used in build/local modes.
• graphql/: Domain-specific operations grouped by feature (auth/, clientportal/, cms/, ecommerce/, order/, payment/, products/) plus aggregate queries.ts/mutations.ts.
• lib/: Cross-cutting utilities.
  • apollo-wrapper.tsx and client.ts: Apollo Client setup.
  • Contexts (AuthContext, CartContext) and hooks (useClientPortal, usePage, fetchCms, fetchCpConfig, fetchTours).
  • renderSections.tsx: Helper to render a section list from a component map.
• types/: Shared TypeScript contracts (types/sections.ts defines the base Section shape).
• public/: Static assets (images, icons, favicons).

Page composition flow

• Home (app/page.tsx): Imports pageData from data/pages/index.json, builds a SectionComponentMap, and calls renderSections to output the page. When BUILD_MODE=true, it swaps to app/page.client.tsx to let the builder inject live data via query params.
• Other routes: Pages like about/page.tsx and contact/page.tsx call usePage(pageName) to fetch CMS content with GET_CMS_PAGE, passing the client-portal-id header from route params. Sections are rendered by switching on section.type.
• Layout: app/layout.tsx wraps everything in ApolloWrapper and ClientLayout, ensuring GraphQL and layout chrome are available to every page.

Sections

• Location: app/_components/sections/. Each file exports a React component that accepts { section: Section }.
• Registry (read-only): app/page.tsx maps section.type to components for build/local; lib/usePage.tsx does the same for CMS. Do not add or remove mappings—only adjust UI inside existing section files.
• Behavior: Sections are responsible for their own data needs (e.g., product listings, CMS posts) and should support sensible defaults so mocked JSON can render without live APIs.

Config and data sources

• Template config: data/configs.json stores meta tags, theme tokens, menus, and integration placeholders. Keep IDs and secrets out of this file; use environment variables instead.
• Page mocks: data/pages/*.json supply title, description, and pageItems for local development and build previews. Use these to validate layout and theming without hitting the CMS.
• Environment flags: BUILD_MODE=true toggles builder-driven rendering; absence falls back to local JSON-driven rendering for the home page.

Shared UI and utilities

• UI primitives live in components/ui (generated via components.json shadcn config).
• Cross-template widgets live in components/common (loaders, dynamic forms, empty states).
• Utility helpers like lib/utils.ts handle class merging and small helpers reused across sections.

GraphQL layer

• Operations are organized by domain inside graphql/, with aggregated exports in graphql/queries.ts and graphql/mutations.ts.
• lib/apollo-wrapper.tsx provides the provider setup; lib/client.ts configures the Apollo client instance.
• Hooks and fetchers in lib/ (e.g., usePage, fetchCms, fetchCpConfig) standardize how sections and pages request CMS/client-portal data, keeping rendering logic composable and data-aware.