Challenge and Context
Building a freight marketplace requires coordinating multiple stakeholders with different needs. Shippers need to quickly find available trucks, track shipments in real-time, and pay seamlessly. Drivers need a steady stream of orders and clear information about pickup and delivery locations. The platform must handle real-time location updates, process payments securely, and maintain reliable communication between all parties.
The system needed to support two distinct mobile applications with shared backend infrastructure. The customer-facing app handles order placement, tracking, and payment. The driver-facing app manages order acceptance, navigation, and delivery confirmation. Both require offline-capable interfaces that work reliably across varying network conditions.
Architecture and System Design
The backend uses Laravel 12 as the core API framework, providing RESTful endpoints secured with Laravel Sanctum for mobile authentication. The database runs on MySQL with spatial extensions enabled through the laravel-eloquent-spatial package, enabling efficient geo-queries for driver matching and route calculations.
The API structure follows clear resource-based patterns. Order management endpoints handle the complete lifecycle from creation through tracking to completion. Separate controllers manage authentication, notifications, payments, and support functions. The routes file demonstrates a clean separation between public endpoints like OTP verification and protected routes requiring authentication.
Mobile applications are built with Flutter using BLoC for state management. This pattern provides clear separation between UI logic and business state, making the codebase testable and maintainable. The customer app and driver app share core infrastructure through a common approach to API communication, localization, and notification handling.
Firebase Cloud Messaging handles push notifications across both applications, while Firebase Core provides initialization and configuration management. The apps support both English and Arabic interfaces through Flutter's localization system, with proper RTL layout support.
Key Engineering Decisions
The platform uses JWT authentication combined with OTP phone verification for secure user onboarding. This approach balances security with usability, critical for platforms handling financial transactions. The OTP system integrates with Twilio for SMS delivery, while the core auth tokens use Laravel Sanctum's token-based system.
Spatial queries power the location-aware features. The Order model uses custom GeoPointCast classes to transform latitude and longitude pairs into queryable objects, enabling efficient driver-to-order matching. The tracking system stores location history in the OrderTrackingEntry model, allowing shippers to view the complete journey path.
Payment processing integrates with MyFatoorah for regional payment methods. The Payment model tracks transaction states, while the Invoice system provides the financial reconciliation layer. The architecture separates payment initiation from callback handling, with webhook endpoints processing asynchronous payment confirmations.
The order lifecycle uses Laravel Observers to automate state transitions and trigger downstream events. When an order status changes, observers fire events that trigger notifications, update related records, and maintain audit trails through the activitylog package. This event-driven approach keeps the codebase modular and prevents logic duplication across controllers.
For driver management, the system tracks vehicle information including truck categories, capacities, and registration details. The RouteGroup model supports predefined shipping lanes with configurable pricing, allowing the platform to offer predictable rates for common origin-destination pairs while supporting dynamic pricing for custom routes.
The admin panel uses Filament to provide operational staff with order management, driver approval, and financial reporting capabilities. This choice gives the team a production-ready admin interface without custom development overhead.
Delivery and Outcomes
The platform delivers a complete freight marketplace solution with three connected components. The Laravel backend provides a stable, scalable API foundation with comprehensive logging through Laravel Telescope and Horizon for queue monitoring. The customer app enables shippers to create orders, track shipments, and manage payments. The driver app provides order discovery, navigation integration, and delivery confirmation workflows.
The architecture supports horizontal scaling through stateless API design and Redis-backed session handling. Queue jobs handle asynchronous operations like notification delivery and payment processing, ensuring the API remains responsive under load.
Localization support covers Arabic and English markets, with proper text direction handling in the Flutter interfaces. The dual-app strategy allows specialized user experiences while sharing backend infrastructure and business logic.