New arrivals: 14 Scout case studies

Medusa Explained · Modules

What's inside a Medusa module

In Medusa, commerce data and operations are organised into modules: catalogue, prices, stock, warehouses. Let's see why this division is useful and what a module contains. We will also see how to create our own using the same tools as Medusa.

3 November 2026Understanding Medusa

One trainer, four modules

Consider a trainer sold in a Medusa store. Its record (name, description, sizes, colours) belongs to the Productmodule. Its price, which may vary by currency or promotion, is handled by Pricing. The available quantity is tracked by Inventory. The warehouses and stores holding the pairs are described by Stock Location.

One product record, four modules

Product record
Trainer · 42 / BlueProductProductwhat are we selling?
€120PricingPricingwhat price?
In stockInventoryInventoryhow many?
Warehouse, storeStock LocationStock Locationwhere?
Here, there are four responsibilities: Product describes the variant, Pricing sets the price, Inventory counts quantities and Stock Location describes places.

One trainer, then, and four modules that each describe it in their own way. The rest of the store follows the same logic: the cart, order and payment each have their own module too.

Each store activity therefore follows its own rules, and Medusa organises its code around these activities.

Why divide things into domains

An online store brings together several sets of business logic : describing products, determining prices, tracking quantities, recording sales. Their rules differ in nature. In the catalogue, a product comes in variants; a price depends on conditions such as currency or customer type. If these sets of logic become intertwined in the code, understanding one or keeping its rules consistent requires untangling the entire system.

Separating responsibilities addresses this difficulty. We group together what concerns the same business area and limit dependencies between these groups. Each forms a domain : a coherent set of information, rules and operations. The catalogue is one. Products, variants (the trainer in size 42, in blue) and options (size, colour) are distinct, but some catalogue rules concern them together: a variant must provide a value for every option of its product. Prices follow other constraints, such as sales, currencies or business rates.

The developer draws these boundaries using specific criteria. They group together things that are closely related and evolve together. They separate responsibilities that have different reasons to change: a trainer's description stays the same when its price drops for a sale. This boundary follows the business activity. A screen may use several modules, and a module often groups several tables.

In Medusa, the module gives these boundaries a concrete form. It keeps its internal data and rules, and the rest of the application goes through its main service, which exposes its operations. Pricing and Product are two separate modules: changing pricing rules does not require rewriting Product. Readers familiar with Domain-Driven Design (DDD) will recognise an idea from this approach, which models the business to contain its complexity.

Maintenance benefits from this. You can understand a domain by reading its module, know where to look for a rule, and keep a change within known boundaries, reducing side effects. Dependencies between modules remain, and good boundaries always require judgement. Above all, they give each change a specific place to happen.

We still need to see what a domain actually contains. For that, an example smaller than a catalogue will do.

A domain with two entities: repairs

Imagine a Repairmodule. It does not exist in Medusa: it is an example small enough to understand its parts. Our store offers to repair damaged pairs, with a loose sole or an open seam, and needs to track these repairs.

Tracking relies on two kinds of entities. The repair request (RepairRequest) describes the reported problem and its status: open, then ready. The intervention (RepairIntervention) describes work performed for that request, such as regluing a sole or restitching a seam, and indicates whether it is complete. A repair request can involve several interventions; each intervention belongs to a single request. This is a one-to-many relationship, written 1 → N.

One request, several interventions

Module Repair

Repair workshop, Repair module

RepairRequest

req_01

problem
“loose sole”
status
open

1 request

RepairIntervention

int_01completed

description
“reglue the sole”
completed
true
request_id
req_01

int_02not completed

description
“restitch a seam”
completed
false
request_id
req_01

N interventions

Illustrative values. The parent request req_01 keeps its identifier; each child intervention points to it through request_id.

