GMAD: Great Magento Architecture Decoupling¶

"I'm Jakub, from qoliber. Let's fix Magento — nobody else is going to do it."

Jakub Winkler — The MAD man behind the GMAD project, Founder of qoliber | Connect on LinkedIn

The open-source project to decouple, modernize, and slim down Magento 2.

Contribute on GitHub

Step 1: Where Do We Contribute?¶

We need your input before we start shipping code

The research is done. The plan is ready. But where should the actual PRs go?

Join the discussion on GitHub

Option	Target	Pros	Cons
A	Magento Open Source (adobe/magento2)	Ships to every Magento install	Slow review, Adobe's priorities
B	MageOS	Community-driven, faster reviews	Smaller install base
C	GMAD standalone	Ship fast, no gatekeepers	Fragmentation risk
D	All of the above	GMAD develops, then submits upstream	Most work, maximum reach

Have an opinion? Tell us in Issue #1. This decision shapes everything.

The Problem¶

Magento 2 ships with 221 modules — and that's without MSI! Most stores use less than half of them. But disabling unused modules isn't straightforward — decades of coupling mean that removing one module can break another that shouldn't care about it at all.

Newsletter code in the Customer module. Wishlist controllers in Sales. Payment depending on Sales which depends on Payment. Product type checks hardcoded into Catalog. CatalogInventory wired into 24 modules.

This project fixes that.

The Numbers¶

Metric	Count
Total modules scanned	221 / 221 (100%)
Modules that can be removed	~121 (55%)
Removable PHP files	~1,470
Circular dependencies found	2 (Sales-Payment, QuoteGraphQl-SalesGraphQl)
Phantom composer deps found & fixed	8
Parallel workstreams for developers	12

What We've Done¶

Scanned Every Module¶

Every one of Magento's 221 modules has been analyzed for:

Inbound coupling (who depends on this module?)
Outbound coupling (what does this module import?)
Phantom dependencies (composer.json require with zero code usage)
Constants leaking across module boundaries
Hardcoded type checks that should be plugins
DI configurations in the wrong module

Identified 4 Decoupling Patterns¶

From the completed PR #1, we established 4 reusable patterns that apply across the entire codebase:

Pattern A: Hardcoded Type Check to Plugin — Remove switch/case product type checks from core modules; each product type registers its own plugin.

Pattern B: Hardcoded DI Array to Self-Registration — Core modules define empty arrays; product types add themselves via DI merging.

Pattern C: Hard Dependency to Nullable Constructor — Make dependencies optional with ?Type $dep = null and null-checks.

Pattern D: Move DI Config to Correct Module — When Module A configures Module B's classes, move the config to where it belongs.

Created the Implementation Plan¶

12 independent workstreams, 46 tasks — all with step-by-step instructions, file paths, before/after code, and the exact pattern to follow. 10 of 12 can start Day 1 with no dependencies between them.

Built the Module Disable Guide¶

3 tiers of modules to disable with copy-paste bin/magento module:disable commands:

Tier 1: 48 modules — disable today, zero risk
Tier 2: 35 modules — disable today, minor admin side effects
Tier 3: 12 modules — disable after decoupling work

Mapped Framework Modernization (PHP 8.4)¶

206 Proxy classes replaceable with native lazy objects
99 constant-bag classes convertible to PHP 8.1 enums
401 @deprecated annotations upgradable to #[\Deprecated] attribute
6 View/Layout proposals including lazy block instantiation and compiled layout cache

How to Contribute¶

Pick a workstream from the Implementation Plan
Follow the patterns established in PR #1
Submit a PR with your changes
Run the verification checklist at the bottom of the Implementation Plan

Every workstream is independent. Multiple developers can work simultaneously without conflicts.

Documentation¶

Decoupling Reports¶

Each report covers: what the module does, who depends on it, who it depends on, the exact coupling points, and a step-by-step decoupling plan.

Report	Modules	Key Finding
Configurable Product	4 modules	`TYPE_CODE` constant used by 5 external modules
Downloadable Product	3 modules	GiftMessageGraphQl coupling fixed
CatalogInventory	24 modules, 83 PHP imports	5 phantom deps removed. Identical code in 3 product types
Sales / Shipping / Payment	16 modules	Circular dependency: Sales-Payment
Payment-Sales Circular	2 modules	3-phase fix: move adapters, observers, cleanup
Newsletter	2 modules	Customer has 11 Newsletter imports — all movable
Review	3 modules	Catalog already has null-object pattern. Move 16 report files
Wishlist	3 modules	Zero PHP imports from outside — all XML/template coupling
Weee (FPT)	2 modules	Zero inbound coupling. Already optional
Cron & Message Queue	5 modules	MQ transports fully decoupled. Proposed `Async\PublisherInterface`
Login As Customer	10 modules	Near-perfect. 1 plugin to relocate
MSRP / Multishipping / MysqlMq	7 modules	MSRP: 3 modules coupled. Multishipping: 2 plugins to move
Media Modules	25 modules	24 modules (288 files) fully optional. MediaStorage essential
RequireJs & Ui Removal	2 modules	Ui: 44 modules, 553 imports. Solvable via composer `replace`
APM	2 modules	Perfectly decoupled. Zero coupling. Reference architecture
Swatches / SendFriend	5 modules	SendFriend: zero coupling. SwatchesLayeredNavigation: empty module
Misc	2 modules	Both clean, trivial fixes

Framework Modernization¶

Report	Key Proposals
PHP 8.4 Opportunities	Lazy objects, enums, property hooks, deprecated attribute, component replacement
View/Layout System	Lazy blocks, compiled layout cache, template maps, asset pipeline extraction

Project Info¶

Created by: Jakub Winkler at qoliber

License: Open source, same as Magento 2 (OSL-3.0 / AFL-3.0)

Reference PR: github.com/qoliber/great-magento-architecture-decoupling — Decouples Catalog from Bundle, Configurable, Downloadable + makes CatalogInventory optional (77 PHP files, 6 XML files, 18 modules)