Backend development

Evolve’s backend is a set of microservices that each own a specific domain: accounts, catalog, checkout, orders, content, payments, and more. These services are composed into a single API through GraphQL Federation.

Each service runs as a standalone process with its own GraphQL subgraph schema, REST endpoints, and infrastructure configuration. In production they run as containers (or serverless functions), while in development the monolith runner starts all services in a single process for convenience.

Service structure

Every service follows the same layout:

• Directorybackend/services/[service-name]/

  • Directorysrc/

    • config.ts Environment variable parsing
    • module.ts Framework module composition
    • server.ts DomainService creation and startup
    • context.ts GraphQL context factory
    • index.ts Entry point (starts the server)
    • Directorytesting/ Test mocks and fixtures

      • …
  • schema.generated.graphql Federation subgraph schema
  • codegen.ts GraphQL code generation config
  • build.ts Build script
  • run.ts Dev server entry point
  • Directoryterraform/ Infrastructure per cloud provider

    • …

The core files (config.ts, module.ts, server.ts, index.ts) follow a consistent pattern across all services (see backend/services/quotes-commercetools for a canonical example):

• config.ts: a config class (e.g. extending CommercetoolsConfig) that parses environment variables
• module.ts: a createModule() factory that composes framework modules into a CompositeModule
• server.ts: calls createDomainService() from @evolve-framework/core to combine the module’s GraphQL subgraph (via GraphQL Yoga) and HTTP endpoints into a single server
• index.ts: the entry point that starts the server
• context.ts: builds the per-request GraphQL context with store context, client context, DataLoaders, and authentication

GraphQL modules

Services organize their GraphQL resolvers and type definitions into modules using the framework’s AbstractModule base class. Modules are composed together with CompositeModule:

import { QuoteModule } from "@evolve-framework/commercetools";
import { CompositeModule } from "@evolve-framework/core";

export const createModule = (): CompositeModule => {
  return new CompositeModule([new QuoteModule()]);
};

The framework provides default modules for common domains (customer, cart, catalog, checkout, order, payment, and more). Your project can use these as-is, override individual resolvers, or add entirely new modules. See the framework customization docs for details.

Shared infrastructure

Several patterns are shared across all services through the framework packages:

• Client factory: creates and caches commercetools API clients with retry logic, timeouts, and authentication middleware
• Token management: handles OAuth flows for anonymous sessions, customer tokens, and API client credentials through the federated token system
• DataLoaders: request-scoped batch loaders for efficient commercetools queries (products, categories, carts, orders, etc.) with optional Redis-backed caching
• Store context: extracts store key, locale, and currency from request headers and makes them available throughout the request lifecycle
• Cache: Redis-backed caching (with in-memory fallback) via @evolve-framework/core/cache, used for client context, business logic, and DataLoader results
• Process management: graceful startup and shutdown handling through the ProcessManager class

REST endpoints

In addition to their GraphQL subgraph, services can expose REST endpoints through Fastify. See REST endpoints & webhooks for the full architectural overview. Common uses include:

• Token endpoints: anonymous token creation, session management
• Webhooks: payment provider callbacks, CMS webhooks
• API extensions: commercetools API extension handlers
• Domain-specific routes: payment flows, feed generation

Infrastructure

Each service includes a terraform/ directory with per-cloud provider configurations (AWS, Azure, GCP). This covers container definitions, environment variables, IAM roles, and any service- specific infrastructure. The Terraform code is deployed through MACH Composer or directly through CI/CD pipelines.

Available services

Evolve ships with the following services:

Service	Domain
account-commercetools	Customer accounts, authentication, sessions
authoring (upcoming)	Editor backend for the AI-driven authoring layer
catalog-commercetools	Product catalog, search sync, sitemaps
chat	AI shopping-assistant backend (uses mcp-customer tools)
checkout-commercetools	Cart operations, order creation, payment routing
cms-contentful	Contentful content integration
cms-storyblok	Storyblok content integration with live editing
email-smtp	Transactional email with React Email
event-router	Cloud event routing topology (Terraform-only)
feed-products	Product feed generation
graphql-gateway	Federation gateway (Hive Router)
mcp-customer	MCP server exposing customer-facing commerce tools
monitoring	Health checks and observability
monolith	Dev-only runner that starts all services in one process
order-commercetools	Order retrieval and management
payment-commercetools-adyen	Adyen payments
payment-commercetools-buckaroo	Buckaroo payments
payment-commercetools-invoice	Invoice payments
payment-commercetools-mollie	Mollie payments
payment-commercetools-paynl	PayNL payments
payment-commercetools-stripe	Stripe payments
pim-bluestone-commercetools	PIM sync from Bluestone PIM to commercetools
quotes-commercetools	B2B quote management

When creating a new project, remove the services you don’t need and keep only what’s relevant for your commerce and content setup.

Backend testingTesting patterns for backend services: Vitest, Fishery factories, MSW, and CommercetoolsMock.

CheckoutHow the checkout domain handles cart operations, order creation, and payment routing.

Content managementHow Evolve integrates with content management systems to deliver pages, navigation, and site layout through the GraphQL schema.