Complete Flows

Every major CargoPRO lifecycle as a diagram — order statuses, prealerts, on-hold invoices, pickups, notifications, payments, consolidation and the user app session.

Order status lifecycle

Both shipments and customer packages move through the same eleven system statuses. An admin changes the status from the panel; the app reacts to the new lifecycle flags that come with it.

stateDiagram-v2
    [*] --> pending : order or package created
    pending --> approved : admin accepts
    pending --> rejected : admin declines
    pending --> cancelled : customer cancels
    approved --> in_transit : handed to courier
    approved --> out_for_delivery : same day delivery
    approved --> ready_for_pickup : at warehouse counter
    approved --> on_hold : issue found
    in_transit --> out_for_delivery : loaded on van
    in_transit --> on_hold : hold reason set
    out_for_delivery --> delivered : customer signs
    out_for_delivery --> on_hold : issue found
    on_hold --> in_transit : admin releases hold
    on_hold --> ready_for_pickup : admin releases hold
    ready_for_pickup --> self_pickup : customer books slot
    ready_for_pickup --> delivered : collected at counter
    self_pickup --> delivered : collected at counter
    consolidate --> in_transit : CON order shipped
    consolidate --> delivered : handed to customer
    delivered --> [*]
    rejected --> [*]
    cancelled --> [*]
    note right of ready_for_pickup
        Pickups module row
    end note
    note right of self_pickup
        Pickups module row
    end note
    note left of consolidate
        Set on child rows added to a CON order
    end note
      

Prealert to package conversion

A prealert is the customer's heads-up that a parcel is on its way. The app records it, staff match it when the parcel physically arrives, and the prealert is converted into a real customer package.

flowchart TD
    A[Customer adds prealert in app] --> B[POST /api/prealerts]
    B --> C[Row in pre_alerts - is_package 0]
    C --> D[Staff notified - prealert_created]
    D --> E[Parcel arrives at warehouse]
    E --> F[Admin opens Convert in Customer Packages]
    F --> G[Convert form prefilled from prealert]
    G --> H[Row in customers_packages - is_prealert 1]
    H --> I[Prealert marked is_package 1]
    H --> J[Invoice file reused from prealert]
    H --> K[Customer notified - package_registered]
    H --> L[Normal status lifecycle begins]
      

On-hold invoice flow

Customs sometimes needs the purchase invoice. Staff put the package on hold with reason invoice, the customer uploads the document from the app, and staff release the hold.

flowchart TD
    A[Admin sets status on_hold] --> B{hold_reason}
    B -->|invoice| C[App shows can_upload_invoice true]
    B -->|other| D[hold_note required - shown to customer]
    C --> E[Customer uploads invoice in app]
    E --> F[POST /api/packages/customer/id/invoice]
    F --> G[Staff notified - invoice_uploaded]
    G --> H[Admin reviews the file]
    H --> I[Admin changes the status]
    I --> J[Hold fields cleared automatically]
    J --> K[Continues to ready_for_pickup or in_transit]
      

Home pickup booking flow

A home pickup is a request for a driver to collect a parcel from the customer's address. It is stored as a shipment row flagged is_pickup = 1 and follows the pickup part of the status lifecycle.

stateDiagram-v2
    [*] --> pending : booked in app with date and address
    pending --> approved : admin accepts and assigns driver
    pending --> rejected : admin declines
    pending --> cancelled : customer cancels
    approved --> ready_for_pickup : parcel collected to warehouse
    ready_for_pickup --> in_transit : handed to the line haul
    in_transit --> out_for_delivery : loaded on van
    in_transit --> delivered : directly handed over
    out_for_delivery --> delivered : customer signs
    delivered --> [*]
    rejected --> [*]
    cancelled --> [*]
      

Warehouse self-pickup flow

When a package is already at the warehouse and marked ready_for_pickup, the customer can book a counter slot and collect it in person — no driver involved.

flowchart TD
    A[Package status ready_for_pickup] --> B[lifecycle flag can_book_pickup true]
    B --> C[Customer picks date and window in app]
    C --> D[POST /api/packages/customer/id/self-pickup]
    D --> E[Status self_pickup - is_pickup 1 - date and window saved]
    E --> F[Track entry - Warehouse self pickup booked]
    E --> G[Staff notified - self_pickup_booked]
    E --> H[Customer collects at warehouse counter]
    H --> I[Admin marks the package delivered]
      

Push notification flow

Every status change fans out through one service, app/Services/OrderNotify.php, on three channels: database (in-app inbox row), email and push (FCM).

sequenceDiagram
    autonumber
    participant A as Admin panel
    participant O as OrderNotify
    participant N as NotificationService
    participant F as FcmService
    participant G as FCM
    participant P as Customer phone
    A->>O: package or shipment updated
    O->>O: fanout - customer plus active staff minus the actor
    O->>N: createNotification with channels
    N->>N: write the in-app inbox row
    N->>N: pick email template by event type and user role
    N-->>P: queued SMTP email
    N->>F: push channel
    F->>F: checks - fcm enabled - template exists - role allowed - token present
    alt any check fails
        F-->>N: skip push and log the reason
    else all checks pass
        F->>G: HTTP v1 messages:send with service account OAuth
        G->>P: notification on the phone
        F->>F: deactivate dead tokens
    end
      

Payment flow

Orders and packages carry a separate status_invoice column — 2 pending, 3 verify, 1 paid — independent of the shipping status. The app shows the Pay Online button from the lifecycle flag can_pay_online.

flowchart TD
    A[Order with status_invoice 2 pending] --> B{can_pay_online}
    B -->|blocked| X[Pay button hidden]
    B -->|allowed| C[Customer taps Pay Online in app]
    C --> D[Gateway checkout - Stripe PayPal Paystack]
    D --> E[Row in payments_gateway]
    E --> F{gateway status}
    F -->|approved| G[Charge row in charges_order]
    F -->|pending| H[Waits for gateway callback]
    F -->|failed| I[Customer can retry]
    H --> G
    G --> J[status_invoice 3 verify]
    J --> K[Admin confirms - charges must cover total]
    K --> L[status_invoice 1 paid]
    L --> M[Customer notified - payment_confirmed]
      

Consolidation flow

Consolidation merges several shipments or customer packages into one CON order so they travel and clear customs together.

flowchart TD
    A[Admin opens Consolidations - Create] --> B{Source type}
    B -->|shipments| C[Pick add_order tracking numbers]
    B -->|packages| D[Pick customers_packages tracking numbers]
    C --> E[Minimum two items required]
    D --> E
    E --> F[CON tracking number generated]
    F --> G[Row in consolidate or consolidate_packages]
    G --> H[Rows in consolidation_items link each child]
    H --> I[Children flagged is_consolidate 1 - status consolidate]
    H --> J[Customer notified - package_consolidated]
    I --> K[CON order lifecycle - pending to delivered]
    K --> L[delivered as one unit]
      

User app session flow

On every launch the user app runs the same gate sequence before showing content — connectivity first, then auth, then onboarding (cargoproapp/lib/main.dart).

flowchart TD
    S[App start] --> T[Splash while services init]
    T --> U[ApiService init - status catalog warm up - language load]
    U --> C{Connectivity}
    C -->|offline| N[NoInternetScreen with retry]
    C -->|online| A{Auth state}
    A -->|logged in| AD{Address on file}
    AD -->|missing| R[RequiredAddressScreen]
    AD -->|present| M[MainNavigation]
    A -->|guest| OB{Onboarding seen}
    OB -->|no| O[OnboardingScreen]
    OB -->|yes| L[LoginScreen]