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.
1. The ruling
Section titled “1. The ruling”Frappe/ERPNext is the platform for everything. Medusa is NOT adopted as infrastructure.
| # | ruling | scope |
|---|---|---|
| F1 | Frappe/ERPNext is the platform. Business objects, the book of record, and the app substrate are Frappe’s. | Everything below. |
| F2 | Medusa 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). |
| F4 | No Medusa↔ERPNext bridge on our clock. It leaves our backlog and becomes a customer-funded feature. | §4.2. |
| F5 | apps/standalone/medusa remains a catalogue app we SELL. This ruling governs what we run, not what we ship. | §4.1. |
| F6 | DesiBox runs on Frappe: cart doctype, ERPNext as the book, payments through the gateway abstraction. | §4.3. |
| F7 | A 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.
2. What was actually being argued
Section titled “2. What was actually being argued”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.
3. The reasoning, recorded in full
Section titled “3. The reasoning, recorded in full”3.1 There is no capability gap
Section titled “3.1 There is no capability gap”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:
| claim | in-repo citation |
|---|---|
| One + Tamagui + React app | apps/marketplace/package.json: "one": "1.16.5", "tamagui": "2.0.0-rc.41", "@multiplatform.one/frappe": "^6.7.0" |
| Reads Frappe REST directly, client-side | features/marketplace/src/catalog/useMarketplace.ts:134,153,173: /api/resource/App Listing, /api/resource/App Version |
| SSR / runtime-config seam | apps/marketplace/src/app.ts:11-26: MARKETPLACE_API_URL resolved from public config at runtime |
| Catalogue size it serves | 90 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.
3.4 The cost avoided
Section titled “3.4 The cost avoided”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:
- Cart and checkout primitives, including guest checkout.
- A retail promotions engine.
- Regions: currency, tax, payment methods and fulfillment options bundled into one first-class object.
- Live carrier rates at checkout.
- 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. Consequences: record these explicitly
Section titled “4. Consequences: record these explicitly”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.
4.2 The bridge leaves our backlog
Section titled “4.2 The bridge leaves our backlog”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.
4.3 DesiBox runs on Frappe
Section titled “4.3 DesiBox runs on Frappe”- 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.
5. What this ruling does not say
Section titled “5. What this ruling does not say”- It does not say Medusa is bad software (§3.5 is the fair account).
- It does not retire
apps/standalone/medusaor 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.
6. Verified vs unverified
Section titled “6. Verified vs unverified”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.
7. See also
Section titled “7. See also”- Hyperswitch integrates into the Frappe payments abstraction: the adjacent ruling from the same conversation
- The commerce edge: ERPNext serves, Medusa consumes: the design this ruling re-scopes; its §5/§7 owed work is no longer ours
- Marketplace architecture: the Frappe-backed storefront and its commerce plan
- Portal architecture: the registration gate the marketplace depends on