Skip to main content

Evolve Framework

Work in progress

The Evolve Framework is an ongoing, backwards-compatible refactoring. Not all services have been migrated yet, and APIs may still evolve. Everything described here is functional but should be considered pre-release.

The Evolve Framework extracts shared backend logic from individual services into versioned vendor packages. Instead of every project carrying its own copy of resolvers, dataloaders, mappers, and validation logic, this code now lives in three framework packages that you depend on like any other library.

Why​

Every Evolve backend service used to ship with a complete copy of its GraphQL resolvers, schema definitions, dataloaders, mappers, and test infrastructure. A typical project contained 300+ files and 16,000+ lines of code that was essentially identical across deployments. This created several problems:

  • Upgrade friction: pulling in platform improvements meant manually diffing and merging hundreds of files
  • Multiplied maintenance: a bug fix needed to be applied once per project instead of once
  • Unclear boundaries: it was hard to tell which code was platform baseline and which was project-specific

What changed​

The framework restructures existing code into three layered packages:

  • @evolve-framework/core: base classes, domain service, process manager, cache, and shared infrastructure (vendor-agnostic)
  • @evolve-framework/schemas: all GraphQL type definitions, organized by domain (vendor-agnostic)
  • @evolve-framework/commercetools: resolver implementations, mappers, dataloaders, and composable GraphQL modules for commercetools

The core and schemas layers are vendor-agnostic. The third layer is the implementation package: the concrete resolvers and data access logic for a specific SAAS integration. @evolve-framework/commercetools is the first implementation package. Additional packages for other integrations (Contentful, Storyblok, Algolia, Shopify, and others) will follow the same three-layer pattern, reusing the same core and schemas.

This is the same code, reorganized. There is no new version of Evolve and no rewrite. You can migrate one service at a time, and unmigrated services continue to work as before.

What it means for your project​

  • Painless upgrades: bump a package version instead of merging hundreds of files
  • Less code to own: your services only contain configuration, context wiring, and project-specific extensions
  • Clear boundaries: the framework owns platform logic, your project owns customizations and business rules
info

Migration is incremental. You can migrate one service at a time while the rest of your project stays untouched.

Frequently asked questions​

Does the GraphQL API change? No. The schema exposed by each service is identical before and after migration. Storefronts and other clients are not affected.

Does the framework affect performance? No. The same code runs in the same way. The framework restructures how code is organized and distributed, not how it executes.

What about CMS, payment, and other services? The first five commercetools services (account, catalog, checkout, order, quotes) have been migrated. CMS integrations (Contentful, Storyblok), payment providers, and other services will follow as their own implementation packages.

Can I stay on an older framework version? Yes. Framework packages are versioned. You can pin a specific version and upgrade on your own schedule.

What's next​