Magento’s project & directory structure

It’s time to dive into Magento’s directory structure. After you install Magento, if you just look around at the files & folders, things can seem… daunting. Looking beyond the initial top-level directories, Magento has over 100,000 files and folders. This large number of directories stems from Magento's extensibility and flexibility features.

The amount of folders exist purely just to organize the codebase. You actually won’t be dealing with most of them, but it’s still important to know what the purpose is of each of these folders, if nothing else than to make you aware of what’s going on at a high-level.

Let’s look at the most important directories, which are app, pub, var and vendor.

Modules in app & vendor

The app directory contains custom modules & themes that you’ll be building. The app/code directory is for modules, and app/design is for themes.

It may surprise you to find these directories empty in new projects but don't worry - it's totally normal because we haven't started coding yet. Now you might wonder, how does Magento function if these directories are empty?”

The vendor directory contains all third-party modules installed with Composer, including Magento code. This is considered an “ephemeral” directory, which means that it is somewhat temporary. You shouldn’t ever place your files within this directory — that’s what the app directory is for. When Magento is deployed to staging & production servers, the vendor directory may be completely rebuilt from the configuration defined within the composer.json file, which is why we don’t place files here that are meant to stick around.

The vendor/magento directory contains all of the modules related to Magento, and they start with module-. Within each module directory you’ll find common subdirectories such as Block, Controller, etc, Model, and so on. Magento uniformly uses naming conventions, ensuring files are predictably placed. This is particularly crucial when navigating Magento's extensive filesystem.

The Magento Framework

The Magento Framework isn’t considered a module, but a separate set of core PHP classes and interfaces that provide the foundational functionality for building Magento modules.

The framework is located within the vendor/magento/framework directory, and contains code for things like routing, dependency injection, the data layer, events, plugins, caching, logging, configuration, and many other lower-level components. These classes don’t directly implement functionality, but provide an API and tools for modules to build on top of.

Much like other files in the vendor directory, you'll never modify these files. However, you will frequently reference them when building out your own modules.

Public Assets

The pub directory is known as the “web root”, which is the main directory the web server should point to. Rather than pointing to an index.php file in the core of your app, it’s a common practice to segregate web requests within a public directory. Segregating web requests enhances security by ensuring they can't access private files in the filesystem. Abiding by this best practice, Magento designates pub/index.php as the actual web entry point.

This setup means that the web server can't access static assets, like images or CSS, unless they're housed in the pub directory. Magento uses pub/static as the main directory that contains CSS and JavaScript that is requested by the server. These files are also generated from the source files located in app/design and vendor in a process called “static content deployment”. This just means that these files are generated from a script runs during code deployments, and keeping it separated like this will decrease page loading speeds.

Transient Data

The var directory contains generated data that changes often such as cache files, logs, and session files. This is a truly ephemeral directory and is just meant to store transient data. It’s best practice to have a separate directory like this for this temp data.

Other Folders

The other folders aren’t really used on a day-to-day basis, so you should breath a sigh of relief that you only really need to worry about those few main folders we talked about. While these important directories form the core, feel free to explore the rest of the filesystem, including the bin directory with the bin/magento CLI tool, the dev directory for unit tests, the lib directory for other frameworks, and the setup directory with install & upgrade scripts.

But don’t get overwhelmed with Magento’s giant codebase. Knowing about app, pub, var and vendor will usually be enough to get you through 95% of your daily Magento duties.