How muhhammedd/shipping-system works
1. This repository is a Laravel monolith for a logistics/courier platform called SHIPEX. The runtime is a server-rendered PHP app using Blade views, Eloquent models, Laravel auth, and a front-end asset pipeline built with Vite/Tailwind.
2. The application is split into multiple user-facing surfaces rather than a single generic UI: admin, merchant, courier, and general user areas. Each surface has its own controllers, layouts, and Blade templates under resources/views, with shared UI components reused across them.
3. Request handling is organized through Laravel routing in routes/web.php and routes/auth.php, then dispatched to feature-specific controllers in app/Http/Controllers. Access is guarded by RoleMiddleware, while SetPreferencesMiddleware applies user/environment preferences before the page renders.
4. The core domain is shipment management. Shipment sits at the center, connected to Merchant, Courier, Branch, ShipmentStatusHistory, and related operational records, so most business flows ultimately read or mutate shipment state.
5. Shipment lifecycle changes are a first-class event flow. ShipmentStatusChanged is emitted from the shipment domain, handled by SendShipmentStatusNotification, and backed by ShipmentStatusNotification, which means status transitions are designed to propagate to users rather than stay local to the controller.
6. The shipment workflow is split by role: merchants create and track shipments, couriers work task queues, and admins manage the full shipment registry. The presence of dedicated Merchant\ShipmentController, Courier\TaskController, and Admin\ShipmentController indicates role-specific views over the same underlying shipment records.
7. COD is its own subsystem, not just a field on shipment. CODSettlement and CODTransaction models, plus CODSettlementController and CODTransactionController, show a financial reconciliation flow for cash-on-delivery collections, settlement batches, and payment-method handling.
8. Pricing is another separate domain service. PricingZone and PricingRule are managed through admin controllers and evaluated by PricingCalculatorService, with validation covered by tests, so price computation is centralized rather than embedded in views or controllers.
9. Administrative operations are broad and operational, covering branches, couriers, merchants, users, settings, reporting, dashboards, and audit-style data. The admin views under resources/views/admin and the corresponding controllers suggest the back office is the primary control plane for the platform.
10. Persistence is conventional Laravel/Eloquent backed by migrations and seeders. The schema includes operational tables for shipments, status histories, COD, pricing, notifications, settings, logs, invoices, documents, and permissions, which indicates the app is stateful and database-centric.
11. Cross-cutting concerns include authentication, email verification, password reset, profile management, localization (lang/en and lang/ar), notifications, and logging. Storage directories and models like Document, Invoice, and Payment suggest file-backed artifacts are part of the domain, not just metadata.
12. The repository also contains planning/specification material: PRD, domain design docs, implementation docs, and admin frontend mockups. Those files are not runtime components, but they define the intended boundaries and help explain why the code is organized around logistics operations, role-based dashboards, shipment state, COD, and pricing.
Main entry points: Admin Admin area · Shipment.php Shipment · migrations Schema · web.php Web routes
Components 26
Runtime
Laravel app lifecycle and shared infrastructure
- Web routes · Main HTTP route map for the app
routes/web.php - Auth routes · Authentication and verification endpoints
routes/auth.php - Role guard · Role-based access control
app/Http/Middleware/RoleMiddleware.php - Prefs middleware · Applies user and environment preferences
app/Http/Middleware/SetPreferencesMiddleware.php
User Surfaces
Role-based entry points and Blade UI
- Auth flow · Login, registration, verification, and reset controllers
app/Http/Controllers/Auth - Admin area · Back-office controllers for operations and oversight
app/Http/Controllers/Admin - Merchant area · Merchant-facing shipment and dashboard controllers
app/Http/Controllers/Merchant - Courier area · Courier task and dashboard controllers
app/Http/Controllers/Courier - User area · General user controllers for profile and documents
app/Http/Controllers - Admin views · Admin layouts and pages
resources/views/admin - Merchant views · Merchant layouts and pages
resources/views/merchant - Courier views · Courier task pages and layouts
resources/views/courier - User views · General user dashboards and documents
resources/views/user - Shared UI · Reusable layouts and UI components
resources/views/components
Domain
Core business models, services, and events
- Shipment · Core shipment aggregate
app/Models/Shipment.php - Status history · Shipment lifecycle audit trail
app/Models/ShipmentStatusHistory.php - Status service · Encapsulates shipment status transitions
app/Services/ShipmentStatusService.php - Status changed · Emitted when shipment state changes
app/Events/ShipmentStatusChanged.php - Notify listener · Converts status changes into notifications
app/Listeners/SendShipmentStatusNotification.php - Shipment notice · User-facing shipment status notification
app/Notifications/ShipmentStatusNotification.php - Pricing calc · Central shipment pricing computation
app/Services/PricingCalculatorService.php - COD domain · Settlement and transaction records for cash-on-delivery
app/Models/CODSettlement.php - Pricing data · Pricing zones and rules
app/Models/PricingZone.php - Core data · Branches, merchants, couriers, users, documents, invoices, payments, settings, logs, permissions
app/Models/Branch.php
Connections 33
- Web routes → Admin area: dispatches · Routes send requests to admin controllers
- Web routes → Merchant area: dispatches · Routes send merchant requests to merchant controllers
- Web routes → Courier area: dispatches · Routes send courier requests to courier controllers
- Web routes → User area: dispatches · Routes send general user requests to app controllers
- Auth routes → Auth flow: dispatches · Auth routes map to authentication controllers
- Admin area → Role guard: protected by · Admin area requires role-based access
- Merchant area → Role guard: protected by · Merchant area requires role-based access
- Courier area → Role guard: protected by · Courier area requires role-based access
- User area → Prefs middleware: uses · User-facing requests apply preferences middleware
- Admin area → Admin views: renders · Admin controllers render admin Blade pages
- Merchant area → Merchant views: renders · Merchant controllers render merchant Blade pages
- Courier area → Courier views: renders · Courier controllers render courier Blade pages
- User area → User views: renders · User controllers render user Blade pages
- Admin views → Shared UI: reuses · Admin UI reuses shared Blade components
- Merchant views → Shared UI: reuses · Merchant UI reuses shared Blade components
- Courier views → Shared UI: reuses · Courier UI reuses shared Blade components
- User views → Shared UI: reuses · User UI reuses shared Blade components
- Status service → Shipment: updates · Service reads and mutates shipment state
- Status service → Status history: records · Status changes are written to history
- Status service → Status changed: emits · Status transitions emit a domain event
- Status changed → Notify listener: handled by · Shipment change events trigger listener logic
- Notify listener → Shipment notice: sends · Listener dispatches user notifications
- Admin area → Shipment: manages · Admin shipment views operate on shipment records
- Merchant area → Shipment: manages · Merchants create and track shipments
- Courier area → Shipment: operates on · Couriers work shipment tasks and assignments
- Pricing calc → Pricing data: evaluates · Pricing calculation uses zones and rules
- Admin area → Pricing calc: uses · Pricing admin flows rely on centralized calculation
- Admin area → COD domain: manages · Admin COD controllers manage settlement and transactions
- Core data → Schema: persisted by · Core entities are backed by schema migrations
- COD domain → Schema: persisted by · COD tables are defined in migrations
- Pricing data → Schema: persisted by · Pricing tables are defined in migrations
- Shipment → Schema: persisted by · Shipment tables are defined in migrations
- Seed data → Schema: populates · Seeders populate the schema after migration