Joomla File Structure Explained: What Every Folder Does

1. The Basics

1.1 The Root at a Glance

A standard Joomla 6 installation has this root (your uploads and a possible logs relocation aside, nothing else should be there):

administrator/    the backend application
api/              the Web Services application
cache/            generated page/system cache
cli/              the command-line entry point
components/       frontend components (the page builders)
files/            YOUR uploaded documents (Media Manager files area)
images/           YOUR uploaded media
includes/         bootstrap files for the frontend
language/         frontend language files
layouts/          shared render layouts (JLayout)
libraries/        the Joomla framework + vendor packages
media/            extension assets: css, js, fonts
modules/          frontend modules
plugins/          all plugins, grouped by type
templates/        frontend templates
tmp/              scratch space for installs and uploads

configuration.php your settings + credentials
index.php         the frontend entry point
htaccess.txt      Apache rules (rename to .htaccess)
web.config.txt    the IIS equivalent
robots.txt        crawler instructions
LICENSE.txt, README.txt   documentation

1.2 Three Kinds of Things

1.3 The One Rule Behind Every Other Rule

Updates replace code; they never touch data folders or your template overrides. That single fact explains the advice repeated across this whole article series: customisations go in overrides and user.css (survive updates), uploads go in images/ (survive updates), and edits inside code folders evaporate at the next release.

3. The Extension Folders

3.1 One Extension, Many Homes

An extension is not one folder - its pieces live where their function dictates. Take com_content, the article system:

components/com_content/                 frontend code + layouts
administrator/components/com_content/   backend code, forms, access.xml
media/com_content/                      its css/js assets
language/en-GB/com_content.ini          frontend language strings
administrator/language/en-GB/...        backend language strings
api/components/com_content/             its API endpoints

Modules follow the same split (modules/ and administrator/modules/), templates too (templates/ and administrator/templates/). Plugins are the exception: all plugins live in one place, plugins/{group}/{name}/, grouped by their type - system, content, authentication, task, and the other groups you have met across this series.

Inside each of those homes, a modern extension follows one internal pattern:

