Skip to content
SHC Docs

Frappe is the platform; Medusa is not adopted as infrastructure: owner ruling 2026-08-16

Status: OWNER RULING. This is a decision record of a conversation, not new analysis. Nothing here was re-derived; it is written down so that it stops being re-litigated. The question came around three times before this ruling; that recurrence is the reason this file exists, and it is the reason the record includes the reasoning and not only the verdict.

Date: 2026-08-16. Measured against shc main @ db497738e.

No code changes. No package is deprecated, removed or renamed by this ruling; see §4, which is the half most likely to be misread.


Frappe/ERPNext is the platform for everything. Medusa is NOT adopted as infrastructure.

#rulingscope
F1Frappe/ERPNext is the platform. Business objects, the book of record, and the app substrate are Frappe’s.Everything below.
F2Medusa is not adopted as infrastructure, not for DesiBox, not for the SHC portal, not for the marketplace, not for BitSpur, not for FlyingFoxLabs.All five named explicitly, because the argument arrived under a different name each time it recurred.
F3★ The cart is NOT modelled as a Quotation. A lightweight custom doctype (or Redis) holds the cart; a Sales Order is minted only at checkout.This is the fix that answers the one real objection (§3.2).
F4No Medusa↔ERPNext bridge on our clock. It leaves our backlog and becomes a customer-funded feature.§4.2.
F5apps/standalone/medusa remains a catalogue app we SELL. This ruling governs what we run, not what we ship.§4.1.
F6DesiBox runs on Frappe: cart doctype, ERPNext as the book, payments through the gateway abstraction.§4.3.
F7A revisit trigger is stated, so this is falsifiable rather than dogma.§3.6.

The adjacent payments ruling from the same conversation is recorded separately in 2026-08-16-hyperswitch-as-a-frappe-gateway.md: split for findability, not because it is separable. F6 depends on it.


Not “which is the better e-commerce product”. The recurring question was whether Medusa should be adopted as infrastructure (a second platform we run, operate, upgrade and integrate) alongside the Frappe/ERPNext estate we already run. That framing matters: every time the argument came back it came back as a capability claim, and it was never a capability question.


Frappe is a metadata-driven framework. Everything Medusa does can be modelled in it. The question was never “can ERPNext do this”; it was “what is pre-built versus what would we build”. Any argument that opens by asserting a thing Frappe cannot do has already gone wrong; the honest version of that argument is an inventory of pre-built surface, and that inventory is §3.5.

3.2 ★ The one real structural difference, and its answer

Section titled “3.2 ★ The one real structural difference, and its answer”

There is exactly one structural objection, and it is real:

ERPNext objects are ACCOUNTING DOCUMENTS. A Quotation is numbered by a naming series, is submittable, is cancellable only by amendment, and is wired to the general ledger. That is precisely right for a book of record and precisely wrong for a cart, where you want thousands of disposable, abandoned, never-reconciled objects churning through the table.

The in-repo corroboration of the submittable-document property, written for a different purpose entirely and therefore not special pleading:

“a submitted Sales Order reserves stock and is only reversible by cancel+amend, so an unattended sync that submits turns every storefront mistake into an accounting correction” docs/proposals/2026-08-09-medusa-erpnext.md:420

★ THE FIX IS TO NOT MODEL THE CART AS A QUOTATION.

  • The cart is a lightweight custom doctype (or Redis) with no naming series, no submit workflow, no GL wiring, and no expectation of permanence.
  • A Sales Order is minted only at checkout, when an abandoned object stops being likely and a book entry starts being wanted.

This is recorded in its own subsection, at the top of the reasoning, and in F3, because it is the detail most likely to be forgotten, and forgetting it is what regenerates the entire Medusa argument. With the cart off the accounting-document path, the last structural argument for Medusa is gone.

3.3 The headless-storefront argument is dead by our own evidence

Section titled “3.3 The headless-storefront argument is dead by our own evidence”

The argument that Medusa is needed because it exposes a Store API for a headless frontend is refuted by a thing we already built and already run.

marketplace.selfhostedcloud.org is a Tamagui / One React frontend reading Frappe REST directly:

claimin-repo citation
One + Tamagui + React appapps/marketplace/package.json: "one": "1.16.5", "tamagui": "2.0.0-rc.41", "@multiplatform.one/frappe": "^6.7.0"
Reads Frappe REST directly, client-sidefeatures/marketplace/src/catalog/useMarketplace.ts:134,153,173: /api/resource/App Listing, /api/resource/App Version
SSR / runtime-config seamapps/marketplace/src/app.ts:11-26: MARKETPLACE_API_URL resolved from public config at runtime
Catalogue size it serves90 first-party packages, docs/proposals/2026-08-16-marketplace-screenshots.md:0.1

We built the thing Medusa’s Store API exists for, on Frappe, and it works. An argument for adopting a platform to obtain a capability we have already demonstrated without it is not an argument.

A bridge is not an integration; it is a permanent reconciliation program. Adopting Medusa alongside ERPNext means:

  • two product models,
  • two customer models,
  • two order models,

