Com­pos­able Com­merce with Medusa: Mod­u­lar­i­ty as Strat­e­gy, Not Buzz­word

"Com­pos­able" sits in al­most every pitch deck, where it usu­al­ly means noth­ing — a la­bel for "mod­ern" meant to jus­ti­fy the next con­tract. With Medusa it is not a mar­ket­ing word but the way the sys­tem is built: a mod­u­lar com­merce core to which you at­tach pay­ment, PIM, ERP, search and CMS over clean APIs.

The dif­fer­ence is not se­man­tic, it is a bud­get ques­tion. Buy com­pos­able as a slide and you end up with a mono­lith wear­ing a REST fa­cade. Un­der­stand the ar­chi­tec­ture and you buy swap­pa­bil­i­ty — the abil­i­ty to re­place a sin­gle build­ing block with­out re­plat­form­ing the whole sys­tem. That is the strate­gic val­ue, and that is where com­pos­able com­merce with Medusa turns out to be ei­ther an in­vest­ment or an ex­pen­sive de­tour.

Medusa is built in four lay­ers: API routes on Ex­press, work­flows be­low them, mod­ules be­low those, and the Post­greSQL data store at the bot­tom. This sep­a­ra­tion is not cos­met­ic. It is the rea­son com­merce and in­fra­struc­ture build­ing blocks can be swapped in­de­pen­dent­ly — "you can re­place any of the third-par­ty ser­vices … to build your pre­ferred com­merce ecosys­tem", as the ar­chi­tec­ture doc­u­men­ta­tion puts it.

A mod­ule in Medusa is "a reusable pack­age of func­tion­al­i­ties re­lat­ed to a sin­gle do­main or in­te­gra­tion". The de­ci­sive prop­er­ty is iso­la­tion: one mod­ule does not reach di­rect­ly into an­oth­er's data mod­els. That sounds like a con­straint, but it is the core of mod­u­lar­i­ty — no build­ing block can qui­et­ly cou­ple it­self to an­oth­er, which is ex­act­ly why each one can be re­placed or re­moved. This iso­la­tion is the tech­ni­cal pre­con­di­tion for "swap­pable" be­ing more than a line in the con­tract.

The mod­ules are joined through Mod­ule Links. In­stead of drag­ging for­eign-key con­straints across the data­base, Medusa gen­er­ates an au­to­mat­ic link ta­ble that stores only IDs — no hard cou­pling be­tween do­mains. Above them sit the work­flows: se­quences of steps with built-in durable ex­e­cu­tion and per-step roll­back. When an or­der touch­es an ERP sys­tem, a pay­ment provider and a CMS, and the third step fails, the work­flow com­pen­sates the first two back clean­ly. That is the un­spec­tac­u­lar but op­er­a­tional­ly de­ci­sive an­swer to how you keep data con­sis­tent across sys­tem bound­aries.

The sell­ing point of com­pos­abil­i­ty is rarely "we can build any­thing" — you can do that with a mono­lith and enough tech­ni­cal debt too. The point is that you can undo a bad de­ci­sion with­out tear­ing down the whole house.

Con­crete­ly: Medusa ships rough­ly two dozen com­merce mod­ules out of the box — from cart, or­der, pay­ment and pric­ing through in­ven­to­ry and ful­fil­ment to pro­mo­tion and tax. Along­side them sit swap­pable in­te­gra­tions for pay­ment (Stripe, Pay­Pal), search (Al­go­lia, Meilisearch), and CMS and ERP as their own mod­ules. If your search provider stops con­vinc­ing you in two years, you swap the search mod­ule — not the plat­form. That is best-of-breed in prac­tice: the best tool per do­main, joined over a doc­u­ment­ed com­merce API, in­stead of an all-in-one suite whose weak­est fea­ture you car­ry be­cause it hap­pens to come bun­dled.

This is also where ERP PIM in­te­gra­tion shifts from an in­te­gra­tion project to an ar­chi­tec­tur­al de­ci­sion. A PIM as its own mod­ule, an ERP adapter as its own mod­ule, joined over Mod­ule Links and work­flows — struc­tural­ly the same pat­tern as the in­ter­nal cart-or­der link, only with ex­ter­nal sys­tems. For de­ci­sion-mak­ers who have to con­nect lega­cy es­tates, that is pre­cise­ly the in­ter­est­ing part: Medusa works as an in­te­gra­tion lay­er that en­cap­su­lates old sys­tems rather than re­plac­ing them.

Here the ar­chi­tec­ture be­comes con­crete­ly testable. The Medusa core con­tains no com­pa­ny, quote or ap­proval mod­ule — the B2B base log­ic is de­lib­er­ate­ly not part of the core. What ex­ists sits in the B2B starter: com­pa­ny and em­ploy­ee man­age­ment, per-em­ploy­ee spend­ing lim­its with con­fig­urable re­set fre­quen­cies, sim­ple com­pa­ny-lev­el ap­proval work­flows, and quote man­age­ment with ne­go­ti­a­tion.

And now the point that car­ries the the­sis: these fea­tures are im­ple­ment­ed in the starter as cus­tom mod­ules (com­pa­ny, quote, ap­proval) — not drawn from the core, not de­liv­ered as a SaaS fea­ture flag. The B2B starter de­scribes it­self as "de­signed to be cus­tomized and ex­tend­ed". It is boil­er­plate to fork and main­tain your­self, not a prod­uct fea­ture Medusa keeps up to date. That dis­tinc­tion is not pedantry but a make-or-buy ques­tion with a di­rect TCO con­se­quence: you take on main­te­nance and fur­ther de­vel­op­ment of this code.

