Medusa.js Architecture Explained: How the Headless Backend Powers Modern Stores

The word "headless" is used so frequently in commerce discussions that it risks losing meaning. In Medusa.js, headless has a precise technical definition: the backend and the frontend are entirely separate applications that communicate exclusively through an API. There is no shared rendering pipeline, no templating engine that the backend controls, and no assumption about what technology the frontend uses.

In a traditional monolithic ecommerce platform, the backend generates the HTML that the browser renders. A Magento theme file, for example, is a PHP template that the Magento backend fills with data and sends to the browser as a complete page. The backend decides the structure of the page, the data it contains, and how it is rendered. Changing the frontend means working within the constraints of the backend's rendering system.

Medusa.js inverts this. The backend generates no HTML at all. It exposes data and operations through API endpoints. The frontend requests data, receives JSON responses, and renders whatever experience it chooses. This separation is what makes it possible to run a website, a mobile app, and a B2B portal from a single Medusa backend without duplicating any commerce logic. As the Askan Technologies overview of the Medusa.js headless backend explains, this API-first approach is the foundation that makes Medusa genuinely composable in ways monolithic platforms cannot match.

Layer 1: The Core Backend Server

The Medusa server is a Node.js application written in TypeScript. It handles incoming API requests, routes them to the appropriate service or module, executes business logic, persists data to the database, and returns responses. The server runs as a standalone process on your infrastructure a VPS, a cloud VM, a container in Kubernetes, or a managed Node.js hosting environment. Medusa does not prescribe your hosting model. You deploy it wherever your infrastructure standards require.

The server uses Express.js under the hood to handle HTTP routing. When a request arrives, Express routes it to a Medusa route handler, which calls the relevant service layer method, which in turn interacts with the relevant module. The entire request lifecycle is synchronous where possible and event-driven where deferred processing is needed.

Layer 2: The Module System

Medusa 2.0 introduced a fully modular architecture that is the most important structural aspect of the platform to understand. Every major commerce domain is implemented as an independent module: the product module manages catalog data, the cart module manages active shopping sessions, the order module tracks purchases through their lifecycle, the pricing module calculates prices and applies rules, the inventory module tracks stock levels across locations, and so on.

Each module is a self-contained unit with its own database schema, its own service methods, and its own event emitters. Modules communicate with each other through defined interfaces, not by directly accessing each other's internals. This means you can replace any module with a custom implementation without touching the rest of the system. If your business needs a custom pricing engine that calculates prices from an external ERP rather than Medusa's default pricing tables, you build a custom pricing module that implements the same interface and swap it in. The rest of the system does not change.

Layer 3: The Services Layer

Above the modules sits the services layer. Services are TypeScript classes that expose methods for performing commerce operations. The OrderService has methods like createOrder, cancelOrder, createRefund, and createReturn. The ProductService has methods like createProduct, updateProduct, listProducts, and deleteProduct. When an API route handler receives a request to create an order, it calls OrderService.createOrder(), which orchestrates the necessary module interactions: updating inventory, recording payment, triggering fulfillment, and emitting events.

Services are where business logic lives. They are also where customization begins. You can extend any Medusa service by creating a custom class that extends the default service and overrides specific methods. Your custom logic runs while the rest of the service behavior remains intact. This is a cleaner extensibility model than Magento's plugin and preference system, where overriding a class requires declaring a preference in configuration and can create conflicts when multiple extensions override the same class.

Layer 4: The API Layer

The outermost layer is the REST API that your storefront and admin panel consume. Medusa exposes two distinct API surfaces: the Store API, which is used by customer-facing frontends, and the Admin API, which is used by the admin dashboard and internal tooling. The Store API is intentionally limited to operations that a customer should be able to perform: browsing products, managing a cart, placing an order, viewing order history. The Admin API exposes full management capabilities: creating products, processing refunds, managing inventory levels, configuring tax rules.

Both APIs follow RESTful conventions and return JSON responses. Authentication uses JWT tokens for the Store API (issued at customer login) and API keys for the Admin API (used by backend services and the admin panel). Medusa also supports custom API routes, so you can add endpoints specific to your business without modifying core code.

The following modules ship with Medusa and cover the full lifecycle of an ecommerce operation.

• Product Module: Manages product types, variants, options, collections, categories, tags, and associated metadata. Supports unlimited custom attributes per product type.

• Cart Module: Handles active shopping sessions, line item management, discount application, shipping option selection, and payment session initialization.

• Order Module: Tracks orders from placement through fulfillment, managing payment capture, shipment records, returns, refunds, and credit notes.

• Pricing Module: Calculates prices using price lists, customer group rules, currency conversions, volume tiers, and regional overrides. The most powerful and flexible pricing engine Medusa offers.

• Inventory Module: Tracks stock levels per SKU per inventory location. Supports reservations (stock held for an order in progress), adjustments, and multi-location fulfillment.

• Fulfillment Module: Manages the shipping lifecycle from order placement to delivery. Supports multiple fulfillment providers, partial shipments, and split-fulfillment across locations.

• Customer Module: Handles customer accounts, authentication, address books, customer groups, and saved payment methods.

• Payment Module: Provides a consistent interface for payment providers. Stripe and PayPal are supported natively. Custom providers implement the same interface for any other gateway.

The module interface system is what makes Medusa genuinely extensible rather than just configurable. Every module in Medusa implements a defined TypeScript interface. To replace the default inventory module with one backed by your ERP system, you create a class that implements the IInventoryModuleService interface, write your ERP integration logic inside it, and register it as the inventory module in your Medusa configuration. The rest of the system, including the order service and the fulfillment module, continues to call the same interface methods and receives correctly typed responses.

