Adobe Commerce Architect Master cheat sheet

Layered model: presentation (storefront/Admin), service contracts (API layer), domain (modules), persistence (resource models) - modules must depend downward only.

Service contracts are PHP interfaces in the module's Api/ directory; calling them instead of concrete classes keeps customizations upgrade-safe.

declarative schema (db_schema.xml) is the source of truth for tables; SchemaListener diffs it against the DB during setup:upgrade.

di.xml configuration merges across modules by area (global, frontend, adminhtml, webapi_rest); later module load order overrides earlier preferences.

Module load order is defined by app/etc/config.php sequence plus sequence entries in module.xml; ordering matters for plugin and preference resolution.

A preference (di.xml) replaces an implementation globally per interface; a plugin intercepts a single method - prefer plugins for behavior, preferences for substitution.

Areas (frontend, adminhtml, webapi_rest, crontab, graphql) each bootstrap a separate ObjectManager scope; code must not assume a single request lifecycle.

Magento Open Source and Adobe Commerce share the core; Commerce adds B2B, staging/content staging, and cloud-only features - architecture decisions must account for edition.

Minimum module: registration.php, etc/module.xml, and a composer.json with name/type magento2-module for Composer-based installs.

Plugin order: before (return value may be modified array), around (must call $proceed), after (receives result) - around plugins are the most expensive and least composable.

Observers are event-driven and fire for all dispatched events; plugins are method-specific - choose observers for cross-cutting side effects, plugins for behavior injection.

A module's etc/di.xml preferences and plugins apply globally unless scoped to an area directory (etc/frontend/di.xml).

CLI commands extend Symfony Command and are registered in etc/di.xml under Magento\Framework\Console\CommandList - commands are not auto-discovered.

Cron jobs are declared in etc/crontab.xml with a job group; the group must exist in etc/cron_groups.xml or the job silently never runs.

setup:upgrade runs data and schema patches in order of setup_version/schema version; patches are recorded in the patch_list and setup_module tables.

Use dependency injection via constructor, not ObjectManager::getInstance(), to keep classes testable and compatible with compiled DI.

EAV entities (product, customer, category) split data across entity, attribute, and value tables (catalog_product_entity_varchar, _int, _decimal, _text, _datetime).

Flat catalog tables (catalog_product_flat_*) are denormalized read models; they trade storage and index time for storefront read speed.

Indexers write to index tables (e.g., catalog_product_index_price); a 'reindex required' state means storefront reads may be stale.

Declarative schema: db_schema.xml defines tables/columns/indexes/constraints; db_schema_whitelist.json records intentional changes for backward compatibility.

Foreign keys and unique constraints belong in db_schema.xml constraints, not raw SQL, so schema diffs stay reproducible across environments.

Quote/order data uses quote, quote_item, sales_order, sales_order_item with entity_id and increment_id; joins must respect store_id scoping.

Staging (Commerce) stores scheduled versions in *_cl tables (e.g., catalog_product_entity_cl) linked to staging_update - reads must resolve the active version.

Multi-source inventory (MSI) splits stock across inventory_source_item and aggregates via inventory_stock_sales_channel; legacy cataloginventory_stock is not authoritative.

REST endpoints are declared in webapi.xml with a service method, route, HTTP verb, and ACL resource; the route maps to a service contract method.

GraphQL schema is built from etc/schema.graphqls per module; resolvers implement Magento\Framework\GraphQl\Schema\ResolverInterface.

Authentication: OAuth 1.0a for third-party apps, bearer tokens (integration/admin/customer tokens) for API calls, and session for storefront.

Asynchronous integration uses the message queue (RabbitMQ) via etc/queue_consumer.xml and etc/communication.xml; publishers should not block the request.

webapi.xml ACL () enforces authorization; omitting it exposes the endpoint to anonymous callers.

Bulk APIs (async/bulk routes) accept arrays and process via message queue - use them for high-volume catalog/price pushes.

API rate limiting and response caching are configured at the web server/CDN layer; Magento itself does not throttle REST by default.

Extension attributes (extension_attributes.xml) add fields to existing service contract DTOs without modifying core interfaces.

Full-page cache (FPC) stores rendered HTML per URL/vary; cacheable=false blocks and customer-specific blocks (customer data) are hole-punched via AJAX.

Cache types: config, layout, block_html, collections, reflection, db_ddl, compiled_config, eav, customer, page_cache - each has an independent backend.

