How a request runs
Mercur keeps Medusa’s layers as they are, so Medusa’s architecture guide applies to every Mercur project. A request passes through four layers:- API route: an HTTP handler under
/admin,/vendor, or/store. Middleware authenticates the caller first; on/vendorit also resolves the caller’s seller before any handler runs, including handlers you add. - Workflow: the handler runs a workflow for every write. Each step has a compensation function, so when a step fails, the steps before it roll back.
- Module: workflow steps call module services. A module owns its tables and never imports another module.
- Data: every module stores its tables in the same PostgreSQL database. Links record relationships between modules without foreign keys between their tables.
completeCartWithSplitOrdersWorkflow groups the cart’s items by seller, creates one order per seller under an order group, and refreshes each order’s commission lines. If a step fails, the workflow rolls back and the cart stays open.
Backend packages
The backend is one Medusa server. Mercur adds a plugin and providers to it; it doesn’t replace or fork the framework.Medusa
Medusa is the commerce engine: products, pricing, carts, orders, payments, fulfillment, promotions, and the module, workflow, and event system the rest of Mercur is built on. Anything in Medusa’s documentation works in a Mercur project.@mercurjs/core
The marketplace plugin. It contains the marketplace modules (sellers and members, offers, commissions, payouts, product attributes, the product change pipeline, reviews, and custom fields), the workflows that connect them to commerce, the /vendor API, and the marketplace routes on /admin and /store. You register it by wrapping your Medusa config with withMercur():
medusa-config.ts
@mercurjs/stripe-connector-plugin
A Stripe payment provider and a payout provider built on Stripe Connect. It creates a connected account per seller, returns onboarding links, transfers each seller’s share, and maps Stripe webhooks to payout account statuses. It also brings the payout operations core leaves out: the scheduled capture, payout, reversal, and settlement jobs, settlements and bank payouts, operator adjustments, and the Integrations → Stripe screens.
Source · Stripe Connect guide
PostgreSQL and Redis
PostgreSQL is the only supported database. The startermedusa-config.ts uses Redis for the event bus, the workflow engine, locking, and the cache; Medusa also ships in-memory versions of these modules for development.
Providers
Mercur doesn’t choose your payment gateway, carrier, email service, or search engine. Each integration sits behind a provider interface, and you pick the implementation inmedusa-config.ts:
Swapping a provider doesn’t touch marketplace code. A payout provider implements
IPayoutProvider from @mercurjs/types, which has four methods: createPayoutAccount, createOnboarding, createPayout, and getWebhookActionAndData. You register it on the payout module:
medusa-config.ts
Panel packages
The admin panel and the vendor panel are React 18 apps built with Vite and Medusa UI. They ship as packages that your host apps render, so you upgrade them by bumping a version.@mercurjs/admin and @mercurjs/vendor
@mercurjs/admin is the operator panel and @mercurjs/vendor is the seller panel. A host app renders the panel and adds its stylesheet:
apps/admin/src/main.tsx
admin-ui and vendor-ui modules of @mercurjs/core.
Admin source · Vendor source
@mercurjs/dashboard-sdk
A Vite plugin that turns files in a host app into panel extensions. Pages come from src/routes/**/page.tsx, widgets from src/widgets/, custom-field UI from src/custom-fields/, and sidebar changes from src/_navigation.ts:
vite.config.ts
extension-targets.d.ts with every zone id and model name, so a widget that targets a missing zone fails type-checking.
Source · Panel extensions
@mercurjs/dashboard-shared
The UI primitives both panels are built from: forms, tabbed create flows, data tables, route modals and drawers, and query-key helpers. Use them in your own pages so they match the built-in screens.
Source
Client packages
Every Mercur client, the panels included, talks to the backend over HTTP through the same typed client.@mercurjs/client
A typed fetch wrapper. mercurjs codegen reads your backend’s API routes, including the ones you add, and writes a Routes type. The client turns property access on that type into requests:
src/lib/client.ts
.query() sends a GET, .mutate() sends a POST, and .delete() sends a DELETE. Because the panels use this client too, a backend change that breaks a caller fails at tsc instead of at runtime.
Source · Add a typed API route
@mercurjs/types
Mercur’s entity and HTTP types (sellers, offers, commissions, payouts, order groups), plus re-exports of Medusa’s types. A storefront can type its responses with this package without importing the backend.
Source
Tooling packages
These packages run on your machine or in CI. None of them run in production.@mercurjs/cli
The mercurjs command. It installs and updates blocks (add, diff, search, view), generates route types (codegen), and builds plugins and registries:
create-mercur-app
Creates a new project: the API, the admin host app, and the vendor host app in one Turborepo workspace.
Blocks
Blocks are features that the CLI copies into your project as source code: modules, workflows, API routes, and panel extensions. Once installed, a block is your code.mercurjs diff shows what changed upstream, and you decide what to take. The official registry includes wishlist, algolia, meilisearch, vendor-chat, and requests, and you can host your own registry.
Blocks · Registry
@mercurjs/docs
These docs, bundled into node_modules with an llms.txt index. Coding agents read them to get the contracts for the Mercur version you installed.
Build with AI
Where your code goes
Your code lives next to Mercur’s in the same project, and nothing requires a fork. Each kind of change has one place to go:Design decisions
These decisions explain the shape of the packages above:- A Mercur project is a Medusa project: Mercur adds modules, routes, and workflows to Medusa and changes none of its layers
- Modules don’t import each other: links connect them, so you can replace Mercur’s commission module or remove a module you don’t use
- Integrations are providers: payments, payouts, fulfillment, notifications, files, and search each sit behind an interface you implement or swap
- Seller scoping runs before handlers:
/vendormiddleware resolves the seller before your code runs - Types come from the backend: codegen reads your routes, the client reads the generated types, and the panels use the client
- Panels are packages, features are source: you upgrade the panels by bumping a version, and you own every block you install
Next steps
Platform modules
Data models, workflows, and events for each marketplace module.
Extend a workflow
Run your own step inside an existing flow through a hook.
Panel extensions
Add pages, widgets, custom fields, and navigation to the panels.
API conventions
Authentication, seller scoping, and the three API surfaces.