What MedusaJS Custom Engines Taught Me

Most headless commerce platforms sell you a comforting illusion during the first week of development. As long as your business only sells physical t-shirts with simple size variants and standard shipping rates, everything works out of the box. The real architectural test begins the moment you try to bend that same engine to power a multi-vertical ecosystem where instant digital ticketing, dynamic tour scheduling, point-of-sale retail inventory, and on-demand driver dispatch all share a unified checkout pipeline. When I started building custom domain engines on top of MedusaJS, I quickly realized that treating a commerce framework like a traditional monolithic CRUD application is the fastest way to accumulate crippling technical debt.

Why Extending Core Tables Directly Is a Trap

My earliest instinct when adding custom business logic was to reach directly into the existing product and order tables and bolt on custom columns. That approach feels productive for about 48 hours until you try to upgrade core framework packages or separate your booking logic from physical merchandise fulfillment. MedusaJS forced me to unlearn that habit through its strict modular architecture, where every custom domain lives as an isolated service with its own database entities and internal container scope.

1import { MedusaService } from "@medusajs/framework/utils"
2import { DispatchAllocation } from "./models/dispatch-allocation"
3
4class DispatchEngineService extends MedusaService({
5  DispatchAllocation,
6}) {
7  async lockDriverSlot(driverId: string, bookingWindow: Date): Promise<string> {
8    const existingLocks = await this.listDispatchAllocations({
9      driver_id: driverId,
10      scheduled_at: bookingWindow,
11      status: "locked",
12    })
13
14    if (existingLocks.length > 0) {
15      throw new Error("Driver slot is already locked for this time window")
16    }
17
18    const allocation = await this.createDispatchAllocations({
19      driver_id: driverId,
20      scheduled_at: bookingWindow,
21      status: "locked",
22    })
23
24    return allocation.id
25  }
26
27  async releaseDriverSlot(allocationId: string): Promise<void> {
28    await this.updateDispatchAllocations({
29      id: allocationId,
30      status: "released",
31    })
32  }
33}
34
35export default DispatchEngineService

Encapsulating domain rules inside a dedicated module service changes how you reason about system boundaries. Notice how the dispatch engine above knows nothing about shopping carts, payment gateways, or customer profiles. It only cares about locking and releasing time slots atomically. By refusing to let foreign keys bleed across module boundaries, you gain the freedom to extract that engine into a standalone microservice later or replicate its database tables independently when read traffic spikes.

Mastering Distributed Rollbacks Through Workflow Steps

Isolating modules solves the data耦合 problem, but it immediately introduces a harder challenge around transactional consistency. When a customer books a tour package and pays via a digital wallet or QRIS gateway, your backend has to reserve inventory, lock a driver slot in your custom dispatch engine, capture the payment, and emit an analytics event. If the payment gateway times out on the third step, a naive service layer leaves orphaned inventory locks sitting in your database forever.

Working with the MedusaJS workflow engine taught me to stop relying on giant database transactions and start designing every business mutation with an explicit undo button. Every step in a workflow pairs its forward execution logic with a compensating function that knows exactly how to reverse the state if a downstream step fails.

1import { createStep, StepResponse, createWorkflow, WorkflowResponse } from "@medusajs/framework/workflows-sdk"
2import { DISPATCH_MODULE } from "../modules/dispatch"
3import DispatchEngineService from "../modules/dispatch/service"
4
5const reserveDispatchStep = createStep(
6  "reserve-dispatch-step",
7  async (input: { driverId: string; window: Date }, { container }) => {
8    const dispatchService: DispatchEngineService = container.resolve(DISPATCH_MODULE)
9    const allocationId = await dispatchService.lockDriverSlot(input.driverId, input.window)
10
11    return new StepResponse({ allocationId }, allocationId)
12  },
13  async (allocationId: string | undefined, { container }) => {
14    if (!allocationId) return
15    const dispatchService: DispatchEngineService = container.resolve(DISPATCH_MODULE)
16    await dispatchService.releaseDriverSlot(allocationId)
17  }
18)
19
20export const completeBookingWorkflow = createWorkflow(
21  "complete-booking-workflow",
22  (input: { driverId: string; window: Date }) => {
23    const reservation = reserveDispatchStep(input)
24    return new WorkflowResponse(reservation)
25  }
26)

Writing that second compensation function inside createStep fundamentally rewires your engineering discipline. Instead of hoping that network calls never fail, you assume failure is inevitable and codify the exact cleanup procedure right next to the mutation. When a downstream payment verification throws an exception two seconds later, the workflow engine automatically walks backward through the execution graph and invokes releaseDriverSlot with the exact allocation identifier returned earlier.

Decoupling Side Effects From Core Transaction Paths

Another harsh lesson came from watching response latencies creep upward whenever third-party integrations were placed inside synchronous request cycles. Early on, it is tempting to trigger WhatsApp notifications, generate PDF invoices, or push real-time revenue metrics into an analytical store right inside your checkout workflow. Even if those steps succeed ninety-nine percent of the time, a single sluggish webhook from an external provider will stall the entire user checkout experience.

The cleanest architectural pattern I adopted from MedusaJS is keeping custom engine workflows strictly focused on state mutations while delegating every side effect to asynchronous event subscribers. Once the booking workflow commits its state, it emits a lightweight domain event onto the internal event bus. Dedicated background workers or Kafka producers can then pick up that payload, stream it into ClickHouse for real-time dashboard analytics, or dispatch courier notifications without adding a single millisecond to the customer-facing API response.

How This Pattern Reshaped My Own Core Architectures

Building production systems on top of MedusaJS custom engines eventually influenced how I architect software even when I am not using MedusaJS at all. When I started designing custom core engines for my own travel and multi-service platforms, I carried over the exact same separation between isolated domain modules, read-only cross-module links, and compensating workflow steps. Once you experience the peace of mind that comes from self-healing transactions and zero cross-module spaghetti code, going back to traditional controller-service-repository monoliths feels like stepping backward a decade. Framework APIs will always evolve, but learning to treat every business capability as an independent, composable engine with built-in rollback guarantees is an architectural lesson that pays dividends across your entire career.