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:

backend/services/[service-name]/
├── src/
│   ├── init.ts            # Environment and client initialization
│   ├── server.ts          # DomainService creation and startup
│   ├── context.ts         # GraphQL context factory
│   ├── config.ts          # Environment variable parsing
│   ├── graphql/           # Resolvers and mutations
│   ├── rest/              # REST route handlers
│   ├── generated/         # Generated types and schema
│   └── testing/           # Test mocks and fixtures
├── schema.graphql         # Federation subgraph schema
├── codegen.ts             # GraphQL code generation config
├── build.ts               # Build script
├── run.ts                 # Dev server entry point
└── terraform/             # Infrastructure per cloud provider

The three core files (init.ts, server.ts, context.ts) follow a consistent pattern across all services:

• init.ts: loads configuration, initializes the cache, configures the commercetools client factory and token manager
• server.ts: creates a DomainService that combines GraphQL (via GraphQL Yoga) and HTTP (via Fastify) into a single 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 AbstractGraphQLModule base class. Modules are composed together with GraphQLCompositeModule:

const module = new GraphQLCompositeModule([
  new CustomerGraphQLModule(),
  new SessionGraphQLModule(),
]);

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
catalog-commercetools	Product catalog, search sync, sitemaps
checkout-commercetools	Cart operations, order creation, payment routing
order-commercetools	Order retrieval and management
quotes-commercetools	B2B quote management
cms-contentful	Contentful content integration
cms-storyblok	Storyblok content integration with live editing
payment-commercetools-stripe	Stripe payments
payment-commercetools-adyen	Adyen payments
payment-commercetools-buckaroo	Buckaroo payments
payment-commercetools-paynl	PayNL payments
payment-commercetools-invoice	Invoice payments
email-smtp	Transactional email with React Email
feed-products	Product feed generation
monitoring	Health checks and observability

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

📄️ Checkout

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

📄️ Backend testing

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

🗃️ Content management

1 item