Challenge and Context
The client needed a modern e-commerce platform tailored for the Saudi Arabian market. The requirements included bilingual content support, integration with multiple regional payment providers, and synchronization with an existing warehouse management system. The platform had to handle the complexity of VAT calculations, manage inventory across channels, and provide a seamless checkout experience while maintaining high performance.
The existing infrastructure required the new platform to integrate with Mintsoft, an ERP system handling inventory and fulfillment. Additionally, the client required support for Buy Now Pay Later options popular in the region, alongside traditional card payments. The platform needed to scale during peak periods while providing real-time visibility into order status and inventory levels.
Architecture and System Design
The application is built on Laravel 12, leveraging the framework's robust ecosystem for queue management, caching, and database operations. The architecture follows a service-oriented pattern where payment processing and ERP synchronization are encapsulated in dedicated service classes, allowing for independent testing and modification of each integration point.
The system uses MySQL for persistent data storage, with Redis handling session management and queue processing through Laravel Horizon. Search functionality is powered by Typesense, configured for both English and Arabic text, providing fast and relevant product searches. The media layer utilizes Spatie Media Library for image management, including automatic WebP conversion and responsive image generation.
The admin interface is built with Filament, providing a performant dashboard for managing products, orders, and customer data. Laravel Pulse offers real-time monitoring of application health, while Telescope handles debug mode introspection. The application runs queued jobs for webhook processing from payment providers, ensuring reliable handling of asynchronous payment confirmations.
Key Engineering Decisions
The team chose Typesense over Algolia for search functionality due to its superior handling of Arabic text and more predictable pricing for self-hosted deployments. The search index is configured with locale-specific fields, allowing queries to search across both English and Arabic product attributes while maintaining relevance scoring.
Payment gateway integration was implemented using a modular service pattern. Each gateway, including Tamara, Tabby, MyFatoorah, and HyperPay, operates through its own service class with consistent methods for creating payment sessions, handling webhooks, and managing refunds. This abstraction allows new payment providers to be added without modifying core checkout logic. Webhook handlers process payment events asynchronously through queued jobs, ensuring reliable state management even during high traffic periods.
The Mintsoft ERP integration handles bidirectional synchronization. Products sync from the ERP to maintain inventory accuracy, while orders flow from the platform to Mintsoft for fulfillment processing. The integration includes retry logic and detailed logging for failed API calls, with automatic retry mechanisms for transient failures. Order creation maps local data structures to Mintsoft payloads, including VAT calculations and delivery scheduling.
The codebase implements a custom MoneyCast using Brick Money for precise decimal arithmetic, essential for financial calculations where floating-point errors are unacceptable. All monetary values are stored as integers in the smallest currency unit and converted only at display time.
Internationalization uses Spatie Translatable for model-level translations, with route-level language switching enabling separate URLs for English and Arabic content. The middleware enforces language consistency throughout the user session.
Delivery and Outcomes
The platform successfully launched with four integrated payment providers, giving customers flexibility in their payment choices. The Typesense-powered search delivers sub-100ms response times even with large product catalogs, while the Arabic text search performs comparably to English searches.
The Mintsoft integration handles order creation and inventory synchronization automatically. The webhook-driven architecture ensures payment statuses update reliably without manual intervention. The separation of concerns between payment processing, order management, and inventory allows each component to be updated independently.
The engineering team prioritized code quality through Laravel Pint for formatting and Pest for testing, ensuring consistent code style and reliable test coverage across the application.