Originator / Customer Journey

Role: Creates orders and initiates cargo into the custody chain
Org: External (trader, farmer, SME, aggregator)
Scope: Own orders only
Note: An Originator can also be the Designee on the same or a different order (e.g. a trader who ships and receives their own goods)

---

Preconditions

• Has a valid phone number
• Has a physical ID
• Has a compatible device

---

1. Registration

Step 1.1: Identity Registration

• Same supervised onboarding flow as Operator
• Admin creates profile with: fullName, phoneNumber, idType, idNumber, trustTier
• Status set to PENDING_VERIFICATION

Step 1.2: Authentication

• Login via phone number → SMS OTP → access token
• Device binding required before order creation

---

2. Creating an Order

Step 2.1: Define Order

• Originator creates an order specifying:
  • Origin: Name + GPS coordinates (e.g. "Techiman Market")
  • Destination cluster: e.g. BOLGATANGA_CORRIDOR
  • Containers: One or more, each with:
    • designeePhoneNumber, mandatory, sole physical identifier on container (BR-02)
    • declaredCount, expected number of units
    • packagingType, SACK, CRATE, CARTON, BUNDLE, or OTHER
• System creates: orderId, containerIds[]
• Order status: AWAITING_ORIGIN_SCAN
• Errors: INVALID_CONTAINER_COUNT, MISSING_DESIGNEE_PHONE_NUMBER

Step 2.2: Multiple Containers / Designees

• One order can have many containers with different designees
• Each container must have exactly one designeePhoneNumber
• Multiple containers may share the same designee
• Order only moves to ReadyForDispatch when all containers pass origin scan

Order State Machine

Draft → AwaitingOriginScan → ReadyForDispatch → InTransit → Delivered → Completed
                           ↘ OnHold → AwaitingOriginScan (rescan requested)
                                                         ↘ OnHold (integrity hold mid-transit)
Draft / AwaitingOriginScan / ReadyForDispatch / InTransit → Cancelled

---

3. Origin Scan

Business Rule BR-01: No order may enter ReadyForDispatch without a validated origin scan for all containers.

Step 3.1: Initiate Origin Scan

• Originator (or delegated operator) creates a scan record
• Scan type: ORIGIN
• Submits GPS and timestamp

Step 3.2: Capture Video

• Video must show:
  • Designee phone number written on the container (OCR-matched by server)
  • Container packaging and condition
  • Full container visibility

For loose produce (M1A: AI Produce Heap Scan):

• Multi-angle scan of produce heap
• Physical phone-number card used as visual anchor
• AI outputs:
  • Crop type identification + confidence
  • Quality grading (A/B/C)
  • Volume estimation (photogrammetry)
  • Weight estimation (bounded range)
  • Recommended containerisation plan (# of sacks/crates)
• Outputs are planning-grade (not trade-settlement-grade) in early adoption
• Second capture or supervisor review triggered if confidence is below threshold

Step 3.3: Upload & Submit

• Get presigned upload URL (valid 900 seconds)
• Upload video to object storage
• Submit to trigger AI assessment

Step 3.4: OCR Phone Number Validation (BR-02)

• Server extracts phone number from video via OCR
• Compares to designeePhoneNumber declared on container
• If OCR confidence ≥ OCR_CONFIDENCE_MIN policy: auto-accepted
• If OCR confidence < threshold: manual confirmation required with audit trail
• If mismatch: container blocked from dispatch (BR-07)

Step 3.5: AI Integrity Assessment

Outcome	Container State	Order State
PASS / PASS_WITH_TOLERANCE	Created → OriginVerified	→ ReadyForDispatch (when all containers pass)
HOLD	Created → OnHold	→ OnHold
FAIL	Blocked	Escalated

If OnHold: Originator must rescan. Order returns to AwaitingOriginScan.

---

4. Tracking an Order

Step 4.1: Monitor Order State

• Originator can query order status at any time
• States: ReadyForDispatch → InTransit → Delivered → Completed

Step 4.2: Container-Level Visibility

• Each container shows:
  • Current state
  • Current custody operator ID
  • Last known location (from operator's telemetry heartbeat)

Step 4.3: Notifications

Originator receives SMS/Push notifications on:

• Origin scan result (PASS or HOLD)
• Order dispatched (first pickup confirmed)
• Integrity hold raised mid-transit
• Delivery confirmed
• Settlement finalised

Step 4.4: Enterprise Dashboard (if M12 enabled)

• Full order/container status view
• Exception management
• SLA visibility
• Evidence access (scan videos, integrity assessments)
• Custody chain visualisation

---

5. Delivery Confirmation

Step 5.1: Delivery Scan by Operator

• Final operator performs DELIVERY scan
• Designee confirms via SMS OTP
• Container state: InCustody → Delivered → Closed

Step 5.2: Order Completed

• Order: InTransit → Delivered → Completed (after settlement)
• Originator receives delivery confirmation notification

Step 5.3: Evidence Access

• Originator can access:
  • Delivery scan video
  • Delivering operator identity
  • Timestamp and GPS of delivery
  • Full integrity assessment history
• Useful for dispute, reconciliation, or compliance reporting

---

6. Common Scenarios

Scenario A: Farmgate Intake with Loose Produce

1. Farmer/aggregator brings loose produce to intake point
2. Produce heap is scanned (M1A), crop ID, grade, volume, weight estimated
3. Estimates inform containerisation (e.g. 4 sacks recommended)
4. Containers created, linked to original heap scan evidence
5. Order created with container references
6. Standard custody chain proceeds

Scenario B: Trader with Multiple Designees

1. Trader creates one order, multiple containers, each with a different designee phone
2. All containers must pass origin scan individually
3. Order not dispatched until all containers are OriginVerified

Scenario C: Originator is Also the Designee

1. Trader ships goods to their own receiving depot
2. Same phone number appears as both Originator and Designee
3. System supports this, no conflict

Scenario D: Dispute (Originator View)

1. Designee reports non-receipt or damage
2. Originator queries event trail for the container
3. Supervisor reviews custody chain (origin → handoffs → delivery)
4. Liability window identified (last PASS scan to first HOLD/FAIL)
5. Outcome: operator refund, or re-shipment decision

---

Edge Cases

Scenario	Behaviour
Origin scan fails OCR check	Container blocked from dispatch; rescan required
Produce heap confidence too low	Second capture triggered; supervisor may review
One of many containers fails origin scan	Entire order held in OnHold until all containers pass
Order cancelled mid-transit	Subject to cancellation policy; held containers resolved by supervisor

---