DieselDepot-APP/AGENTS.md

Diesel Depot — agent notes

Project at a glance

Next.js 14 PWA + PocketBase. Tracks diesel stock across depots, fleet deliveries, internal usage, evaporation losses; bridges to Sage for invoicing.

Workspace: /Volumes/EXT/DEVELOPMENT/MINIMAX/DIESEL_DEPOT Dev server: npm run dev → http://localhost:4002 (not 3000 — WFDASH uses 3000/4001) Backend PB: http://pocketbase-zinlbpsext2ro0lgb2558vfy.169.239.180.130.sslip.io Collection prefix: dd_ (diesel_depot) — every new collection MUST start with this.

Collections (all dd_ prefixed)

Name	Type	Purpose
dd_depots	base	Lumelela Depot (LUM), Fanie Plot (FAN) — coords in seed
dd_trucks	base	Capacity, current balance, current km
dd_clients	base	Customer master + default_lat/lng for v2 anomaly
dd_users	auth	Drivers / pump attendants / admin / owner
dd_delivery_notes	base	Meter readings, photo, signature, status, qty

Internal transfers / invoice bridge / evaporation are deferred to v2.

PB instance quirks (this instance)

• The superuser collection is named _superusers (not _admins). Token has collectionId: pbc_3142635823 and type: "auth" (not "admin").
• /api/admins/auth-with-password returns 404 here — always use /api/collections/_superusers/auth-with-password or save the token directly.
• See scripts/create-collections.mjs for the two-pass relation creation pattern (relations need the real collectionId UUID, not the name).

Seeded data

• Depots: Lumelela Depot (LUM) and Fanie Plot (FAN) at 23,000 L each (real Carletonville coordinates)
• Owner user: owner@dieseldepot.local / changeme — change on first login
• Starter truck: TBD-0001 (rename once fleet registration is known)

Things to remember when extending

1. The form uses FormData to upload files. pb().collection().create(fd) works.
2. meter_continuity_status enum: green / yellow / red. Adding new values needs a UI change in the PB admin first (per the WFDASH gotcha).
3. New collections/fields must use the dd_ prefix to avoid colliding with other apps on the same PB (customers, delivery_notes, fuel_purchases, suppliers, customer_pricing, monthly_price_increases, statement_log, fuel_settings already exist and are used by other code on this instance).
4. PWA service worker is a stub (public/sw.js) — no offline cache in v1.
5. Tailwind palette: brand #1f4e8c, amber #e8a02a, red-alert #c8312a.