# mrgreullr/medusa architecture

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

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

## Overview

Medusa is a modular commerce platform: a customer or operator interacts with commerce APIs, which expose commerce operations backed by modules and workflow orchestration. The README describes broad use cases and customizable commerce building blocks; sampled source supports specific fulfillment, transaction-storage, and admin-route-generation relationships. Other subsystem connections are left unverified rather than inferred from names or directory structure.

Main entry points: [`packages/medusa/src/api`](https://github.com/mrgreullr/medusa/tree/develop/packages/medusa/src/api) (Commerce API), [`packages/modules`](https://github.com/mrgreullr/medusa/tree/develop/packages/modules) (Commerce modules), [`packages/plugins/loyalty/src/api/admin/gift-cards/route.ts`](https://github.com/mrgreullr/medusa/blob/develop/packages/plugins/loyalty/src/api/admin/gift-cards/route.ts) (Loyalty routes), [`packages/core/orchestration/src/transaction/distributed-transaction.ts`](https://github.com/mrgreullr/medusa/blob/develop/packages/core/orchestration/src/transaction/distributed-transaction.ts) (Distributed transaction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Commerce interfaces"]
  node_commerce_api["Commerce API"]
  node_product_api["Product routes<br/>[route.ts]"]
  node_search_api["Search routes<br/>[route.ts]"]
  node_loyalty_api["Loyalty routes<br/>[route.ts]"]
end

subgraph group_domain["Commerce capabilities"]
  node_commerce_modules["Commerce modules"]
  node_fulfillment_service["Fulfillment service"]
  node_fulfillment_provider["Fulfillment provider"]
  node_search_service["Search service"]
  node_index_storage["Index storage contract"]
  node_oidc_engine["OIDC authentication<br/>[engine.ts]"]
end

subgraph group_runtime["Workflow runtime"]
  node_gift_card_flow["Gift card workflow"]
  node_credit_flow["Store credit workflow"]
  node_orchestrator["Transaction orchestrator"]
  node_distributed_transaction["Distributed transaction"]
  node_transaction_step["Transaction steps"]
  node_transaction_storage[("Transaction storage")]
  node_memory_workflow_storage[("In-memory workflow storage")]
end

subgraph group_admin["Admin experience"]
  node_admin_dashboard["Admin dashboard<br/>[app.tsx]"]
  node_admin_route_builder["Admin route generation<br/>[generate-routes.ts]"]
  node_admin_babel["Admin source parser<br/>[babel.ts]"]
end

node_shopper(("Shopper or operator"))

node_shopper -.->|"sends requests"| node_commerce_api
node_commerce_api -.->|"routes requests"| node_product_api
node_commerce_api -.->|"routes requests"| node_search_api
node_commerce_api -.->|"exposes extensions"| node_loyalty_api
node_commerce_api -.->|"uses commerce logic"| node_commerce_modules
node_commerce_modules -.->|"includes fulfillment"| node_fulfillment_service
node_fulfillment_service -->|"calls provider"| node_fulfillment_provider
node_commerce_modules -.->|"includes search"| node_search_service
node_search_service -.->|"uses storage contract"| node_index_storage
node_loyalty_api -->|"invokes workflow"| node_gift_card_flow
node_loyalty_api -->|"invokes workflow"| node_credit_flow
node_commerce_modules -.->|"supports workflows"| node_orchestrator
node_orchestrator -.->|"coordinates execution"| node_distributed_transaction
node_distributed_transaction -->|"executes steps"| node_transaction_step
node_distributed_transaction -->|"persists checkpoints"| node_transaction_storage
node_memory_workflow_storage -.->|"implements storage contract"| node_transaction_storage
node_commerce_modules -.->|"offers authentication"| node_oidc_engine
node_shopper -.->|"manages commerce"| node_admin_dashboard
node_admin_dashboard -.->|"manages via API"| node_commerce_api
node_admin_route_builder -->|"parses routes"| node_admin_babel

click node_commerce_api "https://github.com/mrgreullr/medusa/tree/develop/packages/medusa/src/api"
click node_product_api "https://github.com/mrgreullr/medusa/blob/develop/packages/medusa/src/api/store/products/route.ts"
click node_search_api "https://github.com/mrgreullr/medusa/blob/develop/packages/medusa/src/api/store/search/route.ts"
click node_commerce_modules "https://github.com/mrgreullr/medusa/tree/develop/packages/modules"
click node_fulfillment_service "https://github.com/mrgreullr/medusa/blob/develop/packages/modules/fulfillment/src/services/fulfillment-module-service.ts"
click node_fulfillment_provider "https://github.com/mrgreullr/medusa/blob/develop/packages/modules/fulfillment/src/services/fulfillment-provider.ts"
click node_search_service "https://github.com/mrgreullr/medusa/blob/develop/packages/modules/search/src/services/search-module-service.ts"
click node_index_storage "https://github.com/mrgreullr/medusa/blob/develop/packages/core/types/src/index-data/storage-provider.ts"
click node_loyalty_api "https://github.com/mrgreullr/medusa/blob/develop/packages/plugins/loyalty/src/api/admin/gift-cards/route.ts"
click node_gift_card_flow "https://github.com/mrgreullr/medusa/blob/develop/packages/plugins/loyalty/src/workflows/gift-cards/workflows/create-gift-cards.ts"
click node_credit_flow "https://github.com/mrgreullr/medusa/blob/develop/packages/plugins/loyalty/src/workflows/store-credit/workflows/create-store-credit-accounts.ts"
click node_orchestrator "https://github.com/mrgreullr/medusa/blob/develop/packages/core/orchestration/src/transaction/transaction-orchestrator.ts"
click node_distributed_transaction "https://github.com/mrgreullr/medusa/blob/develop/packages/core/orchestration/src/transaction/distributed-transaction.ts"
click node_transaction_step "https://github.com/mrgreullr/medusa/blob/develop/packages/core/orchestration/src/transaction/transaction-step.ts"
click node_transaction_storage "https://github.com/mrgreullr/medusa/blob/develop/packages/core/orchestration/src/transaction/datastore/abstract-storage.ts"
click node_memory_workflow_storage "https://github.com/mrgreullr/medusa/blob/develop/packages/modules/workflow-engine-inmemory/src/utils/workflow-orchestrator-storage.ts"
click node_oidc_engine "https://github.com/mrgreullr/medusa/blob/develop/packages/modules/providers/auth-oidc/src/engine/engine.ts"
click node_admin_dashboard "https://github.com/mrgreullr/medusa/blob/develop/packages/admin/dashboard/src/app.tsx"
click node_admin_route_builder "https://github.com/mrgreullr/medusa/blob/develop/packages/admin/admin-vite-plugin/src/routes/generate-routes.ts"
click node_admin_babel "https://github.com/mrgreullr/medusa/blob/develop/packages/admin/admin-vite-plugin/src/babel.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_commerce_api,node_product_api,node_search_api,node_loyalty_api toneBlue
class node_commerce_modules,node_fulfillment_service,node_fulfillment_provider,node_search_service,node_index_storage,node_oidc_engine toneAmber
class node_gift_card_flow,node_credit_flow,node_orchestrator,node_distributed_transaction,node_transaction_step,node_transaction_storage,node_memory_workflow_storage toneMint
class node_admin_dashboard,node_admin_route_builder,node_admin_babel toneRose
class node_shopper toneIndigo
```

## Components

### Commerce interfaces

- [Commerce API](https://github.com/mrgreullr/medusa/tree/develop/packages/medusa/src/api): `packages/medusa/src/api`
- [Product routes](https://github.com/mrgreullr/medusa/blob/develop/packages/medusa/src/api/store/products/route.ts): `packages/medusa/src/api/store/products/route.ts`
- [Search routes](https://github.com/mrgreullr/medusa/blob/develop/packages/medusa/src/api/store/search/route.ts): `packages/medusa/src/api/store/search/route.ts`
- [Loyalty routes](https://github.com/mrgreullr/medusa/blob/develop/packages/plugins/loyalty/src/api/admin/gift-cards/route.ts): `packages/plugins/loyalty/src/api/admin/gift-cards/route.ts`

### Commerce capabilities

- [Commerce modules](https://github.com/mrgreullr/medusa/tree/develop/packages/modules): `packages/modules`
- [Fulfillment service](https://github.com/mrgreullr/medusa/blob/develop/packages/modules/fulfillment/src/services/fulfillment-module-service.ts): `packages/modules/fulfillment/src/services/fulfillment-module-service.ts`
- [Fulfillment provider](https://github.com/mrgreullr/medusa/blob/develop/packages/modules/fulfillment/src/services/fulfillment-provider.ts): `packages/modules/fulfillment/src/services/fulfillment-provider.ts`
- [Search service](https://github.com/mrgreullr/medusa/blob/develop/packages/modules/search/src/services/search-module-service.ts): `packages/modules/search/src/services/search-module-service.ts`
- [Index storage contract](https://github.com/mrgreullr/medusa/blob/develop/packages/core/types/src/index-data/storage-provider.ts): `packages/core/types/src/index-data/storage-provider.ts`
- [OIDC authentication](https://github.com/mrgreullr/medusa/blob/develop/packages/modules/providers/auth-oidc/src/engine/engine.ts): `packages/modules/providers/auth-oidc/src/engine/engine.ts`

### Workflow runtime

- [Gift card workflow](https://github.com/mrgreullr/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`
- [Store credit workflow](https://github.com/mrgreullr/medusa/blob/develop/packages/plugins/loyalty/src/workflows/store-credit/workflows/create-store-credit-accounts.ts): `packages/plugins/loyalty/src/workflows/store-credit/workflows/create-store-credit-accounts.ts`
- [Transaction orchestrator](https://github.com/mrgreullr/medusa/blob/develop/packages/core/orchestration/src/transaction/transaction-orchestrator.ts): `packages/core/orchestration/src/transaction/transaction-orchestrator.ts`
- [Distributed transaction](https://github.com/mrgreullr/medusa/blob/develop/packages/core/orchestration/src/transaction/distributed-transaction.ts): `packages/core/orchestration/src/transaction/distributed-transaction.ts`
- [Transaction steps](https://github.com/mrgreullr/medusa/blob/develop/packages/core/orchestration/src/transaction/transaction-step.ts): `packages/core/orchestration/src/transaction/transaction-step.ts`
- [Transaction storage](https://github.com/mrgreullr/medusa/blob/develop/packages/core/orchestration/src/transaction/datastore/abstract-storage.ts): `packages/core/orchestration/src/transaction/datastore/abstract-storage.ts`
- [In-memory workflow storage](https://github.com/mrgreullr/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`

### Admin experience

- [Admin dashboard](https://github.com/mrgreullr/medusa/blob/develop/packages/admin/dashboard/src/app.tsx): `packages/admin/dashboard/src/app.tsx`
- [Admin route generation](https://github.com/mrgreullr/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/mrgreullr/medusa/blob/develop/packages/admin/admin-vite-plugin/src/babel.ts): `packages/admin/admin-vite-plugin/src/babel.ts`

### Other components

- **Shopper or operator**

## Connections

- Shopper or operator → Commerce API: sends requests
- Commerce API → Product routes: routes requests
- Commerce API → Search routes: routes requests
- Commerce API → Loyalty routes: exposes extensions
- Commerce API → Commerce modules: uses commerce logic
- Commerce modules → Fulfillment service: includes fulfillment (evidence: `packages/modules/fulfillment/src/services/fulfillment-module-service.ts`)
- Fulfillment service → Fulfillment provider: calls provider (evidence: `packages/modules/fulfillment/src/services/fulfillment-module-service.ts`)
- Commerce modules → Search service: includes search
- Search service → Index storage contract: uses storage contract
- Loyalty routes → Gift card workflow: invokes workflow (evidence: `packages/plugins/loyalty/src/api/admin/gift-cards/route.ts`)
- Loyalty routes → Store credit workflow: invokes workflow
- Commerce modules → Transaction orchestrator: supports workflows
- Transaction orchestrator → Distributed transaction: coordinates execution (evidence: `packages/core/orchestration/src/transaction/distributed-transaction.ts`)
- Distributed transaction → Transaction steps: executes steps (evidence: `packages/core/orchestration/src/transaction/distributed-transaction.ts`)
- Distributed transaction → Transaction storage: persists checkpoints (evidence: `packages/core/orchestration/src/transaction/distributed-transaction.ts`)
- In-memory workflow storage → Transaction storage: implements storage contract
- Commerce modules → OIDC authentication: offers authentication (evidence: `packages/modules/providers/auth-oidc/src/engine/engine.ts`)
- Shopper or operator → Admin dashboard: manages commerce
- Admin dashboard → Commerce API: manages via API
- Admin route generation → Admin source parser: parses routes (evidence: `packages/admin/admin-vite-plugin/src/routes/generate-routes.ts`)
