LoadYard — technical spec

Binding law: `../../JAMAICA_TRUST.md`

Stack. Next.js PWA, TypeScript, Postgres, object storage for photos/audio, WhatsApp Cloud API, SMS/WhatsApp OTP. No consumer wallet.

Shared with the other flagship. YardTrade and LoadYard are two skins. Same listings, bids, provider_wallets, OTP, ratings. This skin filters kind = haulage. See `../../ENGINE.md`.

Architecture

[PWA] → [BFF] → listings / matching / ratings / OTP → WhatsApp Cloud (receipts, disputes) → object storage (photos, short audio) → provider ledger (prepaid lead balance — provider money only) [OCR / whisper] optional, never blocking

Browse is public. Auth is phone OTP.
Matching is automated. No dispatch office.
Get three cash bids for this load.

Core APIs

Method	Path	Job
GET	/api/loadyard/browse	Public inventory or board — no login
POST	/api/loadyard/otp/start	Phone OTP
POST	/api/loadyard/otp/verify	Session cookie
POST	/api/loadyard/lead/accept	Deduct provider lead fee
POST	/api/loadyard/complete	Two-way rating unlock
POST	/api/loadyard/wa-export	Image/PDF for WhatsApp
GET	/api/loadyard/export	DPA zip
DELETE	/api/loadyard/account	Delete

Data model (sketch)

users — phone, role (seeker / provider), OTP verified_at
loadyard_listings — public fields only
loadyard_leads — provider_id, seeker_id, fee_jmd, status
ratings — two-way, job_id
provider_wallets — prepaid provider balance for lead fees (not household escrow)
id_checks — licence/TRN photo, reviewer, status
audit_events — append-only

Security

OTP rate limits. No password store.
ID photos encrypted at rest; 90-day review then delete unless dispute hold.
PII scoped. No sale. No JPS/NWC/bank credential fields exist.
Provider wallet is a simple debit ledger. Top-up is Lynk/card to our company account with a receipt — same as buying airtime for ads.
Payee on every card is the truck, yard, or dealer that bid.

Scalability

Parish shards on listing tables. Media on object storage. WhatsApp send queue. Read replicas for browse.

Offline / PWA

Cargo photo or SKU first. Bids cache. OTP after the first bid. WhatsApp share. Same shell as YardTrade.

Service worker caches last browse payload. Writes queue when FLOW/Digicel drops. Shell under 150 KB gzipped.

What we will not build

Custodial household wallets. Escrow. “Pay the job here.” Blockchain settlement. Call-centre IVR.