Medusa
MedusaJS is the open-source commerce framework that powers Mercur’s foundation. It handles products, pricing, carts, orders, payments, fulfillment, and promotions. Mercur does not replace any of this — it extends Medusa with marketplace-specific logic using Medusa’s own extension model.Admin Panel
The admin panel is a React application for marketplace operators. It provides a dashboard to manage sellers, configure commission rates, moderate product requests, handle disputes, and monitor the overall marketplace. It is built with Medusa UI components and can be extended with custom pages and components through the Dashboard SDK.Vendor Portal
The vendor portal is a React application for sellers. Sellers use it to manage their products, process orders, configure shipping, track payouts, and handle returns. Like the admin panel, it is built on the Dashboard SDK and can be fully customized.Storefront
The storefront is the customer-facing application. It can be built with any frontend technology that consumes the Store API — Next.js, Remix, or any other framework. Mercur provides a ready-made storefront template to start from.API Routes
Mercur exposes three sets of HTTP endpoints:- Admin API (
/admin/*) — Platform administration - Vendor API (
/vendor/*) — Seller operations - Store API (
/store/*) — Customer-facing storefront
Core Plugin
The core plugin (@mercurjs/core-plugin) is the main package that contains all of Mercur’s marketplace logic — modules, links, workflows, API routes, subscribers, and providers. It is installed as a standard MedusaJS plugin and serves as the foundation that blocks extend.
Modules
Modules encapsulate data models and business logic for a specific domain. Each module is self-contained with its own models, service, and migrations. Mercur’s marketplace modules include Seller, Commission, Payout, Marketplace, Requests, Reviews, and others. They communicate through Links and Workflows, never directly.Links
Links define relationships between Mercur modules and Medusa core entities without modifying either side. For example, a link connects a Medusa Product to a Mercur Seller — this is how the system knows which seller owns which product.Workflows
Workflows coordinate multi-step operations across modules. They support compensation (automatic rollback on failure) and hooks (extension points for custom logic). For example, the checkout workflow splits a cart by seller, creates separate orders, allocates payments, and calculates commissions — all as a single atomic operation.Blocks
Blocks are the unit of distribution in Mercur. Each block is a self-contained piece of functionality — a module, a workflow, an API route, a link, or a UI extension. When you install a block, the CLI copies its source code directly into your project. You own every line and can modify anything.Registry
A registry is a collection of blocks available for installation. The official Mercur registry (@mercurjs) provides all marketplace blocks. You can also create and host custom registries for your own blocks.
CLI
The Mercur CLI (@mercurjs/cli@latest) manages your project — scaffolding from templates, installing blocks, searching registries, generating types, and diffing local changes against upstream versions.
Dashboard SDK
The Dashboard SDK (@mercurjs/dashboard-sdk) is a Vite plugin shared by the admin panel and vendor portal. It provides file-based routing, automatic navigation generation, component overrides, and i18n support.
API Client
The API Client (@mercurjs/client) provides type-safe access to all Mercur API endpoints. Types are generated from your actual API routes using bunx @mercurjs/cli@latest codegen, so requests and responses are always in sync with your backend.