# muhhammedd/shipping-system architecture

> Architecture diagram of the GitHub repository muhhammedd/shipping-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/muhhammedd/shipping-system
- Repository: https://github.com/muhhammedd/shipping-system

## Overview

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: [`app/Http/Controllers/Admin`](https://github.com/muhhammedd/shipping-system/tree/master/app/Http/Controllers/Admin) (Admin area), [`app/Models/Shipment.php`](https://github.com/muhhammedd/shipping-system/blob/master/app/Models/Shipment.php) (Shipment), [`database/migrations`](https://github.com/muhhammedd/shipping-system/tree/master/database/migrations) (Schema), [`routes/web.php`](https://github.com/muhhammedd/shipping-system/blob/master/routes/web.php) (Web routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_runtime["Runtime"]
  node_routes_web["Web routes<br/>routing<br/>[web.php]"]
  node_routes_auth["Auth routes<br/>routing<br/>[auth.php]"]
  node_role_mw{{"Role guard<br/>middleware<br/>[RoleMiddleware.php]"}}
  node_prefs_mw{{"Prefs middleware"}}
end

subgraph group_grp_surfaces["User Surfaces"]
  node_auth_ctrl["Auth flow<br/>controllers"]
  node_admin_ctrls["Admin area<br/>controllers"]
  node_merchant_ctrls["Merchant area<br/>controllers"]
  node_courier_ctrls["Courier area<br/>controllers"]
  node_user_ctrls["User area<br/>controllers"]
  node_views_admin["Admin views<br/>blade ui"]
  node_views_merchant["Merchant views<br/>blade ui"]
  node_views_courier["Courier views<br/>blade ui"]
  node_views_user["User views<br/>blade ui"]
  node_shared_views["Shared UI<br/>blade components"]
end

subgraph group_grp_domain["Domain"]
  node_shipment_model[("Shipment<br/>eloquent model<br/>[Shipment.php]")]
  node_shipment_status[("Status history<br/>eloquent model")]
  node_shipment_service["Status service<br/>domain service"]
  node_shipment_event(("Status changed<br/>event"))
  node_shipment_listener(("Notify listener"))
  node_shipment_notification(("Shipment notice<br/>notification"))
  node_pricing_service["Pricing calc<br/>domain service"]
  node_cod_models[("COD domain<br/>models<br/>[CODSettlement.php]")]
  node_pricing_models[("Pricing data<br/>models<br/>[PricingZone.php]")]
  node_core_models[("Core data<br/>models<br/>[Branch.php]")]
end

subgraph group_grp_data["Persistence"]
  node_migrations["Schema<br/>migrations"]
  node_seeders["Seed data<br/>seeders<br/>[DatabaseSeeder.php]"]
end

node_routes_web -->|"dispatches"| node_admin_ctrls
node_routes_web -->|"dispatches"| node_merchant_ctrls
node_routes_web -->|"dispatches"| node_courier_ctrls
node_routes_web -->|"dispatches"| node_user_ctrls
node_routes_auth -->|"dispatches"| node_auth_ctrl
node_admin_ctrls -->|"protected by"| node_role_mw
node_merchant_ctrls -->|"protected by"| node_role_mw
node_courier_ctrls -->|"protected by"| node_role_mw
node_user_ctrls -->|"uses"| node_prefs_mw
node_admin_ctrls -->|"renders"| node_views_admin
node_merchant_ctrls -->|"renders"| node_views_merchant
node_courier_ctrls -->|"renders"| node_views_courier
node_user_ctrls -->|"renders"| node_views_user
node_views_admin -->|"reuses"| node_shared_views
node_views_merchant -->|"reuses"| node_shared_views
node_views_courier -->|"reuses"| node_shared_views
node_views_user -->|"reuses"| node_shared_views
node_shipment_service -->|"updates"| node_shipment_model
node_shipment_service -->|"records"| node_shipment_status
node_shipment_service -->|"emits"| node_shipment_event
node_shipment_event -->|"handled by"| node_shipment_listener
node_shipment_listener -->|"sends"| node_shipment_notification
node_admin_ctrls -->|"manages"| node_shipment_model
node_merchant_ctrls -->|"manages"| node_shipment_model
node_courier_ctrls -->|"operates on"| node_shipment_model
node_pricing_service -->|"evaluates"| node_pricing_models
node_admin_ctrls -->|"uses"| node_pricing_service
node_admin_ctrls -->|"manages"| node_cod_models
node_core_models -->|"persisted by"| node_migrations
node_cod_models -->|"persisted by"| node_migrations
node_pricing_models -->|"persisted by"| node_migrations
node_shipment_model -->|"persisted by"| node_migrations
node_seeders -->|"populates"| node_migrations

click node_routes_web "https://github.com/muhhammedd/shipping-system/blob/master/routes/web.php"
click node_routes_auth "https://github.com/muhhammedd/shipping-system/blob/master/routes/auth.php"
click node_role_mw "https://github.com/muhhammedd/shipping-system/blob/master/app/Http/Middleware/RoleMiddleware.php"
click node_prefs_mw "https://github.com/muhhammedd/shipping-system/blob/master/app/Http/Middleware/SetPreferencesMiddleware.php"
click node_auth_ctrl "https://github.com/muhhammedd/shipping-system/tree/master/app/Http/Controllers/Auth"
click node_admin_ctrls "https://github.com/muhhammedd/shipping-system/tree/master/app/Http/Controllers/Admin"
click node_merchant_ctrls "https://github.com/muhhammedd/shipping-system/tree/master/app/Http/Controllers/Merchant"
click node_courier_ctrls "https://github.com/muhhammedd/shipping-system/tree/master/app/Http/Controllers/Courier"
click node_user_ctrls "https://github.com/muhhammedd/shipping-system/tree/master/app/Http/Controllers"
click node_views_admin "https://github.com/muhhammedd/shipping-system/tree/master/resources/views/admin"
click node_views_merchant "https://github.com/muhhammedd/shipping-system/tree/master/resources/views/merchant"
click node_views_courier "https://github.com/muhhammedd/shipping-system/tree/master/resources/views/courier"
click node_views_user "https://github.com/muhhammedd/shipping-system/tree/master/resources/views/user"
click node_shared_views "https://github.com/muhhammedd/shipping-system/tree/master/resources/views/components"
click node_shipment_model "https://github.com/muhhammedd/shipping-system/blob/master/app/Models/Shipment.php"
click node_shipment_status "https://github.com/muhhammedd/shipping-system/blob/master/app/Models/ShipmentStatusHistory.php"
click node_shipment_service "https://github.com/muhhammedd/shipping-system/blob/master/app/Services/ShipmentStatusService.php"
click node_shipment_event "https://github.com/muhhammedd/shipping-system/blob/master/app/Events/ShipmentStatusChanged.php"
click node_shipment_listener "https://github.com/muhhammedd/shipping-system/blob/master/app/Listeners/SendShipmentStatusNotification.php"
click node_shipment_notification "https://github.com/muhhammedd/shipping-system/blob/master/app/Notifications/ShipmentStatusNotification.php"
click node_pricing_service "https://github.com/muhhammedd/shipping-system/blob/master/app/Services/PricingCalculatorService.php"
click node_cod_models "https://github.com/muhhammedd/shipping-system/blob/master/app/Models/CODSettlement.php"
click node_pricing_models "https://github.com/muhhammedd/shipping-system/blob/master/app/Models/PricingZone.php"
click node_core_models "https://github.com/muhhammedd/shipping-system/blob/master/app/Models/Branch.php"
click node_migrations "https://github.com/muhhammedd/shipping-system/tree/master/database/migrations"
click node_seeders "https://github.com/muhhammedd/shipping-system/blob/master/database/seeders/DatabaseSeeder.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_routes_web,node_routes_auth,node_role_mw,node_prefs_mw toneBlue
class node_auth_ctrl,node_admin_ctrls,node_merchant_ctrls,node_courier_ctrls,node_user_ctrls,node_views_admin,node_views_merchant,node_views_courier,node_views_user,node_shared_views toneAmber
class node_shipment_model,node_shipment_status,node_shipment_service,node_shipment_event,node_shipment_listener,node_shipment_notification,node_pricing_service,node_cod_models,node_pricing_models,node_core_models toneMint
class node_migrations,node_seeders toneRose
```

## Components

### Runtime

Laravel app lifecycle and shared infrastructure

- [Web routes](https://github.com/muhhammedd/shipping-system/blob/master/routes/web.php): routing · Main HTTP route map for the app · `routes/web.php`
- [Auth routes](https://github.com/muhhammedd/shipping-system/blob/master/routes/auth.php): routing · Authentication and verification endpoints · `routes/auth.php`
- [Role guard](https://github.com/muhhammedd/shipping-system/blob/master/app/Http/Middleware/RoleMiddleware.php): middleware · Role-based access control · `app/Http/Middleware/RoleMiddleware.php`
- [Prefs middleware](https://github.com/muhhammedd/shipping-system/blob/master/app/Http/Middleware/SetPreferencesMiddleware.php): middleware · Applies user and environment preferences · `app/Http/Middleware/SetPreferencesMiddleware.php`

### User Surfaces

Role-based entry points and Blade UI

- [Auth flow](https://github.com/muhhammedd/shipping-system/tree/master/app/Http/Controllers/Auth): controllers · Login, registration, verification, and reset controllers · `app/Http/Controllers/Auth`
- [Admin area](https://github.com/muhhammedd/shipping-system/tree/master/app/Http/Controllers/Admin): controllers · Back-office controllers for operations and oversight · `app/Http/Controllers/Admin`
- [Merchant area](https://github.com/muhhammedd/shipping-system/tree/master/app/Http/Controllers/Merchant): controllers · Merchant-facing shipment and dashboard controllers · `app/Http/Controllers/Merchant`
- [Courier area](https://github.com/muhhammedd/shipping-system/tree/master/app/Http/Controllers/Courier): controllers · Courier task and dashboard controllers · `app/Http/Controllers/Courier`
- [User area](https://github.com/muhhammedd/shipping-system/tree/master/app/Http/Controllers): controllers · General user controllers for profile and documents · `app/Http/Controllers`
- [Admin views](https://github.com/muhhammedd/shipping-system/tree/master/resources/views/admin): blade ui · Admin layouts and pages · `resources/views/admin`
- [Merchant views](https://github.com/muhhammedd/shipping-system/tree/master/resources/views/merchant): blade ui · Merchant layouts and pages · `resources/views/merchant`
- [Courier views](https://github.com/muhhammedd/shipping-system/tree/master/resources/views/courier): blade ui · Courier task pages and layouts · `resources/views/courier`
- [User views](https://github.com/muhhammedd/shipping-system/tree/master/resources/views/user): blade ui · General user dashboards and documents · `resources/views/user`
- [Shared UI](https://github.com/muhhammedd/shipping-system/tree/master/resources/views/components): blade components · Reusable layouts and UI components · `resources/views/components`

### Domain

Core business models, services, and events

- [Shipment](https://github.com/muhhammedd/shipping-system/blob/master/app/Models/Shipment.php): eloquent model · Core shipment aggregate · `app/Models/Shipment.php`
- [Status history](https://github.com/muhhammedd/shipping-system/blob/master/app/Models/ShipmentStatusHistory.php): eloquent model · Shipment lifecycle audit trail · `app/Models/ShipmentStatusHistory.php`
- [Status service](https://github.com/muhhammedd/shipping-system/blob/master/app/Services/ShipmentStatusService.php): domain service · Encapsulates shipment status transitions · `app/Services/ShipmentStatusService.php`
- [Status changed](https://github.com/muhhammedd/shipping-system/blob/master/app/Events/ShipmentStatusChanged.php): event · Emitted when shipment state changes · `app/Events/ShipmentStatusChanged.php`
- [Notify listener](https://github.com/muhhammedd/shipping-system/blob/master/app/Listeners/SendShipmentStatusNotification.php): listener · Converts status changes into notifications · `app/Listeners/SendShipmentStatusNotification.php`
- [Shipment notice](https://github.com/muhhammedd/shipping-system/blob/master/app/Notifications/ShipmentStatusNotification.php): notification · User-facing shipment status notification · `app/Notifications/ShipmentStatusNotification.php`
- [Pricing calc](https://github.com/muhhammedd/shipping-system/blob/master/app/Services/PricingCalculatorService.php): domain service · Central shipment pricing computation · `app/Services/PricingCalculatorService.php`
- [COD domain](https://github.com/muhhammedd/shipping-system/blob/master/app/Models/CODSettlement.php): models · Settlement and transaction records for cash-on-delivery · `app/Models/CODSettlement.php`
- [Pricing data](https://github.com/muhhammedd/shipping-system/blob/master/app/Models/PricingZone.php): models · Pricing zones and rules · `app/Models/PricingZone.php`
- [Core data](https://github.com/muhhammedd/shipping-system/blob/master/app/Models/Branch.php): models · Branches, merchants, couriers, users, documents, invoices, payments, settings, logs, permissions · `app/Models/Branch.php`

### Persistence

Database schema and seed data

- [Schema](https://github.com/muhhammedd/shipping-system/tree/master/database/migrations): migrations · Database tables for logistics, COD, pricing, notifications, and settings · `database/migrations`
- [Seed data](https://github.com/muhhammedd/shipping-system/blob/master/database/seeders/DatabaseSeeder.php): seeders · Initial database data · `database/seeders/DatabaseSeeder.php`

## Connections

- 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
