Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 42 ยท Getting Started

Architecture and Directory Layout

Tour the Magento 2 folders (app/code, vendor, pub, var, generated), follow a request from index.php to a response, and learn what the three deploy modes change.

Open a fresh Magento project and you will find dozens of folders. Some you edit every day, some you must never touch, and some are created and deleted by Magento itself. Knowing which is which saves hours, because a large share of "Magento is broken" problems turn out to be a stale file in generated/ or var/ or a permission problem in pub/.

This lesson draws the map. You will learn what each top-level folder is for, how a single HTTP request travels through the application, why everything is organised in modules, and what the deploy modes (default, developer, production) change. The examples use stand-ins: a directory walker and a miniature request pipeline.

The top-level folders

A project created with Composer looks roughly like this (names are stable across 2.4.x, but a given release may add or omit a few entries):

TEXT
project/
  app/
    code/          your modules: Vendor/Module
    design/        your themes: frontend/Vendor/theme
    etc/           config.php, env.php (project configuration)
    i18n/          language packs
  bin/magento      the command line tool
  dev/             developer tools and tests
  generated/       code Magento writes for you (do not edit)
  lib/             framework resources (JavaScript, CSS, internal libraries)
  pub/             the web root
    static/        CSS, JS and images served to browsers
    media/         product images and uploads
  setup/           installer
  var/             logs, caches, sessions, temporary files
  vendor/          Composer packages, including vendor/magento/*

The ones you work in are few:

  • app/code holds your modules. A module called Acme_Hello lives in app/code/Acme/Hello. This is where almost all customisation code goes.
  • app/design holds your themes, which change how the storefront looks.
  • app/etc holds config.php (the list of enabled modules and some shared settings) and env.php (the database credentials and other settings that differ per server). env.php contains secrets and must never be committed to a public repository.

The ones you read but do not edit:

  • vendor/magento contains the core. Composer owns it. In a standard project the core modules are installed here as packages rather than in app/code.
  • generated/ contains PHP classes that Magento creates on demand: factories, proxies and interceptors. You will meet them in Factories, Proxies and Generated Code. It is safe to delete, and Magento rebuilds it.
  • var/ holds logs (var/log/system.log, var/log/exception.log), caches and temporary data. When something fails, look in the logs first.

And one that matters for security: pub/ is meant to be the web server's document root. Pointing the web server at the project root instead exposes app/etc/env.php and other sensitive files to the internet. Any setup guide that says "document root = project folder" is wrong for Magento 2.

Always configure your web server so that the document root is pub/. Serving the project root is a well-known cause of leaked configuration files.

PHP A directory walker

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Everything is a module

Magento's central design idea is that each feature is a module: catalog, checkout, customer, tax, sales, the admin panel and so on are separate modules with their own folder. A module owns its PHP classes, its XML configuration, its templates and its database tables. Modules communicate through interfaces and events instead of reaching into each other's internals, and your own code joins the application the same way core code does.

This is the reason you can customise so much without editing the core: a module can add configuration, swap classes, wrap methods and add layout changes just by shipping XML files that Magento discovers and merges. Your First Module shows the minimum a module needs.

Following a request

When a browser asks for a page, the web server hands the request to pub/index.php. From there the flow is, in simplified form:

flowchart TD
    A["pub/index.php"] --> B["Bootstrap creates the application"]
    B --> C["Front controller"]
    C --> D["Router chain<br/>(CMS, standard, default)"]
    D --> E["Matching controller action"]
    E --> F["Result object<br/>(page, JSON, redirect)"]
    F --> G["Response sent to browser"]

A request enters at index.php, finds an action through the routers, and leaves as a response built from a result object.

The front controller asks each router in turn whether it recognises the URL. The standard router maps a path like /hello/index/world to a module's controller class. The action returns a result such as a page, JSON or a redirect, and the framework turns it into the HTTP response. Routing and Controllers and Request, Response and Result Types cover each step in depth.

Before any of that, Magento also loads configuration for the current area (storefront, admin and so on), builds the dependency-injection configuration, and consults caches. The next few lessons unpack these.

PHP A miniature request pipeline

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Deploy modes

Magento runs in one of three modes, and the choice changes performance, error handling and how generated code is treated:

Mode Used for What it does
default A fresh install before you choose Works, but not tuned for development or production
developer Your local machine Shows errors, generates code and static files on demand, slower
production Live stores Hides errors from visitors, expects code and static files to be pre-built, fastest

You inspect and change the mode with the command line tool:

Terminal
bin/magento deploy:mode:show
bin/magento deploy:mode:set developer
bin/magento deploy:mode:set production

Switching to production runs compilation and static content steps, so it takes a while, and a production site should not be changed by hand afterward. Deployment and Upgrades covers the full production routine. For learning, use developer mode.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where does your own module code normally live in a standard Composer project?

    Custom modules go in app/code under a vendor folder and a module folder. vendor/ belongs to Composer and pub/static and var/ hold generated or runtime files.
  2. 2. Why should the web server document root be pub/ rather than the project folder?

    Exposing the project root can leak configuration and secrets. pub/ contains only what browsers should reach.
  3. 3. What can you safely do with the generated/ folder?

    generated/ holds code Magento writes (factories, proxies, interceptors). It is rebuilt on demand or by compilation, so never edit it.
  4. 4. Which mode is meant for a live store?

    Production mode hides errors from visitors and expects compiled code and deployed static files for best speed.

Summary

  • Edit app/code and app/design; read var/ logs; leave vendor/ and generated/ alone.
  • app/etc/env.php holds per-server secrets, and the document root must be pub/.
  • Magento is built from modules that talk through interfaces, events and merged XML.
  • A request goes pub/index.php, bootstrap, front controller, routers, an action, a result, a response.
  • Use developer mode locally and production mode on live stores.

Next: Setting Up a Development Environment