Operator Journey

Role: Transport worker (tricycle, motorcycle, small truck)
Org: External
Scope: Own assignments only

Preconditions

Has a valid phone number
Has a physical ID (e.g. Ghana Card)
Has a compatible device (PAYG-issued or own device)

1. Onboarding

Step 1.1: Identity Registration (supervised)

A Kaya Sync Admin or Onboarding Officer creates the operator profile
Fields required: fullName, phoneNumber, idType (e.g. GH_CARD), idNumber, trustTier
Trust tiers:
- TIER_1_PAYG, Kaya Sync-issued device, highest trust
- TIER_2_BYOD, Operator's own verified device
- TIER_3_UNVERIFIED, Unverified, restricted privileges
Operator status set to: PENDING_VERIFICATION
Errors: DUPLICATE_OPERATOR, INVALID_ID

Operator enters phone number on device
System sends SMS OTP (expires in 300 seconds)
Operator enters OTP
System returns: accessToken (JWT), refreshToken, operatorId
Errors: INVALID_PHONE_NUMBER, INVALID_OTP, SESSION_EXPIRED, DEVICE_NOT_BOUND

Step 1.3: Device Binding (mandatory)

Operator submits device fingerprint (IMEI/hash/attestation)
System binds device to operator account
Status: BOUND
Device binding is required before any scan or custody action can be performed
Errors: DEVICE_ALREADY_BOUND, DEVICE_TIER_NOT_ALLOWED

State after onboarding: Operator ACTIVE, device BOUND

2. Start of Day (SOD) Attestation

Business Rule BR-09: SOD attestation is mandatory daily. Operators without a valid attestation cannot accept new loads or participate in aggregation plays.

Step 2.1: Create Attestation Record

Operator submits vehicle type, GPS location, and whether vehicle has been altered
Vehicle types: TRICYCLE, MOTORBIKE, SMALL_TRUCK, CORRIDOR_TRUCK, BUS
System returns list of required photos: REAR, LEFT, RIGHT, FLOOR, CEILING, MODIFICATION_CLOSEUP

Step 2.2: Capture & Upload Photos

For each required photo type, operator gets a presigned upload URL (valid 600 seconds)
Operator uploads directly to object storage
Errors: ATTESTATION_NOT_FOUND, INVALID_PHOTO_TYPE

Step 2.3: Submit for AI Assessment

Operator submits attestation
AI estimates vehicle capacity with confidence scoring
Errors: MISSING_REQUIRED_PHOTOS

Attestation State Machine

NotAttested → Captured → Submitted → Valid
                                   ↘ Rejected → Captured (recapture)
Valid → Expired (TTL elapsed, must re-attest next day)

State after SOD: Valid attestation: operator can accept loads

3. Receiving & Accepting an Order

Step 3.1: Order Notification

Operator receives SMS/Push notification of available order
Notification includes: order ID, origin, destination, container count, designee info

Step 3.2: Accept Order

Operator accepts the assignment
Operator becomes currentCustodyOperatorId for all containers on the order
Container state: OriginVerified → InCustody

Precondition: Valid SOD attestation must be active (BR-09)

4. Picking Up Cargo (Origin Scan)

The origin scan is the first verifiable record of cargo condition. No order can be dispatched without it.

Step 4.1: Create Scan Record

Operator creates a scan record for the container
Scan type: ORIGIN
Supplies GPS coordinates and timestamp

Step 4.2: Capture Video

Mobile app guides operator through capture:
- Show designee phone number written on the container (OCR-matched by server)
- Show full container, packaging, and condition
- Video must be live capture (replay detection active)
Works offline, video stored encrypted on device until connectivity returns

Step 4.3: Upload Video

Operator requests a presigned upload URL (valid 900 seconds)
Uploads video directly to object storage
Submits scan to notify server

Step 4.4: AI Integrity Assessment

System automatically assesses the scan:

Outcome	Meaning	Next Step
`PASS`	All checks pass	Container → `OriginVerified`; Order → `ReadyForDispatch`
`PASS_WITH_TOLERANCE`	Minor issues within threshold	Same as PASS
`HOLD`	Mismatch detected	Container → `OnHold`; rescan required
`FAIL`	Severe integrity violation	Escalated to supervisor

Possible reason codes: PHONE_NUMBER_MISMATCH, COUNT_MISMATCH, PACKAGING_CHANGED, DAMAGE_DETECTED, TAMPER_SUSPECTED, LOW_LIGHT, BLUR, VIDEO_REPLAY_SUSPECTED, GPS_MISMATCH, TIME_WINDOW_EXCEEDED

Scan State Machine

CapturedOffline → Uploaded → Validated → Assessed → Archived
                           ↘ Rejected (corrupted/invalid metadata, recapture required)

5. Transporting Cargo

Step 5.1: Telemetry Heartbeat

Device continuously sends telemetry:
- GPS coordinates, heading, speed
- Remaining vehicle capacity (volume + weight)
- Destination intent
Used by Orchestration service for real-time optimisation
Errors: DEVICE_NOT_BOUND, OPERATOR_SUSPENDED

Step 5.2: Aggregation / Disaggregation Recommendations (optional)

System may recommend consolidating loads with another operator
Operator receives: handoff point, counterparty operator ID, estimated carbon saving, risk score
In Phase 1: recommendations only, human approval required
Operator must have valid SOD attestation and trust tier that permits aggregation

6. Performing a Custody Handoff

Business Rule BR-03: Every custody transfer requires dual scans, HANDOVER by the outgoing operator and RECEIVE by the incoming operator.

Step 6.1: Initiate Transfer (Handover Operator)