For each kind of entity, a model describes the available fields and their types. The concrete entity is a specific repair request, for example the loose sole reported on Tuesday. It has a stable identifier, allowing it to be found and referred to unambiguously. The model is written once; concrete entities then accumulate in the database.

Why put these two entities in the same module? Because an intervention has no meaning outside its repair request, and both follow the rules of repair tracking. This is the grouping criterion applied to a tiny case. Their relationship therefore stays inside the module: in the database, it will take the form of an SQL foreign key between two tables in the same domain.

This hypothetical module uses the same tools as Medusa's native modules. Those are far richer and cannot be reduced to this example, but their anatomy relies on the same parts. The first describes the data.

Describe the data once

Medusa describes data using its own modelling language, DML (Data Model Language). Here are the two models of the Repair :

import { model } from "@medusajs/framework/utils"

export const RepairRequest = model.define("repair_request", {
  id: model.id().primaryKey(),
  problem: model.text(),
  status: model.enum(["open", "ready"]).default("open"),
  interventions: model.hasMany(() => RepairIntervention, {
    mappedBy: "request",
  }),
})

export const RepairIntervention = model.define("repair_intervention", {
  id: model.id().primaryKey(),
  description: model.text(),
  completed: model.boolean().default(false),
  request: model.belongsTo(() => RepairRequest, {
    mappedBy: "interventions",
  }),
})

Each model is given a name, then its properties: an identifier and typed fields (text, a value chosen from a list, a boolean). The final properties declare the relationship on both sides. hasMany indicates that a repair request has several interventions, belongsTo that an intervention belongs to a request. The mappedBy option connects the two declarations by giving the name of the inverse property on each side.

This language is not reserved for extensions. Native modules are written the same way: the model Product in Medusa also starts with model.define.

What does this description produce? First, a definition for the ORM. An ORM (object-relational mapping) is the layer that maps objects used in code to rows in the tables of a relational database; Medusa uses MikroORM. Thanks to the models, the ORM knows how to read and save a repair request or an intervention.

Then, migrations. A migration is a script that changes the database structure: creating a table, adding a column. Medusa can generate them from models; they are then applied explicitly, and nothing changes the database without your knowledge. For our relationship, the migration adds a request_idcolumn to the interventions table, containing the repair request's identifier, and a foreign key ensuring that this column refers to an existing request. When a field is added to the model, a new migration is generated, then applied in the same way.

Finally, TypeScript types. Rather than copying the structure into a separate interface, we infer it from the model :

import { InferTypeOf } from "@medusajs/framework/types"

type RepairRequestType = InferTypeOf<typeof RepairRequest>

The type follows the model: if a field changes, the type changes with it.

From models to the database

DML models

RepairRequest RepairIntervention

ORM definitions, types and migrations

TypeScript type

InferTypeOf<typeof RepairRequest>

ORM mapping

objects↔rows

Migrations

  1. Generate the migration
  2. Apply the migration
  3. Tables
repair_request
idproblemstatus
req_01loose soleopen
1 N request_id → repair_request.id
repair_intervention
iddescriptioncompletedrequest_id
int_01reglue the soletruereq_01
int_02restitch a seamfalsereq_01
DML models provide ORM definitions, types and migrations; applying the migrations creates the SQL tables, linked by request_id.

One limitation needs to be stated clearly. DML alone does not create a running database, since migrations still need to be applied. Above all, the description does not yet expose any management methods to the application: nothing lets it create a repair request or list its interventions. The service provides these operations.

From model to service: the Service Factory

In a Medusa module, operations go through a service: a class that groups what can be done with the domain's data. Writing creation, reading, updating and deletion for each entity by hand would be lengthy and repetitive. For this, Medusa provides a Service Factory : a function, MedusaService, that builds the foundation of a service from the models it is given.

class RepairModuleService extends MedusaService({
  RepairRequest,
  RepairIntervention,
}) {}

These few lines give the module's main service management methods for each of the two models, including interventions. These are the operations known as CRUD: create, read, update, delete (create, read, update, delete).

