# medusajs/medusa architecture

> Architecture diagram of the GitHub repository medusajs/medusa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/medusajs/medusa
- Repository: https://github.com/medusajs/medusa

## Overview

Medusa is a modular commerce platform: a user or storefront client interacts with server APIs, which expose commerce capabilities implemented by modules and extensible through providers and workflows. The admin dashboard is a separate user-facing surface; orchestration supplies durable transaction behavior beneath workflows. The README establishes the product’s package roles, while sampled source confirms selected fulfillment and orchestration relationships. Several broader runtime connections are not shown in the excerpts, so those links are omitted or marked unverified.

Main entry points: [`packages/modules`](https://github.com/medusajs/medusa/tree/develop/packages/modules) (Commerce Modules), [`packages/core/orchestration/src/transaction/distributed-transaction.ts`](https://github.com/medusajs/medusa/blob/develop/packages/core/orchestration/src/transaction/distributed-transaction.ts) (Distributed Transaction), [`packages/medusa/src`](https://github.com/medusajs/medusa/tree/develop/packages/medusa/src) (Medusa Server), [`packages/admin/dashboard/src/app.tsx`](https://github.com/medusajs/medusa/blob/develop/packages/admin/dashboard/src/app.tsx) (Admin Dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_dashboard["Admin Dashboard<br/>[app.tsx]"]
  node_server["Medusa Server"]
  node_admin_api["Admin API"]
  node_store_api["Store API"]
end

subgraph group_commerce["Commerce Runtime"]
  node_commerce_modules["Commerce Modules"]
  node_fulfillment["Fulfillment Service"]
  node_infrastructure["Infrastructure Modules"]
  node_storage_provider["Index Storage Provider"]
  node_common_types["Core Types<br/>[common.ts]"]
end

subgraph group_workflow["Workflow Runtime"]
  node_core_flows["Core Workflows"]
  node_workflow_sdk["Workflows SDK"]
  node_transaction["Distributed Transaction"]
  node_transaction_step["Transaction Steps"]
  node_transaction_storage["Transaction Storage"]
  node_workflow_storage[("Workflow Storage")]
end

subgraph group_extensions["Extensions"]
  node_fulfillment_provider["Fulfillment Provider"]
  node_payment_provider["Payment Providers"]
  node_admin_extensions["Admin Extensions<br/>[generate-routes.ts]"]
  node_admin_parser["Admin Source Parser<br/>[babel.ts]"]
  node_loyalty_workflows["Loyalty Workflows"]
  node_scaffolder["App Scaffolder<br/>[execute.ts]"]
  node_http_types["HTTP Types Generator<br/>[path-mapper.ts]"]
  node_http_fs["Types File Helpers<br/>[fs-helpers.ts]"]
end

node_operator(("Operator"))
node_storefront(("Storefront Client"))

node_operator -->|"uses"| node_dashboard
node_storefront -.->|"calls"| node_store_api
node_dashboard -.->|"calls"| node_admin_api
node_server -->|"hosts"| node_admin_api
node_server -->|"hosts"| node_store_api
node_admin_api -.->|"exposes"| node_commerce_modules
node_store_api -.->|"exposes"| node_commerce_modules
node_commerce_modules -->|"includes"| node_fulfillment
node_fulfillment -->|"uses"| node_fulfillment_provider
node_commerce_modules -.->|"integrates"| node_payment_provider
node_server -->|"re-exports"| node_core_flows
node_workflow_sdk -.->|"orchestrates"| node_transaction
node_transaction -->|"uses"| node_transaction_storage
node_transaction -->|"runs"| node_transaction_step
node_transaction_storage -->|"references"| node_transaction_step
node_workflow_storage -->|"implements storage"| node_transaction
node_commerce_modules -.->|"uses"| node_infrastructure
node_storage_provider -->|"uses types"| node_common_types
node_admin_extensions -->|"parses with"| node_admin_parser
node_admin_extensions -.->|"extends"| node_dashboard
node_loyalty_workflows -.->|"uses"| node_transaction
node_scaffolder -.->|"creates app"| node_server
node_http_types -->|"uses"| node_http_fs

click node_dashboard "https://github.com/medusajs/medusa/blob/develop/packages/admin/dashboard/src/app.tsx"
click node_server "https://github.com/medusajs/medusa/tree/develop/packages/medusa/src"
click node_admin_api "https://github.com/medusajs/medusa/tree/develop/packages/medusa/src/api/admin"
click node_store_api "https://github.com/medusajs/medusa/tree/develop/packages/medusa/src/api/store"
click node_commerce_modules "https://github.com/medusajs/medusa/tree/develop/packages/modules"
click node_fulfillment "https://github.com/medusajs/medusa/blob/develop/packages/modules/fulfillment/src/services/fulfillment-module-service.ts"
click node_fulfillment_provider "https://github.com/medusajs/medusa/blob/develop/packages/modules/fulfillment/src/services/fulfillment-provider.ts"
click node_payment_provider "https://github.com/medusajs/medusa/tree/develop/packages/modules/providers"
click node_infrastructure "https://github.com/medusajs/medusa/tree/develop/packages/modules"
click node_core_flows "https://github.com/medusajs/medusa/tree/develop/packages/core/core-flows"
click node_workflow_sdk "https://github.com/medusajs/medusa/tree/develop/packages/core/workflows-sdk"
click node_transaction "https://github.com/medusajs/medusa/blob/develop/packages/core/orchestration/src/transaction/distributed-transaction.ts"
click node_transaction_step "https://github.com/medusajs/medusa/blob/develop/packages/core/orchestration/src/transaction/transaction-step.ts"
click node_transaction_storage "https://github.com/medusajs/medusa/blob/develop/packages/core/orchestration/src/transaction/datastore/abstract-storage.ts"
click node_workflow_storage "https://github.com/medusajs/medusa/blob/develop/packages/modules/workflow-engine-inmemory/src/utils/workflow-orchestrator-storage.ts"
click node_storage_provider "https://github.com/medusajs/medusa/blob/develop/packages/core/types/src/index-data/storage-provider.ts"
click node_admin_extensions "https://github.com/medusajs/medusa/blob/develop/packages/admin/admin-vite-plugin/src/routes/generate-routes.ts"
click node_admin_parser "https://github.com/medusajs/medusa/blob/develop/packages/admin/admin-vite-plugin/src/babel.ts"
click node_loyalty_workflows "https://github.com/medusajs/medusa/blob/develop/packages/plugins/loyalty/src/workflows/gift-cards/workflows/create-gift-cards.ts"
click node_scaffolder "https://github.com/medusajs/medusa/blob/develop/packages/cli/create-medusa-app/src/utils/execute.ts"
click node_http_types "https://github.com/medusajs/medusa/blob/develop/packages/cli/http-types-generator/src/mapping/path-mapper.ts"
click node_http_fs "https://github.com/medusajs/medusa/blob/develop/packages/cli/http-types-generator/src/utils/fs-helpers.ts"
click node_common_types "https://github.com/medusajs/medusa/blob/develop/packages/core/types/src/index-data/common.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_dashboard,node_server,node_admin_api,node_store_api,node_storefront toneBlue
class node_commerce_modules,node_fulfillment,node_infrastructure,node_storage_provider,node_common_types toneAmber
class node_core_flows,node_workflow_sdk,node_transaction,node_transaction_step,node_transaction_storage,node_workflow_storage toneMint
class node_fulfillment_provider,node_payment_provider,node_admin_extensions,node_admin_parser,node_loyalty_workflows,node_scaffolder,node_http_types,node_http_fs toneRose
class node_operator toneIndigo
```

## Components

### User Interfaces

- [Admin Dashboard](https://github.com/medusajs/medusa/blob/develop/packages/admin/dashboard/src/app.tsx): `packages/admin/dashboard/src/app.tsx`
- [Medusa Server](https://github.com/medusajs/medusa/tree/develop/packages/medusa/src): `packages/medusa/src`
- [Admin API](https://github.com/medusajs/medusa/tree/develop/packages/medusa/src/api/admin): `packages/medusa/src/api/admin`
- [Store API](https://github.com/medusajs/medusa/tree/develop/packages/medusa/src/api/store): `packages/medusa/src/api/store`

### Commerce Runtime

- [Commerce Modules](https://github.com/medusajs/medusa/tree/develop/packages/modules): `packages/modules`
- [Fulfillment Service](https://github.com/medusajs/medusa/blob/develop/packages/modules/fulfillment/src/services/fulfillment-module-service.ts): `packages/modules/fulfillment/src/services/fulfillment-module-service.ts`
- [Infrastructure Modules](https://github.com/medusajs/medusa/tree/develop/packages/modules): `packages/modules`
- [Index Storage Provider](https://github.com/medusajs/medusa/blob/develop/packages/core/types/src/index-data/storage-provider.ts): `packages/core/types/src/index-data/storage-provider.ts`
- [Core Types](https://github.com/medusajs/medusa/blob/develop/packages/core/types/src/index-data/common.ts): `packages/core/types/src/index-data/common.ts`

### Workflow Runtime

- [Core Workflows](https://github.com/medusajs/medusa/tree/develop/packages/core/core-flows): `packages/core/core-flows`
- [Workflows SDK](https://github.com/medusajs/medusa/tree/develop/packages/core/workflows-sdk): `packages/core/workflows-sdk`
- [Distributed Transaction](https://github.com/medusajs/medusa/blob/develop/packages/core/orchestration/src/transaction/distributed-transaction.ts): `packages/core/orchestration/src/transaction/distributed-transaction.ts`
- [Transaction Steps](https://github.com/medusajs/medusa/blob/develop/packages/core/orchestration/src/transaction/transaction-step.ts): `packages/core/orchestration/src/transaction/transaction-step.ts`
- [Transaction Storage](https://github.com/medusajs/medusa/blob/develop/packages/core/orchestration/src/transaction/datastore/abstract-storage.ts): `packages/core/orchestration/src/transaction/datastore/abstract-storage.ts`
- [Workflow Storage](https://github.com/medusajs/medusa/blob/develop/packages/modules/workflow-engine-inmemory/src/utils/workflow-orchestrator-storage.ts): `packages/modules/workflow-engine-inmemory/src/utils/workflow-orchestrator-storage.ts`

### Extensions

- [Fulfillment Provider](https://github.com/medusajs/medusa/blob/develop/packages/modules/fulfillment/src/services/fulfillment-provider.ts): `packages/modules/fulfillment/src/services/fulfillment-provider.ts`
- [Payment Providers](https://github.com/medusajs/medusa/tree/develop/packages/modules/providers): `packages/modules/providers`
- [Admin Extensions](https://github.com/medusajs/medusa/blob/develop/packages/admin/admin-vite-plugin/src/routes/generate-routes.ts): `packages/admin/admin-vite-plugin/src/routes/generate-routes.ts`
- [Admin Source Parser](https://github.com/medusajs/medusa/blob/develop/packages/admin/admin-vite-plugin/src/babel.ts): `packages/admin/admin-vite-plugin/src/babel.ts`
- [Loyalty Workflows](https://github.com/medusajs/medusa/blob/develop/packages/plugins/loyalty/src/workflows/gift-cards/workflows/create-gift-cards.ts): `packages/plugins/loyalty/src/workflows/gift-cards/workflows/create-gift-cards.ts`
- [App Scaffolder](https://github.com/medusajs/medusa/blob/develop/packages/cli/create-medusa-app/src/utils/execute.ts): `packages/cli/create-medusa-app/src/utils/execute.ts`
- [HTTP Types Generator](https://github.com/medusajs/medusa/blob/develop/packages/cli/http-types-generator/src/mapping/path-mapper.ts): `packages/cli/http-types-generator/src/mapping/path-mapper.ts`
- [Types File Helpers](https://github.com/medusajs/medusa/blob/develop/packages/cli/http-types-generator/src/utils/fs-helpers.ts): `packages/cli/http-types-generator/src/utils/fs-helpers.ts`

### Other components

- **Operator**
- **Storefront Client**

## Connections

- Operator → Admin Dashboard: uses (evidence: `README.md`)
- Storefront Client → Store API: calls
- Admin Dashboard → Admin API: calls
- Medusa Server → Admin API: hosts (evidence: `README.md`)
- Medusa Server → Store API: hosts (evidence: `README.md`)
- Admin API → Commerce Modules: exposes
- Store API → Commerce Modules: exposes
- Commerce Modules → Fulfillment Service: includes (evidence: `README.md`)
- Fulfillment Service → Fulfillment Provider: uses (evidence: `packages/modules/fulfillment/src/services/fulfillment-module-service.ts`)
- Commerce Modules → Payment Providers: integrates (evidence: `packages/modules/providers/auth-oidc/src/engine/engine.ts`)
- Medusa Server → Core Workflows: re-exports (evidence: `README.md`)
- Workflows SDK → Distributed Transaction: orchestrates
- Distributed Transaction → Transaction Storage: uses (evidence: `packages/core/orchestration/src/transaction/distributed-transaction.ts`)
- Distributed Transaction → Transaction Steps: runs (evidence: `packages/core/orchestration/src/transaction/distributed-transaction.ts`)
- Transaction Storage → Transaction Steps: references (evidence: `packages/core/orchestration/src/transaction/datastore/abstract-storage.ts`)
- Workflow Storage → Distributed Transaction: implements storage (evidence: `packages/modules/workflow-engine-inmemory/src/utils/workflow-orchestrator-storage.ts`)
- Commerce Modules → Infrastructure Modules: uses
- Index Storage Provider → Core Types: uses types (evidence: `packages/core/types/src/index-data/storage-provider.ts`)
- Admin Extensions → Admin Source Parser: parses with (evidence: `packages/admin/admin-vite-plugin/src/routes/generate-routes.ts`)
- Admin Extensions → Admin Dashboard: extends
- Loyalty Workflows → Distributed Transaction: uses
- App Scaffolder → Medusa Server: creates app
- HTTP Types Generator → Types File Helpers: uses (evidence: `packages/cli/http-types-generator/src/mapping/path-mapper.ts`)