# 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`.