OperationRepair requestIntervention
CreatecreateRepairRequestscreateRepairInterventions
ListlistRepairRequestslistRepairInterventions
Retrieve one itemretrieveRepairRequestretrieveRepairIntervention
UpdateupdateRepairRequestsupdateRepairInterventions
DeletedeleteRepairRequestsdeleteRepairInterventions

The names follow a simple rule: the operation, then the model name, plural except for retrieve, which reads a single item. This table shows the main operations ; the Factory generates a few others, for example to count results or make a deletion reversible.

The Factory also creates an internal service per model, repairRequestService and repairInterventionService, whose methods have short names: create, list, retrieve, update, delete. These services remain inside the module. The application goes through the main service.

The module designates its main service once. The generated management methods and the public methods that the developer adds to this service are then available to the application, without declaring exposure method by method. The application chooses which ones to call. This availability in code does not automatically create HTTP routes.

The Factory provides the service

RepairRequest RepairIntervention
MedusaService(…)

Module Repair

Repair workshop, Repair module

RepairModuleService

main service

  • request management
  • intervention management

internal services

repairRequestService manages RepairRequest
repairInterventionService manages RepairIntervention

Application

calls only the main service

MedusaService produces the main service from the two models, RepairModuleService and its internal services; the rest of the application only goes through the main service.

The roles remain clearly separated. Tables, the SQL relationship and types come from the DML models; methods and services come from the Factory. Here too, Medusa applies this mechanism to itself: the module service Product extends MedusaService with its own models.

The module can now create, read, update and delete repair requests and interventions. It does not yet know when a repair is ready.

The module's business rules

In this workshop, let's choose a simple rule: a repair request is ready when it has at least one intervention and all its interventions are complete. Such a rule cannot be inferred from any model: it belongs to the store's business logic. The developer must therefore write it as a method added to the main service, markReady(requestId).

Its process takes just a few steps. The method loads the repair request with its interventions, using the relationship declared in the DML. If the request has no interventions, it refuses. If even one intervention is incomplete, it also refuses and explains why. Otherwise, it sets the request's status to ready.

This rule spans two entities, but stays entirely within the same domain: the request and its interventions are two aspects of repair tracking. It does not need any other module.

The main service now contains two families of operations side by side. The methods generated by the Factory manage data; the business method applies a rule. Adding markReady neither hides nor replaces updateRepairRequests : both remain available on the same interface, and the Factory does not choose which ones to expose for you. A direct call to updateRepairRequests could therefore set a request to ready without checking anything. For this action, the application must call markReady.

Two calls, one business rule

Module Repair · same main service

Application

Business logic path

markReady(req_01)

Check

At least one intervention, all complete

Current result: refused

int_02 not completed

status remains open

If all are complete

status → ready

Generated method, still accessible

updateRepairRequests

Direct write

status → ready

without checking interventions

The service exposes the business method markReady, which checks interventions before changing the status, alongside the generated method updateRepairRequests, which remains accessible and writes directly.

The division of work is clear here. The framework provides the foundation: persistence, migrations, types and management operations. The developer keeps what gives their domain its value: its rules. There is still code to write, but it is the code that matters.

Extending Medusa for your business

Medusa provides the commerce engine: catalogue, prices, stock, orders and payments. A custom module adds the data, states, rules and operations of a business activity: contracts, due dates and renewals for subscriptions; requests, interventions and their statuses for a repair service; consignments and sales reports for consignment sales.

The framework handles the structure: DML defines the data models, and the Factory generates the standard methods to create, read, update and delete them. The developer writes the business logic : the rules, checks and operations specific to their business activity.

From this engine, you can develop business services around sales, gradually build a management tool approaching an ERP, or a SaaS application specialised in an industry. The next step is to understand how these modules can work together.

Something to dig into? Add this article to your office hours discussion.

See my discussion