The real proof of the com­pos­abil­i­ty the­sis, though, is *how* these mod­ules are built: as stand­alone do­mains hung onto cart and or­der over Mod­ule Links. A gen­uine pro­cure­ment lay­er — with pun­chout cat­a­logues, cXML and OCI, cost cen­tres, mul­ti-stage ap­proval chains and net-terms in­voic­ing — is demon­stra­bly miss­ing from the starter and has to be built. But it hooks into the same struc­ture: as an­oth­er mod­ule, joined over the same mech­a­nisms. Noth­ing in the ar­chi­tec­ture has to be bro­ken open for it. Any­one who wants to know what the starter de­liv­ers and what en­ter­prise pro­cure­ment re­al­ly de­mands will find the hon­est bound­ary in our piece on why Medusa ships no turnkey pro­cure­ment. And any­one look­ing for the ba­sics of why Medusa is built this way at all should start with the ques­tion of what Medusa.js ac­tu­al­ly is.

MACH stands for Mi­croser­vices-based, API-first, Cloud-na­tive and Head­less; the MACH Al­liance was found­ed in June 2020 and now ex­tends the acronym with the lay­er "Open, Com­pos­able, Con­nect­ed". Medusa fol­lows these prin­ci­ples in its own struc­ture: API-first over a doc­u­ment­ed in­ter­face, swap­pable com­merce and in­fra­struc­ture mod­ules, and the ex­plic­it in­vi­ta­tion to re­place third par­ties. The MACH ar­chi­tec­ture is there­fore not a la­bel you stick on but a build de­ci­sion you can read off the mod­ule iso­la­tion.

This is where a dose of re­al­ism is due. The MACH Al­liance is an ad­vo­ca­cy body and, nat­u­ral­ly, names the up­sides of com­pos­abil­i­ty. The oth­er side — high­er in­te­gra­tion, gov­er­nance and op­er­at­ing com­plex­i­ty, no out-of-the-box suite — does not ap­pear there. Judge an ar­chi­tec­ture sole­ly from the mar­ket­ing of its ad­vo­cates and you buy half the truth. Com­pos­abil­i­ty is a tool with clear costs, not a law of na­ture dressed up as progress.

Com­pos­able comes with an in­voice, and it is not print­ed in the pitch deck. More mod­ules means more in­te­gra­tion work, more mov­ing parts, more op­er­a­tions than an all-in-one plat­form. Medusa's pro­duc­tion stack re­quires Post­greSQL and Re­dis, has to run in two modes (serv­er for API/ad­min, work­er for back­ground jobs), needs at least 2 GB of RAM and Node 20 ex­per­tise on the team — plus your own up­time, scal­ing and se­cu­ri­ty patch­ing.

For a sim­ple, stan­dard­ised B2C cat­a­logue that is mas­sive­ly over-pro­vi­sioned. As of mid-2026 and de­pend­ing on scope, a clean first im­ple­men­ta­tion of a self-host­ed stack tends to land in the low to mid five fig­ures, with on­go­ing op­er­a­tions run­ning to a few hours a month — an es­ti­mate to ver­i­fy against your own case, not a quote. Mon­ey well spent if you in­te­grate sev­er­al best-of-breed sys­tems and want to swap build­ing blocks in­de­pen­dent­ly. Mon­ey wast­ed if a man­aged shop meets the same re­quire­ment at a frac­tion of the op­er­at­ing ef­fort. Mod­u­lar­i­ty only pays off once you ac­tu­al­ly use it — not be­cause it sounds mod­ern.

The un­com­fort­able point: com­pos­abil­i­ty reg­u­lar­ly flips into its op­po­site. Every build­ing block ac­quires its own ven­dor, its own con­tract, its own op­er­a­tions, its own SLA and its own con­tact who, when things break, points at the oth­ers. "Best-of-breed" turns into a zoo of in­ter­faces where no one owns the over­all be­hav­iour any more.

With­out clear gov­er­nance you get an in­te­gra­tion mon­ster that costs more than the mono­lith it was meant to re­place — only with more in­voic­es and more ven­dor risk. I have seen se­tups where five "best" in­di­vid­ual sys­tems to­geth­er worked worse than one mediocre suite, be­cause the in­te­gra­tion lay­er it­self be­came an un­main­tained lega­cy sys­tem. Com­pos­abil­i­ty with­out an op­er­at­ing mod­el is not progress, it is dis­trib­uted tech­ni­cal debt.

The line does not run along the tech­nol­o­gy but along the or­gan­i­sa­tion. Any­one who has not got data mod­el­ling across sys­tem bound­aries un­der con­trol — where prod­uct data is au­thor­i­ta­tive­ly main­tained, say, and how it stays in sync with the shop — will pro­duce the same in­con­sis­ten­cies with mod­ules as with a mono­lith, only hard­er to trace.

Treat "com­pos­able" not as a goal but as a means. The right ques­tion is nev­er "are we com­pos­able enough" but "which spe­cif­ic build­ing block must we be able to re­place in three years with­out re­plat­form­ing". If you can an­swer that, Medusa with its mod­ule ar­chi­tec­ture is a pre­cise tool — and a pro­cure­ment lay­er, a new PIM or an ERP switch stay a mod­ule ques­tion, not a re­plat­form­ing ques­tion.

If you can­not an­swer it, every ad­di­tion­al mod­ule buys you op­tion­al­i­ty you nev­er re­deem but op­er­ate every month. Then the mono­lith is the more hon­est choice. The de­ci­sion for or against com­pos­abil­i­ty is not a tech­nol­o­gy pref­er­ence but a bet on your own rate of change — and you should size that up sober­ly, be­fore a ven­dor sizes it up for you. Any­one want­i­ng to go deep­er into Medusa's role across the whole com­merce stack will find the overview on our Medusa top­ic page.