Cart-Checkout Platform

The legacy monolith owned everything checkout touched: CMS pages, a custom ORM and domain model, orchestration, payments, promotions, downstream sync. Circular dependencies among them made ordinary changes risky. Rebuilding it was the first option we considered, and it was a multi-year bet that would have paid out only at the end, with the business holding still while engineering caught up.

The second option was to buy the commerce backbone and build only the checkout layer on top of it: an API-first composable platform behind a cart-checkout service acting as the single stable entrypoint for every funnel. I owned the technical evaluation comparing Commercetools, BigCommerce, Shopify, and Magento, and argued for Commercetools on Kotlin/JVM fit, data-model flexibility, and partnership terms. It cleared the architecture board on the strength of the migration path and day-two operations.

The tradeoff. A rebuild gives total control and no incremental value until it lands. A composable platform gives value immediately and a permanent dependency on a vendor's roadmap. We took the second and limited the dependency with hexagonal architecture: the vendor sits behind a port, so replacing it is an adapter change.

With one stable entrypoint in front of both systems, funnels could move across one at a time instead of the org committing revenue to a single cutover.

The service owns orchestration and validation, cart and session state in Redis, cart/order operations against Commercetools, and the call to payments-service for tax and payment. Once Commercetools creates the order, its OrderCreated event drives an asynchronous legacy copy that another team owns. Stripe still owns payment processing, and Commercetools is the order system of record as well as the catalog source of truth. Holding that boundary was most of the value.

Everything external enters through a port, which is what let web, mobile, and service-to-service surfaces share one contract across REST, GraphQL, and gRPC adapters while the domain core stayed still.

interface PaymentPort {
    suspend fun quoteTax(cart: Cart, address: Address): TaxQuote
    // One call for all tenders: the only step that moves money.
    suspend fun pay(cart: Cart, tenders: List<Tender>): PaymentResult
}

interface CartStorePort {
    suspend fun load(id: CartId): Cart?
    suspend fun save(cart: Cart): Cart
}

Country, currency, and sales channel were modeled explicitly in the same pass, where the legacy system had inferred them ad hoc. That modeling decision unblocked multi-country and multi-currency growth without another rewrite, and let promotions scale to a per-country model.

Placing an order spans systems that can each fail independently, which makes it the flow where a naive retry costs a customer real money.

A gateway timeout is the hardest case. The charge may have succeeded with the response simply lost, so the caller cannot tell a timeout from a decline, and a blind retry is how a customer gets billed twice. So a payment timeout comes back as a typed error with an unknown outcome, and checkout never retries the charge blind. A charge that succeeds without an order being created is also a typed error, and payments-service reconciles it by charge id.

suspend fun pay(cart: Cart, tenders: List<Tender>): PaymentResult =
    when (val result = payments.pay(cart, tenders)) {
        is Paid     -> result  // record the charge id, then create the order
        is Declined -> result  // terminal: surface it to the customer
        is Unknown  -> throw PaymentOutcomeUnknown(cart.id)  // typed; never retried blind
    }

Order-sync is durable: Commercetools publishes OrderCreated via EventBridge to a Step Functions run per order, so a downstream system being down delays the legacy copy instead of losing it.

Every funnel moved behind a feature-flag / A-B router with a kill switch that forces traffic back to legacy. The router was watched live on four signals: conversion, payment success, p95 latency, and error budget.

We started with the warranties funnel and low-traffic countries, the narrowest surface that still exercised the full path end to end.

The router is also why incident mitigation dropped from hours to minutes. Under the legacy coupling a correctness bug meant a code fix under pressure, and a duplicated price sitting in undocumented legacy code was one such case. With a router in front, the first move is to route traffic away and diagnose afterwards. We later added proactive alerts for invalid products entering the cart, so that class of problem reports itself before a customer does.