This contrasts sharply with the Magento extension model, where customization typically involves declaring preference overrides in di.xml and creating plugin classes that intercept method calls. When two Magento extensions declare preferences for the same class, one silently overrides the other. In Medusa, module replacement is explicit and declared at the application level, making conflicts visible rather than hidden.

One of the most significant architectural additions in Medusa 2.0 is the workflows engine. Workflows are a structured way to define multi-step business processes that must execute reliably, handle failures gracefully, and remain auditable.

Before workflows, complex operations like order placement involved a chain of service method calls with manual rollback logic if one step failed. If payment captured successfully but inventory reservation failed, the developer was responsible for writing the compensation logic. In practice, this meant inconsistent implementations across different teams and hard-to-debug edge cases in production.

Medusa workflows define each step as a discrete unit with an explicit compensate function. If step 3 of a 5-step workflow fails, Medusa automatically runs the compensate functions for steps 1 and 2 in reverse order, leaving the system in a consistent state. This saga pattern is well established in distributed systems, and Medusa's workflow engine brings it to commerce operations where order-level data consistency is critical.

Medusa uses an event-driven architecture for operations that should happen asynchronously after a primary action. When an order is placed, the OrderService emits an order.placed event. Any number of subscribers can listen to this event and execute independently: one subscriber sends a confirmation email, another triggers a CRM update, a third initiates a fulfillment request to a third-party warehouse.

This event-subscriber pattern keeps the core commerce operations fast and free from side-effect overhead. The order placement API call returns a response to the storefront as soon as the order is persisted. The email, CRM update, and fulfillment trigger happen in the background without adding to the customer's checkout response time.

Subscribers are TypeScript classes registered with the Medusa event system. Writing a custom subscriber is straightforward: implement a class with a handle method, decorate it with the event name it should listen to, and register it in your Medusa configuration. This makes integrations with external services clean and decoupled from core commerce logic.

Medusa uses PostgreSQL as its primary datastore and TypeORM as the ORM layer. All commerce data, products, orders, customers, inventory, and configuration, lives in a single PostgreSQL database. Each module manages its own database schema through TypeORM entity definitions, but all entities are stored in the same database unless you specifically configure a separate database per module.

The repository pattern used in Medusa means data access is always abstracted through a repository class. Service methods call repository methods rather than writing raw SQL or ORM queries directly. This abstraction makes the codebase testable and makes it possible to swap the underlying database adapter in future if needed, though PostgreSQL is the current recommended and supported option.

Medusa does not include a built-in caching layer at the application level. Product catalog data, pricing rules, and configuration are read from PostgreSQL on each request unless you implement caching at the infrastructure level. For production stores with high read traffic, placing a caching layer such as Redis between the Medusa API and the database for frequently requested data like product listings and pricing rules is a standard performance optimization. This is typically implemented as a custom middleware layer or as part of the storefront's server-side rendering cache strategy in Next.js.

The Medusa admin dashboard is a separate React application that communicates with the Medusa backend exclusively through the Admin API. It is not embedded in the server but runs as its own frontend application. By default it is served by the Medusa server at the /app path, but it can be hosted independently as a static site if your deployment model requires separation between the API server and the admin frontend.

The admin is built on top of Medusa's UI component library and uses React Query for data fetching and state synchronization. It supports extension through custom widgets and custom pages, which are React components registered with the admin application. If your business needs a custom order status view, a product import interface, or a reporting dashboard built into the admin, these are built as admin extensions without modifying the core admin source.

One of the most commercially significant consequences of Medusa's headless architecture is that a single backend can power multiple distinct storefronts simultaneously. A D2C brand can run a consumer website, a wholesale B2B portal, and a mobile app, each with different product selections, pricing rules, and checkout experiences, all backed by the same Medusa instance. The Askan Technologies guide on Medusa vs Magento covers this multi-channel capability in detail, noting that achieving the same outcome in Magento requires multi-store configuration and significant additional infrastructure.

In Medusa, sales channels are a first-class concept. Products are associated with one or more sales channels. Pricing rules can be scoped to specific sales channels. Each storefront authenticates with the Store API using a publishable API key scoped to its sales channel, meaning the storefront only sees the products, prices, and promotions relevant to it. The backend handles all of this routing and scoping without any additional code in the storefront.

A production Medusa.js deployment typically involves several components running together. Understanding this deployment model helps in planning infrastructure costs and DevOps requirements.

• Medusa server process running on Node.js (minimum 2 vCPUs, 4 GB RAM for moderate traffic).

• PostgreSQL database instance (managed service like AWS RDS or Google Cloud SQL recommended for reliability).

• Redis instance for job queues and optionally for session storage.

• File storage service for product images and assets (AWS S3, Google Cloud Storage, or Cloudflare R2).

• A reverse proxy such as Nginx in front of the Medusa server to handle SSL termination and rate limiting.

Because Medusa is a stateless Node.js application, it scales horizontally by running multiple server instances behind a load balancer. Session data is stored in PostgreSQL or Redis rather than in-memory, so any server instance can handle any request. This makes Medusa straightforward to scale under traffic spikes: add instances when needed and remove them when traffic subsides. This horizontal scaling model is one of the structural advantages Medusa has over Magento, which requires more complex Varnish and Redis caching configurations to handle high concurrency on a single server.