Geolocation

1. Overview — geolocation is the spine

Almost every interesting thing RideChain does leans on knowing where something is. Geolocation underpins matching (which partners are near this pickup?), routing (how do we get there cheapest?), live tracking (where is my parcel right now?), geofenced handovers (one of the four custody checks), and fraud detection (is this GPS even real?). It is less a feature and more the coordinate system the rest of the platform is drawn on.

Two stores carry the geo load, with a deliberate split of duties:

flowchart TB
  subgraph Apps["Edge apps (Flutter / PWA)"]
    PT["🛵 Partner app
streams location"]
    BK["📱 Book app
live track + ETA"]
  end
  PT -->|"WebSocket fixes"| GEO["Go geo module"]
  GEO -->|"GEOADD / GEOSEARCH"| RDS[("Redis geo sets
live positions · ETAs")]
  GEO -->|"durable writes / KNN"| PG[("PostgreSQL + PostGIS
Points · geofences · addresses")]
  GEO -->|"nearest online partners"| MATCH["🎯 Matching"]
  GEO -->|"snapped path"| ROUTE["🧭 Routing (OSRM)"]
  GEO -->|"fence + timestamp events"| CUST["🔒 Custody / handover"]
  GEO -->|"plausibility signals"| FRAUD["🚨 Fraud module"]
  RDS -->|"pushed fixes + ETA"| BK
  classDef hot fill:#fff3e0,stroke:#f4920b,color:#8a5200;
  classDef dur fill:#e8f0fb,stroke:#1f5fae,color:#143d6e;
  class RDS hot; class PG dur;
        

2. The rural addressing problem (and how we resolve it)

The hardest geo problem in the Indian interior is not GPS accuracy — it is that most homes have no usable postal address. "Ramu's house behind the temple, near the big neem tree" is a real, deliverable address to a local and a useless one to a database. RideChain cannot demand a pin-perfect lat/long from a first-time rural sender, so it accepts fuzzy input and resolves it down to something a partner can actually reach.

The resolver tries these in order of confidence, falling back gracefully, and always offers the Point as a known anchor when door-level resolution is too uncertain. Crucially, much of this works offline: a packaged village + landmark gazetteer lets the app suggest a deliverable area code even with no data, deferring the precise pin until sync.

flowchart TB
  IN["Fuzzy address input"] --> Q{"Have a map pin?"}
  Q -- "yes" --> SNAP["Snap pin to road / building"]
  Q -- "no" --> SAVED{"Matches a saved address?"}
  SAVED -- "yes" --> USE["Reuse stored coordinate"]
  SAVED -- "no" --> CODE{"3-word / grid code given?"}
  CODE -- "yes" --> DECODE["Decode to ~3 m square"]
  CODE -- "no" --> LAND{"Landmark in gazetteer?"}
  LAND -- "online" --> GEOCODE["Geocode village + landmark"]
  LAND -- "offline" --> OFFLINE["Offline fallback:
village centroid + landmark note"]
  LAND -- "ambiguous" --> CLARIFY["Operator / voice clarifies"]
  SNAP --> SCORE["Confidence score"]
  USE --> SCORE
  DECODE --> SCORE
  GEOCODE --> SCORE
  OFFLINE --> SCORE
  CLARIFY --> SCORE
  SCORE --> LOW{"Confidence below threshold?"}
  LOW -- "yes" --> ANCHOR["Offer nearest RideChain Point as anchor"]
  LOW -- "no" --> SAVE["Persist geography(Point) + save address"]
  ANCHOR --> SAVE
        

3. Live tracking architecture

Live tracking has to feel real-time to the booker while costing the partner almost no battery or data — non-negotiable on a budget Android phone in a low-signal village. The Partner app streams fixes over a WebSocket to the Go geo module, which writes the live position into the Redis geo index and pushes derived position + ETA on to the Book app.

sequenceDiagram
  autonumber
  participant PT as "Partner app"
  participant GEO as "Go geo module"
  participant RDS as "Redis geo index"
  participant ETA as "ETA / routing"
  participant BK as "Book app"
  PT->>GEO: "WS connect (job-scoped, authed)"
  loop "Adaptive sampling"
    PT->>GEO: "Location fix (lat, lng, accuracy, speed, ts)"
    GEO->>RDS: "GEOADD live position"
    GEO->>ETA: "Recompute ETA if moved enough"
    ETA-->>GEO: "ETA + remaining distance"
    GEO-->>BK: "Push position + ETA"
  end
  Note over PT,GEO: "Near pickup/drop → sample faster; idle → slower"
  PT-->>GEO: "Offline: buffer fixes locally"
  PT->>GEO: "On reconnect: replay buffered fixes (deduped by ts)"
        

Adaptive sampling is the battery trick: the app raises the GPS sampling rate when the partner is close to a pickup or drop (where precision matters and the booker is watching), and drops it right down when the partner is idle, far away, or stationary. The geo module can also push the desired cadence to the device based on job state.

4. Geofencing & the custody check

A geofence is a region — a circle (centre + radius) or a polygon — drawn around a place that matters: a RideChain Point, a pickup door, a drop door, or a Block Hub. Entering the right geofence, together with a trusted server timestamp, is one of the four custody checks a handover must pass — alongside the assignment lock, the unique parcel-ID/QR scan, and the two-sided handover OTP (see Last-Mile Delivery).

flowchart LR
  FIX["Partner location fix"] --> CHK{"Inside the handover
geofence?"}
  CHK -- "no" --> WAIT["Hold: handover blocked,
guide partner closer"]
  CHK -- "yes" --> ACC{"Accuracy within
threshold?"}
  ACC -- "no" --> WAIT
  ACC -- "yes" --> STAMP["Server stamps entry time"]
  STAMP --> GATE["Geofence custody check PASSED"]
  GATE --> NEXT["Proceed to QR scan + OTP"]
        

Containment is evaluated server-side with PostGIS: ST_DWithin(point, fence_centre, radius) for circular fences and ST_Contains(polygon, point) for polygons, both backed by GiST indexes. Radii are tunable per Point because a tight 30 m fence that works in a town is hopeless beside a sprawling rural Point with poor GPS — see the edge-case note on fence sizing.

5. Nearest queries — who is closest?

The question matching keeps asking is: "which eligible, online partners are nearest to this pickup, right now?" Geolocation answers it from both stores. Redis gives the fast first cut over live positions; PostGIS refines with durable eligibility and exact geo predicates.

1. Redis GEOSEARCH — pull all online partners within an expanding radius of the pickup from the live geo set, ordered by distance. Sub-millisecond, no disk.
2. PostGIS KNN refine — for the candidate set, apply durable eligibility (vehicle type, service area, rating, capacity) and exact distance with the <-> KNN operator over a GiST index.
3. Hand to matching — the ranked, eligible shortlist feeds the dispatch cascade in Nearest-Partner Matching.

flowchart TB
  PICK["Pickup location"] --> RDS[("Redis GEOSEARCH
radius, online only")]
  RDS --> CAND["Candidate partners
(by distance)"]
  CAND --> PGQ[("PostGIS KNN refine
eligibility + exact distance")]
  PGQ --> SHORT["Ranked eligible shortlist"]
  SHORT --> MATCH["🎯 Matching cascade"]
  SHARD["Geo-sharding by region / block"] -.->|"scopes the search space"| RDS
  SHARD -.-> PGQ
        

6. Coordinate handling & accuracy

A GPS fix is never a point — it is a point plus an accuracy radius, and in rural / forest / low-signal terrain that radius can balloon. RideChain treats accuracy as a first-class field on every fix and refuses to pretend a ±200 m fix is a doorstep.

Two corrections run on the stream. Snapping projects a raw fix onto the nearest plausible road segment (via the OSRM road network used in Fastest-Route Finding) so a track looks like a road journey, not a drunkard's walk across fields. Jitter / drift smoothing rejects physically impossible jumps and lightly filters scatter while a device is stationary, so a parked partner does not appear to wander.

7. Anti-spoofing & fraud

Because geofence + timestamp is a money-releasing custody check, a faked location is an attack on the ledger. The geo module feeds the fraud module a set of plausibility signals and flags fixes that cannot be trusted; a flagged fix can block escrow release until a human confirms.

flowchart TB
  FIX["Incoming location fix"] --> MOCK{"Android mock-location
flag set?"}
  MOCK -- "yes" --> FLAG["Flag + block release"]
  MOCK -- "no" --> SENSOR{"Sensors agree?
(accelerometer · cell tower)"}
  SENSOR -- "implausible" --> FLAG
  SENSOR -- "ok" --> SPEED{"Speed plausible?
(no teleport jump)"}
  SPEED -- "impossible" --> FLAG
  SPEED -- "ok" --> ROUTEP{"On a plausible route?"}
  ROUTEP -- "no" --> SOFT["Soft-flag: extra review"]
  ROUTEP -- "yes" --> TRUST["Accept fix"]
  FLAG --> FRAUD["🚨 Fraud module:
require manual confirm"]
  SOFT --> FRAUD
        

• Mock-location flag — Android exposes when a fix comes from a mock provider; that is an immediate hard flag.
• Sensor cross-check — accelerometer movement and the serving cell tower / Wi-Fi must be roughly consistent with the reported position; a "moving" device whose accelerometer is dead is suspicious.
• Impossible-speed / teleport — two fixes that imply 900 km/h between them cannot both be real.
• Route plausibility — a fix far off any road the partner could have taken to get there earns at least a soft flag.

8. Location privacy

Live location is sensitive personal data, and RideChain handles it under India's DPDP Act with explicit consent and tight scoping. The guiding principle: a partner's whereabouts are shared only as much as a live job requires, only while it is live.

9. Edge cases & failure modes

Geolocation in the interior is unreliable by default, so every failure mode below has a defined behaviour that degrades gracefully rather than blocking a delivery. The full cross-component catalogue lives in the Edge-Case Catalog.