WFDASH-WEBAPP/docs/driver-app-data-source.md

Driver App — Data Source & Integration Notes

Audience: the agent building the driver-facing app. Author context: WFDash is the operator app (Next.js + PocketBase). This doc describes how the driver app should read the same data so the operator's "Assign driver" action on /collection-map shows up on the driver's phone in real time.

---

TL;DR

A driver's stop list = every order_items row where drv_id == currentDriver.id and item_status == "assigned", regardless of the ready_for_collection flag. Show ready rows one colour, not-yet-ready rows another colour. Do not filter ready_for_collection server-side — that flag controls whether the operator may assign the row, not whether the driver should see it once assigned.

Worked example

"Bright Packaging" supplier, assigned to Driver A. The supplier has 6 items on the same PO:

id	item_status	drv_id	ready_for_collection	what driver sees
1	assigned	A	true	blue pill — "Ready"
2	assigned	A	true	blue pill — "Ready"
3	assigned	A	true	blue pill — "Ready"
4	assigned	A	false	amber pill — "Waiting — ask supplier"
5	assigned	A	false	amber pill — "Waiting — ask supplier"
6	assigned	A	false	amber pill — "Waiting — ask supplier"

The driver app should show all 6 under one supplier card. The driver picks up the 3 ready items and asks the supplier about the other 3 — that's the whole point of surfacing both states.

---

1. Topology

┌──────────────┐    HTTPS    ┌─────────────────────┐
│ Driver App   │ ──────────► │ WFDash Next.js API  │  (recommended)
│ (mobile)     │             │ /api/v1/...         │
└──────────────┘             └──────────┬──────────┘
                                       │ admin client
                                       ▼
                              ┌─────────────────────┐
                              │ PocketBase          │
                              │   - order_items     │
                              │   - suppliers       │
                              │   - users (drivers) │
                              └─────────────────────┘

Two reasonable shapes:

1. Through the WFDash API — easier to evolve, single auth surface, but WFDash already does its own UI-side loading; no dedicated driver endpoint exists yet. You'll need to either add one or call an existing route.
2. Direct PocketBase — driver app talks to PB with its own auth. Faster, but you re-implement filters, expansions, and auth yourself.

Recommendation: start direct-to-PocketBase for the read path. The schema is small and the filters are simple. Add a WFDash proxy only if you need server-side validation (e.g., before letting the driver mark something collected).

---

2. Source collection: order_items

This is the canonical row. The operator's "Assign driver" modal on /collection-map flips these fields:

