Xcoden Resources https://xcoden.com/resources/ Notes on e-commerce architecture, platform engineering and custom commerce systems. en Architecture before code https://xcoden.com/resources/architecture-before-code/ https://xcoden.com/resources/architecture-before-code/ Mon, 21 Sep 2026 00:00:00 +0000 The expensive rebuilds we've seen all started as a schema decision nobody wanted to make early. Here is what we settle before the first migration runs, and why. Every custom commerce build we've taken over had the same story. The first version shipped fast. The second version was where the money went. And when you trace the second version back, it almost never comes from a bad feature. It comes from a data model decision made in week one that the whole system then had to work around.

So before we write application code, we settle three things.

The data model

Not the database schema in the abstract — the specific questions the business will ask of it. A buyback platform needs to know what an offer is: the price quoted, the condition assumed, the date it expires, and what happens when the device that arrives doesn't match. If those are four columns on an orders table, the first dispute rewrites them into four tables.

The test we use: pick the five reports the owner will ask for in month three, and write the query for each one against the proposed model. If a query needs a heuristic ("status was probably X at the time"), the model is missing a fact, and it's cheaper to add it now than to backfill it.

The service boundaries

A commerce system has a handful of things that genuinely operate on their own clock: pricing, inventory, fulfillment, payments. They don't need to be separate services on day one. They do need to be separate modules with a defined interface, so that when the pricing engine needs to change every week and the payout pipeline needs to change never, they aren't tangled in the same controller.

The boundary we draw most often is between what the customer sees and what the operation runs on. Storefront code changes with marketing. Operational logic changes with the business. Coupling them means every promotion is a deployment risk.

What stays off the shelf

Building from scratch is not the goal. The goal is to build the layer the business actually runs on and buy everything else. Payments, email, search, the storefront theme — these are solved problems, and a custom version is a liability, not an asset.

The layer a platform won't do is usually the layer the business depends on. That's the layer we build. Deciding which layer that is, before any code exists, is most of the architecture work.

None of this takes long. A week of conversation and a document that fits on a few pages. The point is that it happens before the first migration, because after that, every decision has a cost attached.

]]>