Core Architecture

Purpose and Scope

This document provides a high-level deep dive into Maho's foundational architecture patterns and systems. It explains the structural relationship between the central hub, the configuration tree, and the modular extensibility of the platform.

Detailed technical documentation for each subsystem can be found in the following child pages:

• Application Bootstrap — Detailed initialization sequence, Mage::run(), and the application lifecycle.
• Request Flow and Front Controller — Routing logic, controller dispatch, and the response generation pipeline.
• Configuration System — Comprehensive guide to config.xml, system.xml, XML merging, and multi-source loading.
• Layout System — XML-driven view layer, block hierarchy, and the rendering pipeline.
• Module System — Module declaration, dependency resolution, and structural standards.
• Event System and Observers — Event dispatching mechanism and the observer pattern.
• Factory Pattern and Object Instantiation — Mage::getModel(), getSingleton(), and class rewrite logic.
• Store and Multi-Store Architecture — Website/Store/Store View hierarchy and scope-based configuration.

The Mage Static Hub

The Mage class app/Mage.php18-121 is the central orchestration point. It is a final class that provides static access to the application instance, configuration, and factory methods. It serves as the primary entry point for almost all internal logic.

Core Registry and Properties

The class maintains several critical static properties that represent the state of the running application:

Property	Type	Purpose
$_app	Mage_Core_Model_App	The application model managing the request lifecycle app/Mage.php71
$_config	Mage_Core_Model_Config	The merged XML configuration tree app/Mage.php78
$_events	\Maho\Event\Collection	Collection of registered observers for event dispatching app/Mage.php85
$_registry	array	A global key-value store for shared objects app/Mage.php57

Mage Static Hub Architecture

Sources: app/Mage.php18-137

Factory Pattern and Class Resolution

Maho uses string aliases (e.g., tax/observer) to instantiate classes. This abstraction allows the system to support Class Rewrites, where a module can override a core class by changing the configuration without touching the original core file.

Object Instantiation Workflow

When Mage::getModel('tax/observer') is called, the following resolution occurs:

1. Prefix Resolution: The system identifies tax as the group and observer as the class entity.
2. Configuration Lookup: It checks global/models/tax/class in the merged XML to find the base class name (e.g., Mage_Tax_Model) app/code/core/Mage/Tax/etc/config.xml19-23
3. Rewrite Check: It checks for any <rewrite> nodes under that group in the configuration app/code/core/Mage/Core/Model/Config.php115-128
4. Instantiation: The final class name (e.g., Mage_Tax_Model_Observer) is generated, cached in $_classNameCache app/code/core/Mage/Core/Model/Config.php118 and instantiated.

Code Entity Mapping: Factory to Class

Sources: app/code/core/Mage/Core/Model/Config.php114-128 app/code/core/Mage/Tax/etc/config.xml19-23

Configuration System

The Mage_Core_Model_Config class app/code/core/Mage/Core/Model/Config.php13-73 aggregates XML files from the core, community, and local pools into a single searchable tree.

Merging Hierarchy

1. Base Configuration: app/etc/*.xml (including local.xml for DB credentials).
2. Module Configuration: etc/config.xml from every active module defined in MAGE_MODULES app/code/core/Mage/Core/Model/Config.php15-73
3. Database Overrides: Values stored in the core_config_data table, accessed via the resource model app/code/core/Mage/Core/Model/Config.php236-242

Cache Sections

To improve performance, the configuration is split into sections that can be cached independently app/code/core/Mage/Core/Model/Config.php91-97:

• adminhtml, crontab, install, stores, websites.

Sources: app/code/core/Mage/Core/Model/Config.php13-98

Event-Driven Extensibility

Maho provides a robust event system via Mage::dispatchEvent(). In addition to traditional XML-based observer registration, Maho introduces PHP Attributes for observer registration lib/Maho/Config/Observer.php26-28

Observer Types

• XML Observers: Registered in a module's config.xml app/code/core/Mage/Tax/etc/config.xml101-148
• Attribute Observers: Registered using the #[Maho\Config\Observer] attribute directly on methods lib/Maho/Config/Observer.php26-46 These are repeatable and allow specifying areas, instantiation types, and replacements lib/Maho/Config/Observer.php39-45 Examples include cron status checks app/code/core/Mage/Cron/Model/Observer.php35-36 and inventory management app/code/core/Mage/CatalogInventory/Model/Observer.php44-45

Event Flow Diagram

Sources: app/Mage.php85 app/code/core/Mage/CatalogInventory/Model/Observer.php44-45 lib/Maho/Config/Observer.php27

Multi-Store Architecture

The platform is designed for multi-tenancy using a hierarchical structure of Websites, Store Groups, and Store Views.

• Website: The highest level (e.g., separate domains) app/code/core/Mage/Core/Model/App.php81
• Store Group: Manages the root category and grouping of views app/code/core/Mage/Core/Model/App.php153
• Store View: The actual locale layer represented by Mage_Core_Model_Store app/code/core/Mage/Core/Model/App.php159

Configuration values can be set at any level of this hierarchy, with the most specific (Store View) overriding the more general (Website or Default) app/code/core/Mage/Core/Model/Config.php95-96 The application initializes the current store during bootstrap app/code/core/Mage/Core/Model/App.php268

Sources: app/code/core/Mage/Core/Model/Config.php91-97 app/code/core/Mage/Core/Model/App.php79-160 app/code/core/Mage/Core/Model/App.php268

Summary of Core Classes

Class Name	File Path	Primary Responsibility
Mage	app/Mage.php	Global static hub and factory.
Mage_Core_Model_Config	app/code/core/Mage/Core/Model/Config.php	Loads, merges, and caches XML configuration.
Mage_Core_Model_App	app/code/core/Mage/Core/Model/App.php	Manages application state, stores, and request lifecycle app/code/core/Mage/Core/Model/App.php248-271

For a deep dive into how these systems initialize, proceed to Application Bootstrap.