field	type	meaning
item_status	select	One of pending, processed, po_generated, collection_pool, assigned, collected, stock_verified, picking, ready_delivery, delivered, cancelled. For driver app purposes, you care about assigned (in your list) and collected (you've picked it up — drop from list or move to history).
drv_id	relation → users	The driver this row is assigned to. Filter on this.
drv_status	select	Operator-side mirror of item_status for drivers — unassigned, assigned, en_route, collected, failed. You can ignore this; item_status is the truth.
drv_assigned_at	date	When the operator hit "Assign". Sort by this if you want a "newest first" list.
ready_for_collection	bool	Operator-side gate. Set to true by /collection-pool "Mark ready". Do not filter on this — surface it as a colour.
notes	text	Operator note (often set alongside ready_for_collection=true, e.g. "Boxes at back loading dock"). Show this prominently when set.
supplier	relation → suppliers	Expand to get suppliername, email, coordinates (semicolon-separated "lat;lng" string in WFDash), phone, etc.
description	text	Item description.
quantity	number	Quantity ordered for this line.
po_description	text	PO-level description if different from the item line.
order	relation → orders	Expand to get order_number.
purchase_order	relation → purchase_orders	Expand to get po_number.

Other fields you can ignore (for now)

cost_price, selling_price, markup, markup_percent, qty_*, problem_flag, problem_type, problem_notes, legacy_order_item_id, in_stock, driver_status, delivery_status, invoice_status, delivered_at, drv_collected_at.

---

3. The driver-stop query

PocketBase filter syntax

collection: order_items
filter: drv_id = "<driverId>" && (item_status = "assigned" || item_status = "collected")
sort: -drv_assigned_at
expand: supplier, purchase_order, order

• drv_id is a relation, so in PocketBase filter syntax you compare against the relation's record id.
• item_status — include assigned (active work) and optionally collected (just-picked-up, before the operator flips it forward). Do not include collection_pool (operator hasn't picked a driver), delivered/cancelled (terminal), or anything else.
• Expand keeps you off N+1 lookups. PB will inline supplier / PO / order objects.

Important: do NOT add ready_for_collection=true to the filter

The operator-side gate that prevents assignment does not mean the driver should be blind to unready items. The whole point is for the driver to nudge the supplier ("by the way, I see you have a few more items on the PO — are they ready too?"). Server-side filtering on ready_for_collection defeats the purpose.

---

4. UI — colour and grouping

Match WFDash's existing palette so when an operator looks over the driver's shoulder it lines up:

State	Pill label	Colour (Tailwind)
item_status == "collected"	"Collected"	emerald — bg-emerald-100 text-emerald-900 border-emerald-300
ready_for_collection == true (not collected)	"Ready"	blue — bg-blue-100 text-blue-900 border-blue-300
ready_for_collection == false (not collected)	"Waiting — ask supplier"	amber — bg-amber-100 text-amber-900 border-amber-300

Counts strip per driver (header)

6 stops · 🟢 0 collected · 🔵 3 ready · 🟠 3 waiting

Hide segments that are zero (omit "0 collected" if nothing's collected yet). This mirrors /collection-map's right-sidebar driver cards exactly.

Grouping

Group rows by supplier.id. Within a supplier, sort however you like. The supplier card header should show the supplier name + the counts strip for that supplier's items:

┌─ Bright Packaging ─────────────────────────┐
│ 6 items · 🔵 3 ready · 🟠 3 waiting        │
│  • 100× Cardboard boxes        [Ready]     │
│  • 50× Bubble wrap rolls        [Ready]     │
│  • 20× Tape dispensers          [Ready]     │
│  • 10× Pallet wrap              [Waiting]   │
│  • 5× Strapping rolls           [Waiting]   │
│  • 2× Stretch film              [Waiting]   │
│                                [Open in maps]│
└────────────────────────────────────────────┘

Notes

If notes is set on a row, surface it inline (the operator often writes "back loading dock", "ask for John", "ring bell"). WFDash renders these as a hover tooltip; in a phone UI a chevron expand or bottom-sheet works fine.

---

5. "What should the driver be able to do?"

Out of scope for this doc, but: the only writes the operator expects from the driver app today are:

• Mark collected — flip item_status from assigned → collected and set drv_status = "collected", drv_collected_at = <now>. The operator's collection-confirm page then handles the rest. Use the existing /api/v1/order-items/<id>/status route (Bearer AGENT_API_KEY) if going through WFDash, or hit PB directly.
• Report a problem — set problem_flag = true, problem_type = "supplier", problem_notes = "<text>". The operator surfaces these on /collection-confirm.

Do not let the driver flip ready_for_collection or reassign themselves — those are operator-only actions.

---

6. Auth

Drivers are PB users records. They log in with email/password (PB's built-in users collection, _pb_users_auth_). The driver app stores the PB auth token after login and passes it as Authorization: <token> on every API call. PB enforces row-level listRule / viewRule (@request.auth.id != '') — drivers will see only what they're allowed to read, which today is all order_items. You'll likely want to tighten that to drv_id = @request.auth.id via PB rule, but that's a schema change — confirm with the WFDash maintainer first.

---

7. What changes you'll need from WFDash

If you go the direct-PB route, you can ship without any WFDash changes — just consume the existing schema and filter.

If you go the WFDash-API route, you'll need one of:

• A new endpoint GET /api/v1/drivers/me/stops that runs the filter above through the admin PB client and returns shaped JSON, or
• A small wrapper around the existing /api/v1/order-items list route (if you want to reuse pagination/auth shape).

Either way, the filter logic is identical to section 3.

---

8. Quick reference — the canonical filter

// PocketBase JS SDK
const stops = await pb.collection("order_items").getList(1, 200, {
  filter: 'drv_id = "' + driverId + '" && (item_status = "assigned" || item_status = "collected")',
  sort: "-drv_assigned_at",
  expand: "supplier,purchase_order,order",
});

Each row in stops.items carries everything section 2 lists. Use expand.supplier.suppliername, expand.supplier.coordinates, etc. for display.

---

9. Open questions for the operator (WFDash maintainer)

• Should drv_status ever diverge from item_status for the driver? (Today they mirror — pick item_status as truth.)
• Should the driver see historical collected items from today, or only active assigned? (collected rows have already moved past the driver's hand — usually safe to drop from the live list, but the operator may want a "today's history" pane.)
• Are PO numbers (po_number) surfaced on the supplier card, or only on drill-in? Operator's map shows po_number; safe default = show on card.