Production mode disables on-the-fly compilation and static file materialization; developer mode regenerates and is unsuitable for load testing.

Varnish sits in front of the app and handles FPC; Magento's built-in FPC is bypassed when Varnish is configured as the cache backend.

Redis handles backend cache, session storage, and FPC (if Varnish absent); use separate Redis instances or DB indexes per role to avoid eviction collisions.

Indexers can run on schedule or on save; on-save is faster for freshness but adds write latency - use update by schedule for high-volume catalogs.

Scale horizontally with multiple web nodes behind a load balancer; sessions must be shared (Redis) and media must be shared (NFS/S3).

Profiling tools: built-in profiler (MAGE_PROFILER), New Relic/Blackfire on Cloud; slow queries surface via the query log and EXPLAIN.

ACL is defined in etc/acl.xml; admin controllers and webapi routes reference resource IDs to gate access; UI menu items also reference ACL resources.

Admin users are subject to 2FA (Commerce/Cloud); integrations and API tokens are separate credential types with their own ACL scope.

XSS prevention: escape output in templates (block escapeHtml, jsLayout escaping); never echo unescaped user input into HTML or JS.

CSRF protection uses form_key on POST forms and the X-Magento-Form-Key header for AJAX; admin and frontend forms both require it.

SQL injection is prevented by using the adapter's quoteInto/parameter binding or repository/collection APIs - never string-concatenate SQL.

File uploads must validate extension, MIME type, and size; store outside webroot where possible and never trust the client-supplied filename.

Sensitive config (payment keys, API secrets) belongs in env.php or encrypted config (Magento\Framework\Encryption\Encryptor), not in source control.

Security scan tool and CSP (Content Security Policy) configuration in csp_whitelist.xml are part of the hardening baseline.

Build phase: composer install (no-dev), di:compile, static content deploy, and code generation produce artifacts that are immutable at runtime.

Deploy phase: setup:upgrade, setup:di:compile (if not prebuilt), setup:static-content:deploy, and cache:flush - order matters and must be idempotent.

Static content deploy uses -f (force) and --jobs for parallelism; locales and themes must be enumerated or content 404s in production.

Zero-downtime deploys require shared media, shared sessions, and a maintenance-mode strategy; config.php and env.php are environment-specific and not committed.

app/etc/env.php is generated per environment; app/etc/config.php (module list) is committed and drives module enable/disable state.

Composer version constraints and the composer.lock file pin dependencies; patches (cweagans/composer-patches) apply at build time.

Rollback strategy: keep the previous release artifact and DB backup; schema changes from setup:upgrade are not automatically reversible.

CI pipelines should run static analysis (phpcs, phpmd, phpstan) and unit/integration tests before producing the deploy artifact.

Adobe Commerce Cloud environments: Integration (per-branch), Staging, and Production; each has its own services and configuration.

Service configuration lives in .magento/services.yaml (MySQL, Redis, Elasticsearch/OpenSearch, RabbitMQ) and routes in .magento/routes.yaml.

Environment variables and secrets are managed via the Cloud CLI (magento-cloud variable:set) and injected into env.php at deploy.

The build hook runs during image build (no services available); the deploy hook runs with services - DB migrations belong in deploy.

Starter vs Pro: Starter has a fixed resource profile; Pro offers scalable architecture with dedicated resources and staging/production separation.

Fastly is the default CDN and image optimizer on Cloud; VCL snippets customize caching and are versioned in the project.

Elasticsearch/OpenSearch is required for catalog search in Commerce 2.4+; the service version must match the supported matrix.

Environment-specific config should use config.php scopes and env.php overrides rather than editing the database directly.

Layout XML (default.xml, page layouts) defines block structure; containers hold blocks, and blocks render via .phtml templates.

UI Components (Knockout.js) power Admin grids and storefront widgets; their configuration is JSON in view/*/ui_component and rendered client-side.

RequireJS (AMD) loads storefront JS; modules define dependencies in requirejs-config.js and shim non-AMD libraries.

Knockout.js binds UI components to data; Magento's customer-data JS provides private data via localStorage-backed sections.

Themes inherit via theme.xml parent; static assets are deployed per theme/locale and resolved through pub/static with fallback.

Page Builder (Commerce) stores content as structured JSON in the CMS entity; rendering is handled by content type renderers.

PWA Studio / GraphQL headless decouples the storefront; caching and auth move to the client and edge, changing FPC assumptions.

CSS is processed with LESS by default; critical CSS and bundling/merging are configured in production mode via env.php settings.