Project structure

A copy of a reference site is one repository with the whole project in it: the storefront, the services behind it, the gateway in front of those, and the configuration that puts it all online. Both reference sites share this layout.

• Directoryfrontend/

  • Directorysite/ the Next.js storefront

    • …
• Directorybackend/

  • Directorypurchase/ cart, checkout, customers, orders, payments

    • …
  • Directorydiscover/ catalog, content, price tiers

    • …
  • Directorynotify/ turns notifications into email

    • …
  • Directorytest-support/ test data for the end-to-end suite

    • …
  • Directorygraphql-gateway/ composes the services into one API

    • …
  • Dockerfile.node one image for every service
• Directorypackages/

  • Directorysite-config/ countries, languages, and locales, shared by the site and services

    • …
  • Directorycodeconfig/ shared TypeScript configs

    • …
• Directoryconfiguration/ Terraform for the vendors and the cloud

  • …
• Directorydeploy/ what runs where, per environment

  • …
• Directorydocker/ configs for the local tracing and metrics tools

  • …
• docker-compose.yaml the local services
• .env your local settings, not in git
• AGENTS.md instructions for coding agents
• CLAUDE.md
• package.json
• pnpm-workspace.yaml the Evolve package versions
• Taskfile.yaml

What you change

Folder	What it is	Do you change it?
frontend/site	The storefront: routes in src/app/[locale], components in src/components, translations in src/messages, GraphQL documents next to the code that uses them. The shopping features come from @evolve-storefront/* packages.	Yes, most. Your pages, layout, brand, and copy live here.
backend/purchase	The service for everything from the cart onward. src/module.ts composes the Evolve modules it serves. src/payments/providers holds the payment providers, src/extensions the commercetools API extensions.	Yes, when you add a field, a payment provider, or a business rule.
backend/discover	The service for what a shopper browses: the catalog, CMS content, and volume prices. src/module.ts composes its modules; src/catalog/jobs holds the sync jobs.	Yes, when you change the catalog, the CMS, or search.
backend/notify	Reads notifications off the internal event bus and sends them as email. One template per notification in src/emails.	Yes, for your email templates and sender.
backend/test-support	Simulates back-office actions and cleans up test data for the end-to-end suite. Runs on test environments only.	Rarely.
backend/graphql-gateway	The router config (router.config.yaml) and the task that composes the supergraph from the services’ schemas. The gateway itself is a published image.	Rarely. Its config changes with CORS, headers, or a new service.
packages/site-config	Your countries, languages, and locale routing, with one site config per country in src/configs. The storefront, discover, and notify read it.	Yes, to add a country or a language.
configuration/	Terraform. Sets up commercetools (project settings, stores, product and custom types), the CMS content model, and the cloud resources each service runs on, including its configuration store and secrets.	Yes. You fill in your own accounts, cloud project, and Terraform state.
deploy/	One evolve-deploy config per environment and part: tst.backend.yaml and tst.site.yaml. Each names the version, environment, and smoke tests of every service.	Yes, when you add an environment or a service.
docker/, docker-compose.yaml	The local services: the gateway image, Redis, Mailpit, and the OpenTelemetry collector, Jaeger, and Prometheus. docker-compose.dev.yaml runs the whole stack in containers.	Rarely.
AGENTS.md, CLAUDE.md	Instructions for coding agents: the architecture, the commands, and the conventions. CLAUDE.md loads AGENTS.md. .mcp.json connects agents to the reference site’s tracing.	Yes. Keep them true for your project, because agents act on them.
pnpm-workspace.yaml	The workspace, the registry for the Evolve scopes, and a catalog with the version of every Evolve package.	When you update Evolve.
.github/	CI: install, codegen, check, and test on every pull request, then build and release.	Yes, for your own pipeline and registry access.

The other files at the root configure tooling: Biome and Prettier for formatting, Turborepo for the tasks, Vitest for the tests, and Knip for unused code.

Where B2C and B2B differ

The layout is the same. What sits in it differs:

	B2C reference	B2B reference
CMS	Storyblok: StoryblokModule in discover, configuration/storyblok	Contentful: ContentfulModule in discover, configuration/contentful
Search	commercetools	commercetools, or Algolia with DISCOVER_SEARCH_ENGINE=algolia; index settings in configuration/algolia
Payment providers	Adyen and Mollie	Pay on account, and Mollie
B2B modules in purchase	BusinessUnitModule and OrderApprovalModule, because other modules’ types refer to them	Also QuoteModule, MultipleCartModule, InvoiceModule, and approvals in checkout
Cloud	Google Cloud: Cloud Run, Parameter Manager, and Secret Manager	Azure: Container Apps, App Configuration, and Key Vault; event triggers in each service’s src/functions/azure

Where Evolve’s code lives

The code in your copy is yours. The commerce logic, the GraphQL schema, and the storefront features come from the @evolve-framework/* and @evolve-storefront/* packages, so backend/purchase/src/module.ts composes modules instead of implementing them. You get fixes and new features by updating those packages. You do not merge code from the reference site. task framework-update moves every @evolve-framework/* entry in the catalog to the newest published version.

What’s next

Your project runs. From here, the guides take one change at a time:

Style and brandApply your brand to every Evolve component through design tokens.

Add a feature packageInstall a storefront feature and wire it into a page.

Add your own moduleAdd your own logic to a service.

DeployingPut your project online, and keep releases safe.