Handover operator initiates custody transfer
Specifies: container IDs, receiving operator ID, GPS location
Validation: Both operators must be co-located within GEO_PROXIMITY_RADIUS_METRES policy threshold
Transfer status: TRANSFER_PENDING
Errors: OPERATOR_NOT_ELIGIBLE, CONTAINER_NOT_IN_CUSTODY, GEO_PROXIMITY_FAILED

Step 6.2: Perform Handover Scan

Handover operator captures HANDOVER video scan
Same capture workflow as origin scan
Container state: InCustody → TransferPending
After upload: TransferPending → AwaitingReceiveScan

Step 6.3: Perform Receive Scan (Receiving Operator)

Receiving operator is notified of pending transfer
Captures RECEIVE video scan at same location
Time between handover and receive scan must be within HANDOFF_TIME_WINDOW_SECONDS

Step 6.4: AI Assessment of Receive Scan

Server compares receive scan to handover scan and baseline fingerprint

Outcome	Container State	Transfer State
`PASS` / `PASS_WITH_TOLERANCE`	`InCustody` (new operator)	Transfer complete
`HOLD`	`IntegrityHold`	Hold, supervisor review required

Payout consequence (BR-04): Handover operator payout triggered only on PASS or PASS_WITH_TOLERANCE. HOLD → payout held in escrow.

7. Completing a Delivery

Step 7.1: Trigger OTP for Designee

Operator arrives at delivery location
System sends SMS OTP to the designee's phone number

Step 7.2: Capture Delivery Scan

Operator captures DELIVERY video scan:
- Shows container condition
- Shows designee phone number on container
- Records GPS and timestamp

Step 7.3: Designee OTP Confirmation

Designee shares OTP with operator
Operator enters OTP into device
System validates OTP
Delivery is not confirmed without valid OTP match

Step 7.4: Delivery Confirmed

Container state: InCustody → Delivered → Closed
Order state: InTransit → Delivered → Completed (after settlement)

8. Receiving Payment (Settlement)

Payout State Machine

Pending → Triggered (integrity PASS + custody transferred)
        → Held (integrity HOLD or anomaly flag)

Triggered → Settled (payment provider success)
          → Failed → Triggered (retry policy)

Held → Released (dispute resolved in operator's favour / supervisor override)
     → Reversed (dispute resolved against operator / fraud confirmed)

Step 8.1: Payout Triggered

System calculates amount and sends to payment provider (mobile money / bank transfer)
Operator receives SMS notification with amount and expected delivery time

Step 8.2: View Payout Status

Operator can view all payouts: status, amount, hold reasons
Statuses: PENDING, TRIGGERED, HELD, RELEASED, SETTLED, FAILED, REVERSED

9. Dispute

Step 9.1: Hold Raised

Integrity assessment returns HOLD or FAIL
Payout moves to HELD state
Operator receives notification with hold reason code

Step 9.2: Evidence Review (Supervisor)

Internal Ops Supervisor reviews evidence bundle:
- All scans linked to container
- Integrity assessments + reason codes
- Operator trust tier and compliance history
- Custody chain visualisation

Step 9.3: Dispute Resolution

Outcome	Payout	Container
Supervisor approves (operator-favourable)	`Held` → `Released` → `Triggered` → `Settled`	`IntegrityHold` → `InCustody`
Supervisor rejects (fraud confirmed)	`Held` → `Reversed`	Closed

All dispute events are immutable in the Event Store.

Edge Cases

Scenario	Behaviour
Operator loses connectivity mid-scan	Video stored encrypted offline; uploaded when connectivity returns
SOD attestation rejected	Operator must recapture photos; cannot accept loads until attestation is `Valid`
Designee unreachable (no OTP response)	Delivery scan held; escalated to Ops Assistant for manual resolution
Aggregation play accepted but counterparty fails receive scan	Integrity hold raised; original handover operator's payout held pending review
Operator's trust tier drops during active order	Restrictions applied; aggregation eligibility suspended; active orders continue

Operator Journey ​

Preconditions ​

1. Onboarding ​

Step 1.1: Identity Registration (supervised) ​

Step 1.2: First Login ​

Step 1.3: Device Binding (mandatory) ​

2. Start of Day (SOD) Attestation ​

Step 2.1: Create Attestation Record ​

Step 2.2: Capture & Upload Photos ​

Step 2.3: Submit for AI Assessment ​

Attestation State Machine ​

3. Receiving & Accepting an Order ​

Step 3.1: Order Notification ​

Step 3.2: Accept Order ​

4. Picking Up Cargo (Origin Scan) ​

Step 4.1: Create Scan Record ​

Step 4.2: Capture Video ​

Step 4.3: Upload Video ​

Step 4.4: AI Integrity Assessment ​

Scan State Machine ​

5. Transporting Cargo ​

Step 5.1: Telemetry Heartbeat ​

Step 5.2: Aggregation / Disaggregation Recommendations (optional) ​

6. Performing a Custody Handoff ​

Step 6.1: Initiate Transfer (Handover Operator) ​

Step 6.2: Perform Handover Scan ​

Step 6.3: Perform Receive Scan (Receiving Operator) ​

Step 6.4: AI Assessment of Receive Scan ​

7. Completing a Delivery ​

Step 7.1: Trigger OTP for Designee ​

Step 7.2: Capture Delivery Scan ​

Step 7.3: Designee OTP Confirmation ​

Step 7.4: Delivery Confirmed ​

8. Receiving Payment (Settlement) ​

Payout State Machine ​

Step 8.1: Payout Triggered ​

Step 8.2: View Payout Status ​

9. Dispute ​

Step 9.1: Hold Raised ​

Step 9.2: Evidence Review (Supervisor) ​

Step 9.3: Dispute Resolution ​

Edge Cases ​