E-commerce study — one document

Young, 2026-10-13: "consolidate into a single document SolOSV3 Docs 01-research: saleor-study.md, saleor-commercial-review.md. Review and study nextjs-commerce and Medusa."

Note on path: the tree holds Docs/SolOSV3/01-research/ (this file). There is no SolOSV3/Docs/ directory — consolidated here, where both source files already live. Both originals are preserved with pointers; nothing was deleted.

PART A — Saleor, consolidated (technical + commercial)

A1. What it is

Saleor Core: headless, API-only, GraphQL-native commerce backend (Python/Django, 23k stars, since 2013). Three deployables: Core API + Storefront (Next.js) + Dashboard (React SPA). Extension only via webhooks, attributes, metadata, apps, subscriptions, dashboard iframes — never by patching core.

Functions: catalog/PIM, checkout state machine, orders/fulfilment/returns + click-and-collect, payment gateway apps, promotions/vouchers, native multichannel (per-channel pricing, currencies, stock, assortments), marketplace recipe, digital goods, staff/customer roles.

A2. Storefront + dashboard

Storefront (saleor/storefront, "Paper"): Next.js App Router RSC + TypeScript + Tailwind. Open Checkout v2, server-first cart, URL-driven steps, no browser tokens (session resolved server-side — the same boundary as our E5). International by default (/{locale}/{channel}/…, per-locale catalog cache, hreflang).

Dashboard (saleor/saleor-dashboard): GraphQL React SPA admin; extending it means shipping an app with iframe views, not forking the admin. Needs Node 24 + pnpm + a running Core.

A3. Commercial (Mira's half, carried verbatim in substance)

Mira's verdict: study-only until a shop is a named goal. Self-hosted is 16–32× cheaper than Cloud; the license is not a blocker for running a shop.

A4. What it means for us

Headless/API-only is the correct shape for anything a fleet drives; the BFF pattern is directly reusable. Do not adopt the platform to "have e-commerce" — a capability with no caller is the defect we keep finding.

PART B — Next.js Commerce + Saleor templates (new)

B1. saleor/nextjs-commerce — archived, do not use

Status: ARCHIVED, fork of Vercel's template. Saleor's own README redirects to their official Next.js Starter for production work. MIT licensed. What it was: Next.js 13 App Router + RSC + Server Actions + Edge runtime + Tailwind, checkout/payments through Saleor, SALEOR_INSTANCE_URL pointing at a Saleor GraphQL endpoint, webhooks for on-demand ISR. Its value today is comparative (providers fork lib/… and swap implementations) — not a base to build on.

B2. The live template: Paper on Vercel

vercel.com/templates/next.js/nextjs-saleor-commerce serves the same Paper storefront as saleor/storefront (one-click Vercel deploy). No divergence to track: template = repo. If we ever stand up a Saleor shop, this is the deploy path, not the archived fork.

B3. saleor-app-template — how extensions are built

Bare-bones Next.js boilerplate for Saleor Apps: webhook endpoints + dashboard config UI via the app manifest (/api/manifest, installed from the dashboard or GQL). License "Other" — read before forking. This is the extension unit of the whole ecosystem: custom logic = an app, and the App SDK/APL docs Young linked are its developer surface.

PART C — Medusa (new)

C1. What it is

Medusa (medusajs/medusa, 36.7k stars — larger than Saleor): Node/TypeScript commerce platform + framework. Core commerce modules on npm; explicitly positioned "for agents and developers." Covers B2B/DTC, marketplaces, distributors, PoS, services — anywhere foundational commerce primitives are needed without reinventing them.

License: open-core. Core is MIT; RBAC-based Enterprise Edition requires a commercial agreement (ENTERPRISE-LICENSE.md). Sharper split than Saleor's: Saleor gates hosting/convenience (Cloud) while the code stays BSD; Medusa gates features (RBAC enterprise materials) while the framework stays MIT. Which gate bites depends on what we'd need — RBAC is exactly the kind of feature a fleet-operated shop ends up wanting.

C2. POS starter — the surface Saleor doesn't show

Agilo/medusa-pos-starter (MIT, Expo React Native): mobile PoS hitting the Medusa Admin REST API — admin login, setup wizard (regions/channels/stock locations), barcode scan via camera, draft orders + discounts + customers, in-app checkout, order history. This is headless commerce extended into physical retail with no backend changes — the strongest concrete demo of the API-only bet either platform makes. Neither Saleor repo in this study shows an equivalent first-party PoS surface.

C3. Saleor vs Medusa — the honest comparison

No verdict between them in this file — that is a commercial + architectural decision needing Mira's TCO half for Medusa (not yet written) and a named shop goal (not yet given). Both stay study-only per the same rule as Saleor.

Cross-links

• Saleor technical (original, preserved): saleor-study.md
• Saleor commercial (original, preserved): saleor-commercial-review.md
• Mira's follow-up (if she writes it): Medusa TCO + license check
• Board: t_32d68ff2 (Mira's Saleor card, done)