reconciled forever. The 2026-08-09 proposal (written in favour of the edge, which is what makes the admission load-bearing) titles its own §5:

“The sync contract: the program nobody has written” docs/proposals/2026-08-09-medusa-erpnext.md:358

The cost of adoption is that program, on our clock, in perpetuity.

3.5 What Medusa would actually add, stated fairly, not strawmanned

Section titled “3.5 What Medusa would actually add, stated fairly, not strawmanned”

This ruling is not a claim that Medusa is bad software. It is a claim about fit. What Medusa genuinely brings that Frappe does not ship pre-built:

  1. Cart and checkout primitives, including guest checkout.
  2. A retail promotions engine.
  3. Regions: currency, tax, payment methods and fulfillment options bundled into one first-class object.
  4. Live carrier rates at checkout.
  5. A retail variant matrix (option/value combinatorics as a first-class model).

For a single-SKU box, roughly 15% of that is used. Adopting a platform to obtain the 15% while carrying the reconciliation program of §3.4 is the trade being refused.

3.6 The revisit trigger, stated concretely

Section titled “3.6 The revisit trigger, stated concretely”

So that this is a falsifiable engineering position and not doctrine. Revisit when any of these become true:

  • Thousands of SKUs.
  • Heavy merchandising / faceted search as a core product requirement.
  • Retail-scale traffic where cart-as-accounting-document becomes a load problem, noting that F3 is specifically what defers this one.

At that point, what we would build in Frappe approaches rebuilding Medusa, and the trade flips. Revisit then, with a real catalogue to migrate, which is also the only condition under which the migration is cheap enough to be honest about.


4.1 apps/standalone/medusa is NOT deprecated

Section titled “4.1 apps/standalone/medusa is NOT deprecated”

This ruling is about what WE run, not what we SHIP. apps/standalone/medusa remains a catalogue app we sell to customers, with its socket edge, its plug, its arm job and its guards intact:

apps/standalone/medusa/
app.yaml compose.yaml vars.yaml Dockerfile backup.yaml
erpnext.plug.yaml medusa-erpnext-arm.job.yaml medusa-init.job.yaml
postgres.plug.yaml s3.plug.yaml tests/

Do not deprecate the package. Do not remove the ERPNext edge. A future sweep that reads this ruling as “Medusa is out” and retires the package has misread it.

The Medusa↔ERPNext bridge becomes a customer-funded feature. What is already built stays built and ships with the sellable app: the credential edge, the compiled-in Medusa Subscribers for the push half, and the frappe_medusa provider-side poll for the pull half (apps/standalone/medusa/erpnext.plug.yaml:29-67). What changes is the clock: no further investment on ours, absent a customer paying for it.

docs/proposals/2026-08-09-medusa-erpnext.md carries a dated header pointing here, so that a future reader does not treat its §5 and §7 “owed work” as ours. That proposal’s §5 is now superseded twice over: once by the embodiment actually landing (the sidecar rung was abandoned for fork-carried subscribers plus frappe_medusa), and once by this ruling reassigning who pays for the rest.

  • Cart: a lightweight cart doctype (F3), not a Quotation.
  • Book: ERPNext. Sales Order minted at checkout; invoice, tax and ledger as normal.
  • Payments: through the Frappe payments gateway abstraction, with Hyperswitch entering as one gateway behind it; see 2026-08-16-hyperswitch-as-a-frappe-gateway.md.

  • It does not say Medusa is bad software (§3.5 is the fair account).
  • It does not retire apps/standalone/medusa or any of its files (§4.1).
  • It does not delete the existing bridge code (§4.2); it reassigns the clock.
  • It does not forbid ever adopting Medusa; §3.6 names the conditions.
  • It does not rule on the marketplace’s own commerce design beyond confirming its Frappe backend, which was already ruled in docs/proposals/2026-08-14-marketplace-architecture.md §3–§4.

Verified in-repo at db497738e: the marketplace storefront’s stack and its direct Frappe REST reads (apps/marketplace/package.json, features/marketplace/src/catalog/useMarketplace.ts:134, apps/marketplace/src/app.ts:11-26); the 90-package first-party catalogue count (docs/proposals/2026-08-16-marketplace-screenshots.md §0.1); the submitted-Sales-Order cancel+amend property as recorded (docs/proposals/2026-08-09-medusa-erpnext.md:420); the “program nobody has written” §5 title (same file, :358); the medusa package’s surviving file set (apps/standalone/medusa/); the landed embodiment change from sidecar to compiled-in subscribers plus frappe_medusa (apps/standalone/medusa/erpnext.plug.yaml:29-67, apps/standalone/medusa/vars.yaml:37-44).

unverified: do not assert these without a source: the specific claim that ERPNext’s Quotation in particular is GL-wired (the submittable / naming-series / cancel-by-amendment shape is recorded above for Sales Order; the Quotation specifics are the owner’s statement of the general ERPNext document model and were not re-measured here); the “~15% used for a single-SKU box” figure, which is the owner’s estimate of proportion, not a measurement; the load threshold at which cart-as-accounting-document actually becomes a problem, which §3.6 deliberately leaves as a trigger to observe rather than a number to assert.