1.3. Medusa's Architecture

In this chapter, you'll learn about the architectural layers in Medusa.

Tip: Find the full architectural diagram at the end of this chapter.

HTTP, Workflow, and Module Layers#

Medusa is a headless commerce platform. So, storefronts, admin dashboards, and other clients consume Medusa's functionalities through its API routes.

In a common Medusa application, requests go through four layers in the stack. In order of entry, those are:

API Routes (HTTP): Our API Routes are the typical entry point. The Medusa server is based on Express.js, which handles incoming requests. It can also connect to a Redis database that stores the server session data.
Workflows: API Routes consume workflows that hold the opinionated business logic of your application.
Modules: Workflows use domain-specific modules for resource management.
Data store: Modules query the underlying datastore, which is a PostgreSQL database in common cases.

Note: These layers of stack can be implemented within plugins.

This diagram illustrates the entry point of requests into the Medusa application through API routes. It shows a storefront and an admin that can send a request to the HTTP layer. The HTTP layer then uses workflows to handle the business logic. Finally, the workflows use modules to query and manipulate data in the data stores.

Database Layer#

The Medusa application injects into each module, including your custom modules, a connection to the configured PostgreSQL database. Modules use that connection to read and write data to the database.

Note: Modules can be implemented within plugins.

This diagram illustrates how modules connect to the database.

Third-Party Integrations Layer#

Third-party services and systems are integrated through Medusa's Commerce and Architectural modules. You also create custom third-party integrations through a custom module.

Note: Modules can be implemented within plugins.

Commerce Modules#

Commerce modules integrate third-party services relevant for commerce or user-facing features. For example, you can integrate Stripe through a Payment Module Provider, or ShipStation through a Fulfillment Module Provider.

You can also integrate third-party services for custom functionalities. For example, you can integrate Sanity for rich CMS capabilities, or Odoo to sync your Medusa application with your ERP system.

You can replace any of the third-party services mentioned above to build your preferred commerce ecosystem.

Diagram illustrating the commerce modules integration to third-party services

Architectural Modules#

Architectural modules integrate third-party services and systems for architectural features. Medusa has the following Architectural modules:

Workflow Engine Module: Orchestrates workflows that hold the business logic of your application. You can integrate Redis to orchestrate workflows.
Cache Module: Caches data that require heavy computation. You can integrate a custom module to handle the caching with services like Memcached, or use the existing Redis Cache Module.
Event Module: A pub/sub system that allows you to subscribe to events and trigger them. You can integrate Redis as the pub/sub system.
File Module: Manages file uploads and storage, such as upload of product images. You can integrate AWS S3 for file storage.
Notification Module: Sends notifications to customers and users, such as for order updates or newsletters. You can integrate SendGrid for sending emails.

All of the third-party services mentioned above can be replaced to help you build your preferred architecture and ecosystem.

Diagram illustrating the architectural modules integration to third-party services and systems

Full Diagram of Medusa's Architecture#

The following diagram illustrates Medusa's architecture including all its layers.

Full diagram illustrating Medusa's architecture combining all the different layers.

Was this chapter helpful?