Skip to main content
Developer DocsDeveloper guide: Magento_Customer Architecture

Magento_Customer Architecture

Complete architectural overview of customer management in Magento 2.4.x with component diagrams and dependency mappings.

499 Components 123 Edges

Quick Stats

499
Total Nodes
123
Total Edges
2
Dependencies
2.4.x
Compatible

Module Overview

The Magento_Customer module is the foundational component for managing customer accounts, authentication, and customer data throughout the Magento ecosystem.

What Magento_Customer Does

Position in Magento Ecosystem

Architectural Layer: Foundation Module

The Customer module sits at the foundation layer of Magento's architecture, providing essential services to nearly all customer-facing and admin modules.

Direct Dependencies

Key Dependent Modules

Modules that depend on Magento_Customer:

• Magento_Sales
• Magento_Quote
• Magento_Checkout
• Magento_Wishlist
• Magento_Review
• Magento_Newsletter
• Magento_Catalog
• Magento_Tax

Service Contracts (API Layer)

The Customer module follows Magento's service contract pattern rigorously, exposing all functionality through well-defined interfaces.

Core Repository Interfaces

1. CustomerRepositoryInterface

Purpose: Main CRUD interface for customer entities

Location: Magento\Customer\Api\CustomerRepositoryInterface

Implementation: Magento\Customer\Model\ResourceModel\CustomerRepository

Key Methods:

PHP
save(CustomerInterface $customer, $passwordHash = null): CustomerInterface
get($email, $websiteId = null): CustomerInterface
getById($customerId): CustomerInterface
getList(SearchCriteriaInterface $searchCriteria): CustomerSearchResultsInterface
delete(CustomerInterface $customer): bool
deleteById($customerId): bool

2. AddressRepositoryInterface

Purpose: CRUD operations for customer addresses

Location: Magento\Customer\Api\AddressRepositoryInterface

Implementation: Magento\Customer\Model\ResourceModel\AddressRepository

3. AccountManagementInterface

Purpose: High-level account operations (authentication, password, activation)

Location: Magento\Customer\Api\AccountManagementInterface

Implementation: Magento\Customer\Model\AccountManagement

Key Methods:

PHP
createAccount(CustomerInterface $customer, $password = null, $redirectUrl = ''): CustomerInterface
authenticate($username, $password): CustomerInterface
changePassword($email, $currentPassword, $newPassword): bool
initiatePasswordReset($email, $template, $websiteId = null): bool
resetPassword($email, $resetToken, $newPassword): bool
isEmailAvailable($customerEmail, $websiteId = null): bool

4. GroupRepositoryInterface

Purpose: Customer group management

Location: Magento\Customer\Api\GroupRepositoryInterface

Database Schema

Primary Tables

customer_entity

Purpose: Main customer data (EAV entity)

Column Type Description
entity_id INT (PK) Customer ID
website_id INT Multi-website support
email VARCHAR(255) Unique per website
group_id INT FK to customer_group
created_at TIMESTAMP Account creation timestamp

customer_address_entity

Purpose: Customer addresses (EAV entity)

Key columns: entity_id (PK), parent_id (FK to customer_entity), city, country_id, region, postcode, street, telephone

customer_group

Purpose: Customer groups (for pricing, catalog rules)

System groups: 0 (NOT LOGGED IN), 1 (General), 2 (Wholesale), 3 (Retail)

EAV Tables

Customer and Address entities use standard EAV structure:

• customer_entity_datetime
• customer_entity_decimal
• customer_entity_int
• customer_entity_text
• customer_entity_varchar
• customer_address_entity_datetime
• customer_address_entity_decimal
• customer_address_entity_int

Extension Points

Plugin Intercept Points

The module provides 19 plugins for customization.

Critical Intercept Points:

  • 1. CustomerRepositoryInterface::save - Customer save operations
  • 2. AccountManagementInterface::authenticate - Login flows
  • 3. GroupRepositoryInterface - Group operations
  • 4. Framework\View\Layout - Frontend depersonalization for caching
  • 5. Framework\App\ActionInterface - Customer notification injection

Event-Based Extension Points

The module dispatches 7 core events:

Customer Lifecycle Events:

  • → customer_save_after_data_object (Primary save event)
  • → customer_address_save_before
  • → customer_address_save_after
  • → customer_customer_authenticated

Note: Customer delete events are not dispatched; use plugins on CustomerRepositoryInterface::delete() instead.

Authentication Events (Frontend):

  • → customer_login
  • → customer_logout
  • → customer_data_object_login

Performance Considerations

Caching Strategy

Database Performance

Key Indexes:

  • • CUSTOMER_ENTITY_EMAIL_WEBSITE_ID (email, website_id) - Unique constraint
  • • CUSTOMER_ENTITY_WEBSITE_ID - Website filtering
  • • CUSTOMER_ADDRESS_ENTITY_PARENT_ID - Customer's addresses lookup

Optimization Tips:

  • → Use getById() instead of get($email) when possible (primary key lookup)
  • → Batch operations with collections instead of repository in loops
  • → Consider custom indexers for complex customer searches

Security & Authorization

Password Management

Hashing: Uses Magento\Framework\Encryption\EncryptorInterface

Default Algorithm: Argon2ID13 (Magento 2.4+)

Password Reset: Token-based reset with configurable expiration (typically 1-24 hours)

Admin Access Control (ACL)

Resources defined in etc/acl.xml:

  • • Magento_Customer::manage - Main customer management permission
  • • Magento_Customer::customer - Customer operations
  • • Magento_Customer::group - Customer group management
  • • Magento_Customer::online - View online customers