src/                    namespaced PHP classes (the autoload map's target)
tmpl/                   the layouts - overridable, per the overrides article
services/provider.php   registers the extension's services (DI wiring)
forms/                  XML form definitions for edit screens

And how does the installer know which folders an extension writes to? Every extension ships a manifest XML (the templateDetails.xml from the Cassiopeia article is one) that declares its files, folders, language files, and media - the installer reads it on install, update, and uninstall. Beware of old tutorials here: pre-Joomla 4 extensions used helper.php files and assets inside their own folders; the src/-plus-services/ pattern is the current one.

3.2 layouts/: the Shared Ones

The root layouts/ folder holds render layouts shared by everything - pagination, custom fields, form fields. The overrides article covers how LayoutHelper finds them and how your template can override each one.

3.3 language/ and Overrides

Language files install into language/{tag}/ per client. Your own text changes do not belong in those files (updates replace them) but in language overrides, managed in the backend and stored under language/overrides/ - the same survive-the-update pattern as template overrides.

5. The Data Folders

5.1 What Runtime Writes

• cache/ and administrator/cache/: generated cache. Safe to empty (System → Clear Cache), never delete the folders themselves. One special file lives here: administrator/cache/autoload_psr4.php, the class map from the troubleshooting article.
• tmp/: scratch space for extension installs and uploads. Empty it freely; a wrong tmp_path is the classic install failure.
• administrator/logs/: Joomla's log files - update logs, the failed-login log, everything the rotatelogs task rotates.

5.2 Move Them Out (Security Article, Applied)

The paths of tmp/ and the log folder are configurable in the Global Configuration precisely so you can move them outside the web root, and the security hardening article recommends exactly that. The public-folder layout in section 9.3 takes the same idea to its conclusion.

5.3 configuration.php

One file is the site's identity: database credentials, the $secret key, every Global Configuration value. It sits in the root, it is in every backup, it never goes in version control or a support ticket, and the security article's advice to make it read-only (444) applies. If configuration.php plus images/ plus the database survive, your site survives.

7. libraries/: the Framework Itself

7.1 Two Halves

• libraries/src/: the Joomla CMS classes - every Joomla\CMS\... class you have seen in this series (Authentication, Access, LayoutHelper, Log) maps to a file here.
• libraries/vendor/: third-party packages managed via Composer - the Joomla Framework packages, the database layer, PSR interfaces, and libraries like TUF for update verification.

7.2 Read Freely, Write Never

libraries/ is the best Joomla documentation there is - this whole article series verified its claims by reading these files. But it is also the folder where "quick fixes" do the most damage: an edit here affects everything, disappears on update, and (per the troubleshooting article) a modified core file is indistinguishable from a hack in an audit. Read daily; write never.

9. Under the Hood (Developer View)

9.1 The JPATH Constants

includes/defines.php names every location once, and all core code uses the names - which is why relocating folders works at all:

JPATH_ROOT           the installation root
JPATH_SITE           frontend application root
JPATH_ADMINISTRATOR  the administrator/ folder
JPATH_API            the api/ folder
JPATH_LIBRARIES      libraries/
JPATH_PLUGINS        plugins/
JPATH_THEMES         the active client's templates folder
JPATH_CACHE          the active client's cache folder
JPATH_MANIFESTS      administrator/manifests/
JPATH_PUBLIC         the web-served root (defaults to JPATH_ROOT)

In your own code, always build paths from these constants - JPATH_ROOT . '/images/...' - never from guessed relative paths.

9.2 From Namespace to File

Joomla autoloads classes by mapping namespaces to folders. The generated map in administrator/cache/autoload_psr4.php shows the pattern literally:

Joomla\CMS\...                          → libraries/src/...
Joomla\Component\Content\Site\...       → components/com_content/src/...
Joomla\Component\Content\Administrator\ → administrator/components/com_content/src/...
Joomla\Plugin\System\Debug\...          → plugins/system/debug/src/...

Read a namespace, know the file; read a path, know the namespace. This mapping is also why deleting the stale cached map fixes the troubleshooting article's "class not found" mysteries: the map said one thing, the disk another.

9.3 JPATH_PUBLIC and the Public-Folder Layout

JPATH_PUBLIC exists for the layout the security article recommends for new sites: only the entry points and web assets in the served folder, everything else - code, configuration, logs - one level above the web root, out of any URL's reach. On a classic install the constant simply equals JPATH_ROOT; the tree in this article is the classic layout.

11. SEO and Metadata

The file tree touches SEO at its edges, and the edges matter. Everything under the web root is potentially crawlable: a forgotten old/ copy of the site gets indexed as duplicate content, a stray database dump can end up in search results (it happens - and it is a data leak first, an SEO issue second), and robots.txt - sitting in the root, as covered in its own article - is your instrument for steering crawlers away from what should not be indexed.

The positive side lives in images/: descriptive folder and file names (images/products/blue-widget.webp beats images/IMG_4711.jpg) carry ranking weight for image search, and a tidy images tree keeps editors choosing the right, optimised file instead of re-uploading duplicates - the performance article's image discipline starts with folder discipline.

13. Best Practices

If you remember only a few things from this article, remember these:

• Learn the three kinds: entry points and code belong to Joomla; images/, configuration.php, and the runtime folders are the site's data.
• Uploads in images/, custom assets in your child template's user.css, markup changes in html/ overrides, text changes in language overrides.
• Never write inside code folders - libraries/ is for reading.
• Keep the root exactly as shipped: every extra file is a question, and backups live outside the tree entirely.
• Move tmp/ and logs out of the web root; consider the public-folder layout for new sites.
• Build paths from JPATH_* constants in code, and read namespaces as directions to files.
• When in doubt whose folder it is: check whether an update or installer would write there.

15. Summary

Joomla's file structure is a small system of contracts:

• Three kinds of content: entry points, code, and data - and only data (plus your overrides) is yours to write.
• Four doors: site, administrator, API, CLI - one codebase, four thin entry points.
• Extensions live distributed: frontend, backend, media, language, and API pieces each in the folder their function dictates; plugins grouped by type in one tree.
• The critical distinction: images/ is your media, media/ is extension assets - with user.css and child template folders as the deliberate exceptions.
• Runtime folders (cache/, tmp/, logs) are disposable in content, essential in existence, and best moved out of the web root.
• For developers: JPATH_* constants name every location, namespaces map to paths, and the public-folder layout takes the web server out of reach of everything but the entry points.

Once the map is in your head, half this article series gets simpler: overrides, hardening, backups, and troubleshooting all become applications of "whose folder is this, and who writes there?".

And if a site's tree has grown mysterious over the years - stray files, duplicate copies, customisations nobody can place - a file-structure audit against a clean Joomla is methodical, satisfying work: everything explained, relocated, or removed. It is precisely the kind of spring cleaning a Joomla specialist does before every migration, and the site is safer and lighter afterwards.