Medusa Architecture & Structure | Medusa Development Course

Welcome to our Medusa Development Course! In this series, you'll learn how to get your development environment ready and take your first steps in building a Medusa-powered e-commerce application. We'll walk you through everything step by step, helping you master Medusa’s modular architecture and build the key features you need.

This course was made by Viktor Holik, our Software Engineer and Medusa Expert.

In this episode of our course, we’ll explore the headless architecture of Medusa and the project structure, like directory, folders and files.

Medusa Architecture & Structure

You can find the transcription of the guide below.

In this section, I will talk about the headless architecture of Medusa and the project structure.

But before doing that, I'll actually show you a diagram. On the left side of this diagram, you have the storefront. The storefront is running in the customer's browser and is used for listing, updating carts, adding some products to the cart, making orders, and others, as you've seen in the previous chapter. The storefront utilizes the Medusa backend to actually perform these actions via the API.

So, I would like you to imagine that Medusa is just a backend API that contains all of the logic behind the storefront and the admin panel. In the Medusa backend, you also have an admin panel that is attached to this backend.

Let's go to the directory where we initialized Medusa. As you can see, we have two folders: medusa-test-storefront and medusa-test. We will not focus too much on the medusa-test-storefront folder, but you should keep in mind that it's just a template for the storefront that the Medusa core team created for you to use.

In our medusa-test folder, we have 4 different tsconfigs, each for different environments, like admin, the server, and also for testing.

In the package.json file, we have all the necessary dependencies for Medusa to run. It also contains the jest config to run unit tests and scripts to build, clean, and run, each Medusa component like admin and server.

The medusa-config.js contains the config for Medusa to run. For example, here we read the environment variables based on the NODE_ENV. We also have a CORS configuration, like ADMIN_CORS and STORE_CORS. There is also the database URL, an array of plugins, some JWT information, cookie information, and the REDIS_URL, which is now disabled but is recommended for production use.

The index.js file is an entry point for Medusa to start. It's not actually running when you use the Medusa develop or Medusa start commands. It's just for specific use cases like some managers, such as PM2.

We also have some environment variables files and their templates.

The uploads is a folder that the Medusa file local plugin uses to upload images to.

The dist folder contains the output of builds for the Medusa server API, and the build folder contains the build admin panel.

The data folder contains the seed data that we can use to seed something - for example, products, users, or categories. We can do this by running the command yarn seed, and this command will read this data and actually seed it into the Medusa backend database.

The src folder contains multiple subfolders, like types, in which we have types for the onboarding feature. We also have subscribers, services, repositories, and models, which I will talk about in more detail in future chapters.

Here, we also have a migration folder, which contains some of the migrations for the database, like creating and updating tables.

We also have an API folder, which contains some custom endpoints, like the onboarding one, which is default in Medusa.

Lastly, there is an admin folder, which is used to extend the admin panel with some custom components, like for example onboarding flow component, which you have seen in the previous chapter.

In short

That concludes our dive into Medusa’s architecture! Now that you understand how the folders interact, you’re ready to start building out more advanced features.

In the next episode, we’ll master advanced configuration options

We hope you found Viktor's tutorial insightful and helpful.