Enterprise B2B/B2C Multi-Region Magento Platform

Multi-Region E-Commerce at Scale

Managing 6 storefrontsmarket segments across multiple regions while synchronising with legacy ERP systems creates serious architectural challenges. This platform shows how to build maintainable, testable e-commerce systems at scale. It processes orders from five concurrent sales channels while maintaining data integrity across two ERP systems and multiple marketplace integrations.

The system handles bidirectional SOAP synchronisation through 27,000 linesERP integration. It uses proven patterns for multi-region data handling, complex shipping logistics, and B2B/B2C pricing segmentation. Three layers form the core architecture: storefront isolation, region-aware processing, and automated synchronisation.

These architectural requirements drove specific technology choices. The platform needed modern PHP features for type safety, proven frontend performance, and robust developer tooling to maintain quality across 87,000 lines of code.

Architecture Overview

The system has four distinct layers, each handling specific concerns while maintaining clean separation. The storefront layer manages six independent sales channels. The application layer provides store-aware business logic. The integration layer handles external systems, and the automation layer orchestrates scheduled operations.

To address these challenges, we implemented a pattern-based solution using PHP 8 match expressions. The router pattern makes regional differences explicit whilst maintaining type safety through the PHP compiler.

This architectural approach might seem counterintuitive. Why not abstract the regional differences behind a unified interface? The answer lies in the trade-offs between abstraction complexity and explicit regional handling.

Technical Challenges

Multi-Region ERP Synchronisation

The legacy ERP system exposes three separate SOAP endpoints with different WSDL schemas, authentication mechanisms, and data formats. Routing orders to the correct endpoint, transforming data between formats, and handling region-specific business rules without creating a maintenance nightmare was tricky.

Beyond routing, the system needed to protect business logic from the volatility of generated SOAP code. When WSDL schemas change during ERP upgrades, a single abstraction layer prevents cascading changes throughout the application.

The wrapper handles schema differences, but converting Magento orders to ERP format requires multiple transformation stages. Each stage handles one concern independently, enabling composition-based flexibility across regions.

Complex Shipping Logic

Shipping carrier selection depends on website, country, postcode pattern, product dimensions, and priority flags. Orders may contain mixed items requiring different carriers. Four database tables manage shipping rules: carrier mapping, order filters, order maps, and packaging items. We needed to resolve the correct carrier without overwhelming checkout logic.

Shipping Resolution Pipeline

Understanding the complexity is one thing. Implementing a maintainable solution is another. The resolver uses a five-stage pipeline that optimises common cases whilst correctly handling edge scenarios.

This pipeline architecture needed concrete implementation. The resolver balances performance with flexibility using wildcard pattern matching and lookup optimisations for the most common order types.

B2B/B2C Pricing Segmentation

Wholesale customers see carton pricing with quantity increments (minimum 24 units); retail customers see single-unit pricing with VAT included. Both must coexist in the same catalogue without price leakage between segments or customer confusion during checkout.

Solving price segmentation required intercepting Magento's pricing engine at multiple touchpoints. Plugins provide a clean way to inject store-specific behaviour without modifying core business logic.

With plugins intercepting price operations, determining the current store context efficiently becomes critical. The solution caches store type detection using PHP 8 match expressions to avoid redundant queries in hot code paths.

Implementation Highlights

Integration Testing at Scale

Getting meaningful test coverage on a platform with complex ERP integration, multiple storefronts, and intricate shipping rules needed a comprehensive testing framework built on modern Magento patterns. We built 201 integration tests covering critical business logic, from shipping resolution to price segmentation to ERP data transformation.

Our testing strategy: never mock DTOs. DTOs are simple data carriers with no behaviour to mock. Testing with real DTOs validates actual data flow, while mocking them only tests the mock's behaviour. This approach caught several serialisation bugs that mocks would have hidden.

Beyond modern PHPUnit attributes, the fixture system itself needed careful architecture. Reusable fixtures reduce boilerplate whilst parameterisation enables flexible test scenarios across different configurations.

Intelligent Cron Orchestration

Managing 26scheduled jobs across imports, exports, indexing, and marketplace sync without overwhelming server resources or causing data corruption from concurrent writes needed a four-layer protection system with dynamic load awareness. We built 814 lines of bash automation. Zero production incidents from job overload since deployment.

Understanding the collision problem led to a four-layer protection system. Each layer addresses different failure modes, from system resource constraints to process-level race conditions.

The protection layers provide collision prevention, but effective scheduling also requires strategic timing offsets. Staggering related jobs ensures sequential execution whilst maintaining synchronisation requirements.

This approach might seem unusual. Why add bash wrappers when Magento has built-in cron handling? The decision comes down to separation of concerns and upgrade safety.

Outcomes & Results

What Worked Well

• Region Router Pattern: Clean separation of UK/US/EU logic without code duplication. Adding a new region requires implementing the interface, not modifying existing code. Exhaustive match expressions ensure compiler catches missing cases.
• DTO Wrappers: Insulating business logic from generated SOAP code proved invaluable when WSDL schemas changed. Only wrapper methods needed updating, protecting 27,000 lines of business logic from schema churn.
• Load-Aware Automation: Zero production incidents from cron job overload since implementing dynamic load detection. Jobs gracefully skip execution during high-load periods rather than failing.
• Fixture-Based Testing: 137 reusable fixtures dramatically reduced test setup time from hours to minutes and improved test clarity through declarative dependencies.

Key Lessons

• Match expressions over if-else: PHP 8 match expressions make region routing exhaustive and self-documenting. The compiler ensures all cases are handled, catching missing regions at build time rather than runtime.
• Never mock DTOs: Simple data objects should be instantiated with real data, not mocked. Mocking them tests the mock's behaviour rather than actual data flow. This caught serialisation bugs mocks would have hidden.
• Graceful degradation over exceptions: For non-critical failures (shipping lookup misses), returning null with comprehensive logging is preferable to throwing exceptions that block order processing.
• Random jitter prevents thundering herd: A simple 1-10 second random delay before process checks eliminated observed scheduling collisions in production when multiple jobs start simultaneously.
• Composition over inheritance: Converters compose specialised transformers rather than inheriting shared behaviour, improving testability and allowing converters to be mixed and matched across regions.

These patterns and techniques aren't specific to this one platform. The architectural approaches apply broadly across different industries and technical contexts.