What is Medusa.js v2 and how is its architecture built?

Sources checked on 11 November 2026, against the Medusa v2 documentation; the latest release on that day was v2.22.6.

This guide is for a CTO, architect or product owner who is hearing about Medusa for the first time or assessing it as the foundation of a new store. It explains what a Medusa v2 application consists of, where your own logic goes and what you need to deploy next to it.

The short version: Medusa v2 is a Node.js server with an admin dashboard, built from independent domain modules. Business logic that touches several modules or external systems lives in workflows, which can roll back completed steps after an error. The storefront is a separate application that talks to Medusa through the API.

According to the Medusa architecture overview, a request from the storefront or admin first reaches an API route. The server runs on Express.js. The route runs a workflow, the workflow uses modules, and the modules read and write data in the database.

Medusa supports only PostgreSQL as its main database. Another database can be connected only inside a custom module. The table shows where your own code goes in each layer.

A module is a package of features for one domain: data models (tables) and a service that manages them. After installation the modules on the list of commerce modules are available, including cart, order, product, pricing, promotion, inventory, payment, tax, customer and user. The exceptions are the loyalty module, installed as a plugin, and the Enterprise Edition RBAC module. Their features are exposed through ready-made API routes.

The second group consists of infrastructure modules. They handle technical services, and the provider behind each of them can be replaced:

• Event Module: event publishing and subscriptions (pub/sub).
• Workflow Engine Module: workflow orchestration.
• Caching Module: caching data that is expensive to compute.
• Locking Module: locks when several processes access the same resources.
• File Module: file storage, for example product images.
• Notification Module: sending notifications to customers and users.
• Analytics Module: forwarding events to an external analytics tool.

Watch the names: the loyalty module on the commerce modules list requires installing the Loyalty Plugin (Medusa v2.14.0+) and, according to the documentation, handles gift cards. A module's name does not yet tell you whether it covers your process; check the description of its features.

The principle of module isolation means that a module cannot see the services or data models of other modules. Your module cannot, for example, call the product module's service or define a direct relation to its tables.

Data from different modules is connected through module links. For each link Medusa creates a separate table that stores only the IDs of the linked records, with no foreign key constraint. Data from several modules is retrieved with the Query tool.

For an architect this gives a simple rule: you store your own business concept, such as a brand or a trade agreement, in your own module and connect it to a product or customer with a link. You do not change the tables of core modules; according to the documentation, isolation lets you add your own module to an application without side effects on the rest of it.

According to the workflows documentation, a workflow is a series of steps that completes a task. Unlike a regular function, Medusa tracks the progress of each step, lets you define rollback logic and runs long actions asynchronously. A workflow is executed from an API route, an event subscriber or a scheduled job.

Rollback is described by a step's compensation function: if a step created a record and a later step failed, the compensation deletes that record. This way data in Medusa and in external systems is not left in an intermediate state.

A hypothetical example, not a client project: a wholesaler wants each store order to reach the ERP. The workflow could look like this:

1. Retrieve the order with its items and customer data using Query.
2. Map the data to the ERP format: item codes, units, customer account number.
3. Create the document in the ERP through an integration module; the compensation cancels the document if a later step fails.
4. Store the ERP document number in your own module and connect it to the order with a module link.
5. Report the failure to the person responsible if the workflow fails. This is not another workflow step: after an error Medusa runs the compensations, not the remaining steps, so the report is handled by the code that ran the workflow (subscriber, API route or scheduled job).

Medusa emits events during core operations, for example order.placed after an order is placed. The events and subscribers guide shows how to handle them with an asynchronous function in the same codebase, without a separate webhook application.

A subscriber runs outside the main flow, so it suits side actions such as a confirmation email. If the action is essential to the flow itself, the documentation points to workflow hooks instead.

Scheduled jobs run a function on a cron expression while the application is running, for example to sync products with an ERP. For actions that must run while the application is stopped, the documentation recommends custom CLI scripts called by the operating system's scheduler.

Events are handled by the Event Module. The local version, used by default, is meant for development; for production the documentation points to the Redis-based module.

The Medusa Admin dashboard is installed together with the application. According to the admin development guide, you can add widgets to existing pages and add new pages, but you cannot change the layout, design or content of existing pages. For heavy changes the documentation suggests building your own dashboard on the Admin API.

The storefront is a separate application. A starting point can be the Next.js Starter Storefront, which since v2.14.0 is placed in one repository (monorepo) with the Medusa application when you install with create-medusa-app. You can also build your own frontend in any technology.

The deployment overview separates the Medusa application (server and admin) from at least one storefront, and they are deployed separately; the server connects to PostgreSQL and Redis. For production the documentation recommends two instances of the same application: a server for requests and a worker for background tasks, and the hosting plan must offer at least 2 GB of RAM. The alternative is managed hosting on Medusa Cloud.

First, the licence: according to the licence file in the repository, Medusa is available under the MIT licence, except for the Enterprise Edition materials, which require a separate commercial agreement. No licence fee for the core does not mean no cost: you pay for hosting, development and maintenance.

The decision depends on how much of your process goes beyond a standard store and who will maintain the code. The table shows conditions, not a ready verdict.

If you sell to businesses and need contract pricing, credit limits and a clear split of responsibility with the ERP, the topic is covered in the Medusa B2B ecommerce guide.

The order below reduces the risk of designing the architecture before understanding the process. Each step ends with a document or a working piece that can be checked.

A time and budget estimate makes sense only after steps 1 and 2, because it depends on the number of custom modules and integrations rather than on Medusa itself.

1. Describe the sales process: who buys, how the price is formed, what happens after the order, what the exceptions are.
2. Map the process to modules: what the commerce modules cover, what needs a custom module and what stays in the ERP.
3. Design integrations as workflows: steps, compensations and who is told about a failure.
4. Build the shortest purchase path from catalogue to ERP order and check it on test data.
5. Prepare production: a separate server and worker, Redis for events, database backups and monitoring.
6. Plan upgrades: who checks new Medusa releases, how often, and how custom modules are tested after an upgrade.