MedusaGo's Architecture

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

MedusaGo has the same architecture as Medusa. The layers, the way they depend on each other, and the HTTP API they expose are identical. What changes is the implementation: each layer is written in Go.

HTTP, Workflow, and Module Layers#

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

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

API Routes (HTTP): API routes are the typical entry point. The server is built on Go's net/http package, with a middleware and route stack that matches the behaviour of Medusa's HTTP layer. It can also connect to Redis, which 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 data store, which is a PostgreSQL database.

Code
Storefront / Admin / other clients
              |
              v
   API routes (HTTP layer)
              |
              v
   Workflows (business logic)
              |
              v
   Modules (domain logic and data)
              |
              v
          PostgreSQL

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

Database Layer#

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

MedusaGo only supports PostgreSQL as the underlying database. It talks to it with the pgx driver and its own data access layer, so the database it reads and writes is the same one that Medusa uses. You can also integrate other databases in a custom module.

Note: Modules can be implemented within plugins.

Third-Party Integrations Layer#

Third-party services and systems are integrated through MedusaGo's Commerce and Infrastructure Modules. For other third-party services, create a custom integration in a custom module.

Commerce Modules#

Commerce Modules integrate third-party services relevant to commerce or user-facing features through module providers. MedusaGo includes, for example:

Payment providers: Stripe and Adyen.
Fulfillment provider: a manual provider.
Auth providers: email and password, GitHub, and Google.
Notification providers: a local provider that logs notifications, and SendGrid.

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

Infrastructure Modules#

Infrastructure Modules integrate third-party services and systems that customise MedusaGo's infrastructure. MedusaGo has the following Infrastructure Modules, each with a development default and, where relevant, a production implementation:

Module	Purpose	Implementations
Event Module	A pub/sub system that allows you to subscribe to events and emit them.	In-process (default), Redis
Workflow Engine Module	Orchestrates workflows, including long-running ones and scheduled jobs.	In-memory (default), Redis
Locking Module	Manages access to shared resources by multiple processes, preventing conflicts and ensuring data consistency.	In-memory (default), PostgreSQL, Redis
Caching Module	Caches data that requires heavy computation.	In-memory, Redis
File Module	Manages file uploads and storage, such as product images.	Local disk (default), S3
Notification Module	Sends notifications to customers and users, such as order updates.	Local (default), SendGrid
Analytics Module	Tracks and analyses user interactions and system events.	Local, PostHog
Search Module	Indexes and searches data with a search provider.	PostgreSQL

The Deployment guide shows how to configure the production implementations.

Note: Modules can be implemented within plugins.

The Admin Dashboard#

The Medusa Admin is a React application that sends requests to the Admin API routes, like any other client. MedusaGo embeds a prebuilt copy of the dashboard in its binary and serves it at /app (configurable with the admin.path option). So you don't deploy the dashboard separately.

If you add admin customisations, build compiles the dashboard with your widgets and UI routes. Learn more in the Build chapter.

Full Diagram of MedusaGo's Architecture#

Code
Clients: Storefront (JS SDK / REST), Medusa Admin (/app), other systems
                              |
                  HTTP layer (/store, /admin, /auth, /hooks)
                              |
                          Workflows
                              |
        Commerce Modules                Infrastructure Modules
  (product, cart, order, payment, ...)  (event, workflow engine, locking,
                              |          caching, file, notification, ...)
                              |                     |
                         PostgreSQL        Redis, S3, SendGrid, ...

Found a problem with this page?Report Issue

Edited Nov 14·Edit this page