{
  "docVersion": 1,
  "id": "template-ride-hailing-dispatch",
  "name": "Ride-hailing dispatch",
  "purpose": "GPS pings stream through competing consumers into a geospatial cell index; matching is a k-nearest lookup, presence and surge run off the same stream.",
  "nodes": {
    "rider": {
      "type": "mobile",
      "label": "Rider App",
      "x": 20,
      "y": 240,
      "runtime": "request ride"
    },
    "rgw": {
      "type": "websocket",
      "label": "Rider Gateway",
      "x": 280,
      "y": 240,
      "runtime": "held connection"
    },
    "surge": {
      "type": "analytics",
      "label": "Surge Pricer",
      "x": 540,
      "y": 30,
      "runtime": "demand/supply per cell",
      "color": "amber"
    },
    "match": {
      "type": "k8s",
      "label": "Match Service",
      "x": 540,
      "y": 240,
      "runtime": "k-nearest in cell",
      "color": "blue",
      "patterns": [
        "stateless",
        "autoscale"
      ],
      "notes": "The match is a read: k-nearest available drivers from the geo index, filtered by presence, priced by surge."
    },
    "geoidx": {
      "type": "geo",
      "label": "Geo Index",
      "x": 800,
      "y": 110,
      "runtime": "H3 cells · driver positions",
      "notes": "Updated ~4×/s per driver by the location workers. Stale positions are the #1 cause of bad matches — freshness is the SLO."
    },
    "presence": {
      "type": "server",
      "label": "Presence",
      "x": 800,
      "y": 380,
      "runtime": "heartbeats · availability"
    },
    "locstream": {
      "type": "stream",
      "label": "Location Stream",
      "x": 540,
      "y": 520,
      "runtime": "GPS pings · 40k/s"
    },
    "locworkers": {
      "type": "worker",
      "label": "Location Workers",
      "x": 800,
      "y": 520,
      "runtime": "competing consumers ×12",
      "patterns": [
        "autoscale"
      ]
    },
    "dgw": {
      "type": "websocket",
      "label": "Driver Gateway",
      "x": 1060,
      "y": 240,
      "runtime": "offers out · GPS in"
    },
    "driver": {
      "type": "user",
      "label": "Driver App",
      "x": 1320,
      "y": 240,
      "runtime": "accept / decline"
    }
  },
  "edges": {
    "e1": {
      "from": "rider",
      "to": "rgw",
      "fromSide": "right",
      "toSide": "left",
      "label": "request ride",
      "animated": true
    },
    "e2": {
      "from": "rgw",
      "to": "match",
      "fromSide": "right",
      "toSide": "left",
      "animated": true,
      "patterns": [
        "timeout"
      ]
    },
    "e3": {
      "from": "match",
      "to": "geoidx",
      "fromSide": "right",
      "toSide": "left",
      "label": "k-nearest in cell 8a2",
      "animated": true
    },
    "e4": {
      "from": "match",
      "to": "presence",
      "fromSide": "bottom",
      "toSide": "left",
      "label": "really available?"
    },
    "e5": {
      "from": "surge",
      "to": "match",
      "fromSide": "bottom",
      "toSide": "top",
      "label": "×1.4 multiplier",
      "style": "dashed"
    },
    "e6": {
      "from": "match",
      "to": "dgw",
      "fromSide": "right",
      "toSide": "left",
      "label": "offer to driver",
      "animated": true
    },
    "e7": {
      "from": "dgw",
      "to": "driver",
      "fromSide": "right",
      "toSide": "left",
      "dir": "both",
      "label": "offer ⇄ accept"
    },
    "e8": {
      "from": "dgw",
      "to": "locstream",
      "fromSide": "bottom",
      "toSide": "right",
      "label": "GPS pings",
      "style": "dashed",
      "patterns": [
        "batch"
      ]
    },
    "e9": {
      "from": "locstream",
      "to": "locworkers",
      "fromSide": "right",
      "toSide": "left",
      "style": "dashed",
      "patterns": [
        "backpressure"
      ]
    },
    "e10": {
      "from": "locworkers",
      "to": "geoidx",
      "fromSide": "top",
      "toSide": "bottom",
      "label": "update cells"
    },
    "e11": {
      "from": "locstream",
      "to": "surge",
      "fromSide": "top",
      "toSide": "bottom",
      "label": "windowed demand/supply",
      "style": "dashed"
    },
    "e12": {
      "from": "dgw",
      "to": "presence",
      "fromSide": "left",
      "toSide": "right",
      "label": "heartbeats",
      "style": "dashed"
    }
  },
  "boxes": {
    "b1": {
      "x": 500,
      "y": 460,
      "w": 560,
      "h": 230,
      "label": "freshness pipeline — the match is only as good as this",
      "color": "blue",
      "opacity": 0.04
    }
  },
  "texts": {
    "t1": {
      "x": 20,
      "y": 430,
      "text": "why competing consumers:\n40k pings/s, any worker may take any ping —\nadd workers to scale, lose one and\nnothing is waiting on it",
      "color": "blue",
      "size": 12
    }
  },
  "meta": {
    "createdAt": "2026-07-13T09:00:00.000Z",
    "modifiedAt": "2026-07-13T09:00:00.000Z"
  }
}