1.01

Describe Magento File Structure

Understanding the foundational Magento file structure is essential for locating code, configuration, and assets quickly.

Why This Matters: Magento is highly structured, and knowing where files reside helps you navigate the codebase efficiently and follow best practices.

Visual Overview

mindmap root((Magento Root)) app/ code design etc i18n bin/ magento CLI generated/ Auto-generated pub/ Document root media static var/ Temporary cache log vendor/ Composer Never modify

Root Directory Structure

The root Magento directory contains several primary folders, each serving a specific purpose:

Core Configuration and Code Areas

app/code

This is where your custom modules are found.

Best Practice: Third-party modules should NOT be installed here. Use Composer instead, as it allows automatic dependency updates.

Why? Installing modules via app/code makes it difficult to keep them up-to-date.

app/design/[frontend|adminhtml]

This directory stores themes for the frontend and admin areas.

  • app/design/frontend - Customer-facing themes
  • app/design/adminhtml - Admin panel themes
app/i18n

Location for translation (language) packages.

Used for multi-language store configurations.

app/etc/

Stores critical configuration files:

app/etc/env.php

Important: Contains environment-specific configuration (database, Redis, AMQP).
⚠️ Should NOT be included in Git - contains sensitive information!

Configuration includes:

  • Database connection details
  • Redis configuration
  • Advanced Message Queuing Protocol (AMQP) settings

app/etc/config.php

Should be committed to Git repository

Contains:

  • Module enable/disable configuration
  • Store configuration defaults
  • Theming configuration

Merges with env.php at runtime.

Application Execution and Tools

bin/

Contains the bin/magento file - the command-line interface (CLI) tool.

Used constantly by developers for tasks like:
  • Cache management: bin/magento cache:flush
  • Module management: bin/magento module:enable
  • Setup commands: bin/magento setup:upgrade
dev/

Contains configuration for built-in tools:

  • Grunt configuration
  • Magento's test suite
generated/

Files are automatically created by Magento.

Best Practice: These files should be built during the deployment process using CI/CD.

Contains:

  • Factory classes
  • Interceptor classes (required for plugins)
  • Proxy classes (used for lazy-loading)
  • Extension attribute interfaces/classes
lib/

Contains internal libraries that Magento relies on.

Example: jQuery is located in lib/web/jquery/

setup/

Contains files related to installing Magento.

Preferred Method: Use CLI command bin/magento setup:install
❌ Avoid using the /setup URL in production

Web Root and Assets

pub/

This should be the HTTP root for the webserver.

Security: Setting document root to /pub helps prevent exposing sensitive folders like var/

How it works:

  • When a user requests a URL, if the exact file doesn't exist, the webserver rewrites to pub/index.php
  • This starts the Magento request

pub/media/

Where the website's images are stored.

pub/static/

Contains processed files (.css, .js, .html) ready for end-users to download.

  • Developer mode: Files are symlinked using bin/magento dev:source-theme:deploy
  • Production mode: Files are processed and copied using bin/magento setup:static-content:deploy
⚠️ Do NOT delete the .htaccess file in this directory - it prevents theme files from downloading!

Temporary and Third-Party Directories

var/

Stores temporary files used by Magento or generated by the application.

Examples:

  • var/log/ - Application logs
  • var/report/ - Error reports
  • var/cache/ & var/page_cache/ - File-system cache
Important: This directory can be deleted at any time - never store critical data here!
Scaling Limitation: Using file-system caches in this directory prevents horizontal scaling (running Magento on multiple instances).
vendor/

Where all Composer-installed modules are located.

This directory can be deleted and recreated by running composer install
⚠️ CRITICAL: NEVER modify code in the vendor/ directory!
Any changes will be destroyed the next time composer update or composer install runs.

Quick Reference Table

Directory Purpose Key Points
app/code Custom modules Use Composer for 3rd-party modules
app/design Themes Frontend & adminhtml themes
app/etc/env.php Environment config ❌ DO NOT commit to Git
app/etc/config.php Module config ✅ Should commit to Git
bin/ CLI tools Contains bin/magento
generated/ Auto-generated code Factories, interceptors, proxies
pub/ Web root Should be HTTP document root
var/ Temporary files Can be deleted anytime
vendor/ Composer packages ⚠️ NEVER modify directly

Exam Tips

Key Points to Remember

  • Know which files should/shouldn't be committed to version control
  • Understand the difference between env.php and config.php
  • Remember that pub/ should be the document root for security
  • Understand that vendor/ code should never be modified
  • Know where generated code is stored and when it's created
  • Understand the purpose of the var/ directory and its scalability limitations
Back to Overview Next: 1.02 Module Structure