Booking & Delivery Flow

1. Overview & the two entry points

A RideChain booking can begin in two completely different places, and the most important thing to understand up front is this: you do not need to walk into a RideChain Point to book. The overwhelming majority of bookings are self-serve from a phone. A "Point" is a physical handover venue (and a fallback for people without a smartphone), not a booking counter you must visit.

flowchart TB
  subgraph Digital["Entry A · Digital self-serve (phone, no travel)"]
    BA["📱 Book app (Flutter)"]
    WEB["💻 Next.js PWA (web)"]
    WAB["💬 WhatsApp bot"]
    IVR["📞 IVR / missed-call"]
  end
  subgraph Assisted["Entry B · Walk-in at a RideChain Point"]
    OP["🧑‍💼 Kirana / CSC operator
books on customer's behalf"]
  end
  BA & WEB & WAB & IVR --> API["Go booking API"]
  OP --> API
  API --> SM["Booking state machine
(DRAFT → QUOTED → … → SETTLED)"]
  classDef d fill:#e8f0fb,stroke:#1f5fae,color:#143d6e;
  classDef a fill:#fff3e0,stroke:#f4920b,color:#8a5200;
  class BA,WEB,WAB,IVR d; class OP a;
        

2. Pickup & drop modes (DOOR vs POINT)

At booking time the booker chooses a pickup mode and a drop mode, each independently DOOR or POINT. These four combinations are the single biggest lever on price and speed: a door visit is dedicated partner time (premium), while a Point lets the parcel ride a shared, batched milk-run (cheapest).

Speed tiers map onto modes: Urgent / on-demand wants a dedicated partner (favours DOOR ends); Express mixes a dedicated leg with a Point; Bundled milk-run requires POINT → POINT so the parcel can be batched. See Commission & Pricing for the fare formula and surge.

3. The booking creation flow

Creation walks the booker through five inputs, produces a live quote, takes payment into escrow, then matches a partner. Pricing, payment and matching are separate idempotent steps — none assumes a single happy reply, and payment is only confirmed by the PG webhook, never by the client's own "I paid" message.

1. Choose pickup & drop modes — DOOR/POINT for each end, with addresses or a Point picked from the map.
2. Describe the package — category, size bucket (S/M/L/XL), weight bucket, and flags: fragile, perishable, urgent, oversized.
3. Engine recommends a vehicle — from size/weight/flags/geo; the booker may override (e.g. force a Bolero for a bulky item).
4. Live price quote — pricing returns fare + breakdown for the chosen tier; re-quoted if any input changes.
5. Pay into escrow — a gateway order is created (Razorpay primary → Cashfree fallback); funds are held, the platform holds no money.
6. Match & assign — bundling-first, then on-demand cascade; the booker receives the assigned partner + ETA and live tracking begins.

sequenceDiagram
  autonumber
  participant U as "Booker (app / web / WA / operator)"
  participant GW as "Go booking API"
  participant PR as Pricing
  participant PAY as "Payments + escrow"
  participant PG as "Gateway (RZP → CF)"
  participant MA as Matching
  participant PT as "Partner app"
  U->>GW: "Choose pickup/drop modes + addresses"
  U->>GW: "Package: category, size S/M/L/XL, weight, flags"
  GW->>PR: "Recommend vehicle (size, weight, flags, geo)"
  PR-->>U: "Suggested vehicle (user may override)"
  U->>GW: "Confirm vehicle + speed tier"
  GW->>PR: "quote(modes, vehicle, tier, geo)"
  PR-->>U: "Live price + breakdown"
  U->>GW: "Confirm + place booking (idempotency-key)"
  GW->>PAY: "Create escrow order"
  PAY->>PG: "Order (Razorpay, fallback Cashfree)"
  PG-->>U: "Payment intent (UPI / wallet)"
  U->>PG: "Pay"
  PG-->>PAY: "WEBHOOK: captured (source of truth)"
  PAY-->>GW: "Escrow held (idempotent)"
  GW->>MA: "Dispatch (bundling-first → on-demand)"
  MA->>PT: "Offer leg(s)"
  PT-->>MA: "Accept"
  MA-->>U: "Assigned partner + ETA, live track begins"
        

4. The booking state machine

A booking is a finite state machine. The happy path threads from DRAFT to SETTLED; every off-ramp (no partner, cancellation, failed handover, dispute) is an explicit side state with defined money behaviour. Relay bookings loop through AT_HUB once per intermediate leg.

stateDiagram-v2
  [*] --> DRAFT
  DRAFT --> QUOTED: "price returned"
  QUOTED --> PAYMENT_PENDING: "place booking"
  PAYMENT_PENDING --> ESCROW_HELD: "PG webhook captured"
  PAYMENT_PENDING --> CANCELLED_BY_BOOKER: "abandon / timeout"
  ESCROW_HELD --> MATCHING: "dispatch"
  MATCHING --> ASSIGNED: "partner accepts"
  MATCHING --> NO_PARTNER_FOUND: "cascade exhausted"
  NO_PARTNER_FOUND --> REFUNDED: "auto-refund escrow"
  ASSIGNED --> EN_ROUTE_PICKUP: "partner moving"
  ASSIGNED --> CANCELLED_BY_PARTNER: "partner drops"
  EN_ROUTE_PICKUP --> AT_PICKUP: "geofence reached"
  AT_PICKUP --> PICKED_UP: "pickup OTP verified"
  AT_PICKUP --> FAILED_PICKUP: "sender absent / refused"
  PICKED_UP --> IN_TRANSIT
  IN_TRANSIT --> AT_HUB: "relay leg"
  AT_HUB --> IN_TRANSIT: "next leg assigned"
  IN_TRANSIT --> AT_DROP: "final leg geofence"
  AT_DROP --> DELIVERED: "drop OTP + POD"
  AT_DROP --> FAILED_DELIVERY: "receiver absent"
  FAILED_DELIVERY --> RETURNED: "reverse logistics"
  DELIVERED --> SETTLED: "escrow released, splits paid"
  CANCELLED_BY_BOOKER --> REFUNDED
  CANCELLED_BY_PARTNER --> MATCHING: "re-dispatch"
  FAILED_PICKUP --> REFUNDED
  DELIVERED --> DISPUTED: "complaint window"
  DISPUTED --> SETTLED: "resolved in favour of partner"
  DISPUTED --> REFUNDED: "resolved in favour of booker"
  RETURNED --> REFUNDED
  SETTLED --> [*]
  REFUNDED --> [*]
        

5. OTP & POD handover

RideChain uses four OTPs across a booking, each closing a specific trust gap, plus a geo- and time-stamped Proof-of-Delivery photo and a tamper-evident QR on the parcel.

On top of OTPs, every handover records a POD photo stamped with GPS + timestamp (stored in Cloudflare R2) and a QR scan of the parcel's unique ID. The QR scan must match the assigned parcel or the app blocks the handover — this is what stops a wrong parcel being given out.

flowchart LR
  A["Partner reaches drop geofence"] --> B{"Scan parcel QR"}
  B -- "mismatch" --> X["Block: wrong parcel"]
  B -- "match" --> C["Receiver reads drop OTP"]
  C --> D{"OTP correct?"}
  D -- "no" --> R["Retry / fallback channel"]
  D -- "yes" --> E["Capture POD photo (GPS + time)"]
  E --> F["Mark DELIVERED → release leg escrow"]
        

6. Delivery journey — direct vs relay

A booking decomposes into ordered legs. A direct booking (Mode A) is one leg, one partner, door-to-door or Point-to-door. A relay / milk-run booking (Mode B) is multiple legs that pass through a Block Hub for consolidation, each leg a different partner. Money splits per leg, and each leg releases on its own handover.

flowchart TB
  subgraph ModeA["Mode A · Direct (one leg)"]
    SA["Sender"] -->|"pickup OTP"| PA["Partner A"]
    PA -->|"drop OTP + POD"| RA["Receiver"]
  end
  subgraph ModeB["Mode B · Relay / milk-run (multi-leg via Hub)"]
    SB["Sender / origin Point"] -->|"pickup OTP, leg 1"| PB1["Partner A"]
    PB1 -->|"handover at hub"| HUB["🏬 Block Hub
consolidate"]
    HUB -->|"leg 2 assigned"| PB2["Partner B"]
    PB2 -->|"drop OTP + POD, leg 2"| RB["Receiver / dest Point"]
  end
  classDef hub fill:#fff3e0,stroke:#f4920b,color:#8a5200;
  class HUB hub;
        

The custody chain holds each parcel to exactly one partner per leg via four interlocking controls: an assignment lock, the unique parcel-ID / QR scan, the two-sided handover OTP, and a geofence + timestamp. A partner may serve many Points (coverage), but a given parcel is locked to one Point + one partner per leg.

7. Cancellation, failed pickup/delivery, returns & refunds

Who can cancel — and at what cost — depends on the state at the moment of cancellation. The rule of thumb: before ESCROW_HELD, cancels are free/full-refund; after a partner has started or completed work, work already done is paid for.

Reverse logistics: a return creates a new leg in the opposite direction (receiver/drop-Point → sender/origin-Point), re-using the same custody controls. The partner who carries the return leg is paid for it; the booker is refunded the value of the service not rendered (delivery), net of any return-leg charge.

8. No-app & low-literacy support

Rural reach means many bookers have no smartphone, intermittent data, or low literacy. The flow degrades gracefully across channels and reading levels.

9. Edge cases & failure modes

The booking flow is built assuming the unhappy path is the common path. Each risk below has a defined mitigation; the full catalogue lives in the Edge-Case Catalog.