Medusa Project Structure: Where Every Kind of Code Belongs

Medusa has no registration file for most things. Put a subscriber in src/subscribers/ and it is a subscriber. This is pleasant right up until you are unsure which of six directories a new piece of logic belongs in — and that choice determines how the codebase ages.

Here is the map, and the decision tree.

The map

src/
├── admin/          Dashboard extensions — widgets and routes
├── api/            HTTP endpoints, mirroring the URL path
├── jobs/           Scheduled work, cron-style
├── links/          Relationships between modules
├── modules/        Commerce domains: models, service, migrations
├── scripts/        One-off executables — seeds, backfills
├── subscribers/    Event handlers
└── workflows/      Multi-step processes with compensation

src/modules/

The unit of data ownership. One directory per domain, each with models/, service.ts, index.ts and generated migrations/. If it has tables, it lives here. Modules explained.

src/workflows/

Business processes. Convention is src/workflows/<name>.ts for the workflow and src/workflows/steps/<name>.ts for its steps. Anything touching two modules or one external system belongs here. Workflows explained.

src/api/

Directory structure mirrors the URL:

src/api/
├── admin/
│   └── suppliers/
│       ├── route.ts          → /admin/suppliers
│       └── [id]/route.ts     → /admin/suppliers/:id
├── store/
│   └── wishlists/route.ts    → /store/wishlists
└── middlewares.ts            → route middleware config

Export GET, POST, PUT or DELETE from route.ts. Routes under /admin require admin authentication; /store routes require a publishable key.

Keep route handlers thin: validate, resolve, call a workflow or service, respond. Business logic in a route handler is logic no subscriber or job can reuse.

src/subscribers/

Event handlers. One file per concern, exporting a handler and a config naming the event. Events and subscribers.

src/jobs/

Scheduled work:

import { MedusaContainer } from "@medusajs/framework/types"
import { syncInventoryWorkflow } from "../workflows/sync-inventory"

export default async function syncInventoryJob(container: MedusaContainer) {
  await syncInventoryWorkflow(container).run({ input: {} })
}

export const config = {
  name: "sync-inventory",
  schedule: "0 * * * *",
}

Jobs run on instances in worker mode. Keep the job body to a single workflow invocation — a job is a trigger, not a place for logic.

src/links/

One file per relationship, named for the pair: product-brand.ts, order-invoice.ts.

src/admin/

widgets/ inject into existing dashboard pages; routes/ add new ones. Admin customisation.

src/scripts/

Executables run manually via npx medusa exec ./src/scripts/<name>.ts. Seeds, backfills, data repairs. Not part of the request path, and not scheduled.

The decision tree

For any new piece of logic, in order:

1. Does it own data with its own lifecycle? → a module.
2. Does it happen on a schedule? → a job that calls a workflow.
3. Does it react to something that already happened? → a subscriber.
4. Is it triggered by an HTTP request? → an API route that calls a workflow or service.
5. Does it touch more than one module or an external system? → a workflow.
6. Is it a single-module operation? → a method on that module's service.
7. Is it a one-off? → a script.

Note that 2, 3 and 4 all end up calling a workflow. That is intentional: the entry point and the logic are different concerns, and keeping them separate is what lets the same process be triggered three ways.

What people get wrong

Logic in API routes. Fine until a scheduled job needs the same behaviour and you copy it.

A module with no models. If it has no data, it is a workflow or a service wrapper, not a module.

Subscribers doing transactional work. If failure should undo the original operation, it is a workflow step.

Scripts that become permanent. A backfill script run monthly is a job that has not been promoted yet.

Deep nesting in api/. URL depth is API design. Four levels usually means the resource model needs rethinking.

Configuration

medusa-config.ts at the root does two jobs: project configuration (database, Redis, CORS, secrets, worker mode) and module registration. Module and plugin registration is explicit; everything under src/ is not. See environment variables for how to keep that file free of literals.

Organising a large codebase

Convention tells you which directory. It does not tell you how to organise thirty modules and eighty workflows. What has held up for us:

Group workflows by domain, not by verb.

src/workflows/
├── subscriptions/
│   ├── renew-subscription.ts
│   ├── pause-subscription.ts
│   └── steps/
│       ├── charge-subscription.ts
│       └── advance-billing-period.ts
├── b2b/
│   ├── approve-order.ts
│   └── steps/
└── import/
    └── import-products.ts

Nested folders load fine, and a new engineer looking for subscription billing finds it in one guess.

Keep steps next to the workflow that owns them. A shared steps/ directory at the root becomes a junk drawer within a quarter. Only genuinely reused steps belong in a common location, and there are fewer of those than you expect.

One file per API route. Resist combining. The path is the file, and that is the property that makes the codebase navigable.

Where the shared code goes

The one thing convention does not cover: helpers that are neither a module nor a workflow.

Keep a third-party client inside the module that wraps that service, not in a shared lib. The moment two modules import the same client, you have coupled them through the back door — and the isolation rules exist precisely to prevent that.

Naming conventions

Small decisions, applied consistently, that make a codebase navigable:

The one that pays off during an incident is matching step names to filenames. When a workflow fails at 2am, the log line names the step, and you want that to be a filename you can open rather than a string you have to grep for.

Structure is cheap to get right at the start and expensive to fix later. We do architecture reviews if a codebase has drifted.