MEGAINFRA-WEBAPP/docs/multi-site-assessment.md

# Multi-site readiness assessment

> **The question.** The Hills, Cosmo City, Castle Gate, Autumns Gate, Pitsana
> Mills, West Park, and more to come. This is *not* a question about
> multi-tenancy or serving multiple client companies. It is: **does the
> existing per-site model actually hold up as the number of sites and the
> volume of historical data grows, and where does it break?**
>
> This document is the deliverable that matters most. Parts A and B are
> forensic; Part C is the plan.

The codebase today handles a small number of sites (the production
instance is 7-10) with low hundreds of thousands of fuel log rows and
similar counts across timesheets, fixed costs, and PO items. The
assessment below uses those numbers as the current baseline and projects
out to the realistic next year.

---

## Part A — What works today

The data model is already site-aware. Verified against `src/lib/pb-types.ts`:

- 10 of 13 collections carry a `site` relation (`sites`, `employees`,
  `vehicles`, `fixed_costs`, `income_claims`, `purchase_orders`,
  `delivery_notes`, `fuel_logs`, `plant_hours_log`, plus `data_import_batches`
  indirectly through the processed record).
- 9 of those 10 also carry the denormalised `project_code` text. The
  exception is `timesheets`, which carries neither — see
  [§B.5](#5-vehicles-plant-and-employees-moving-between-sites) for the
  consequences.
- The two collection-tables that don't carry site directly
  (`purchase_order_items`, `received_items`) inherit it through their
  parent. They are never queried by site on their own.

**Per-site financials are computed once and reused.** All the math lives
in `src/lib/metrics/` and is consumed by the **Sites** list
(`src/app/dashboard/sites/page.tsx`), the **Site** detail
(`src/app/dashboard/sites/[id]/page.tsx`), the **Overview** monthly-fixed-cost
tile (`src/app/dashboard/page.tsx:100-108`), the **chat** tool layer
(`src/lib/agent/tools.ts`), and the **MCP** server (`src/mcp/server.ts`).
The whole app agrees to the last digit because every figure comes from
the same `computeSiteSpend → computeSiteProjection →
buildWeeklyIncomeVsExpenses` chain.

**The agent resolves sites from free text correctly when the query is
unambiguous.** `src/lib/agent/resolve.ts:21-48` (`resolveSite`) goes
id → exact project code → exact name → substring on either, and returns
`{ kind: "ambiguous", matches: [...] }` rather than guessing. The
chat tool layer's `requireSite` helper
(`src/lib/agent/tools.ts:76-92`) surfaces the ambiguity to the model
as a follow-up question. That is the right behaviour for money
questions.

**Imported data is matched to a site deterministically when the source
has a clean identifier.** The fuel importer
(`src/app/api/fuel-logs/import/route.ts:214-224`) and plant hours
importer (`src/app/api/plant-hours/import/route.ts:237-250`) both
build a `Map<name.toLowerCase(), SiteRecord>` once at the top of the
import and reuse it for every row. The PO process-batch route does the
same through `matchSite` (`src/lib/purchase-order-schema.ts`).

**Bottom line for what works.** Up to roughly 7-10 sites with 6-12
months of history (a few hundred thousand rows per heavy collection),
the app is correct. The Overview and Sites pages render in under ~2
seconds. The chat can answer portfolio questions. Imports run end-to-end
in 5-30 seconds depending on the file.

---

## Part B — Where it breaks

This part walks each of the eight leads the prompt gave me, confirms or
refutes with file:line evidence, and adds the things I found in addition
that the prompt did not list.

### 1. Hard 50-site cap on the Overview page — **CONFIRMED**

**Lead claim:** `src/app/dashboard/page.tsx:64` calls
`pb.collection("sites").getList<SiteRecord>(1, 50, { sort: "name" })`,
and site 51+ silently vanishes from the KPI tiles and the "Attention
required" rail.

**Evidence.**

- `src/app/dashboard/page.tsx:64` — the 50-row fetch.
- `src/app/dashboard/page.tsx:112-113` — `for (const s of sites.items) siteById.set(s.id, s);` uses only the 50 returned items.
- `src/app/dashboard/page.tsx:135-154` — the "Attention required" buckets are built against `siteById` keys, so a fuel log attached to a site beyond the 50-row window has no site in the lookup map and falls into the `(unknown site)` bucket.
- `src/app/dashboard/page.tsx:176` — `attention.okSiteCount = sites.items.length - problemSites.length` — a 51st site that is healthy *is not counted* in either problemSites or okSiteCount, so its fuel logs are simply dropped from the rail.
- `src/app/dashboard/page.tsx:191` — the "Sites" KPI tile label says `data.sites.length`, again the length of the 50-row response.

**Other capped `getList(page, perPage)` calls found.** Grep across `src/`:

| File:line | Call | Cap | Blast radius |
| --- | --- | --- | --- |
| `src/app/dashboard/page.tsx:64` | `sites.getList(1, 50)` | 50 | Overview sites tile, attention rail, sites list at the bottom of the page |
| `src/app/dashboard/page.tsx:69` | `vehicles.getList(1, 1, { filter: "cost_per_hour>0" })` | 1 (just a count) | KPI tile — fine, only `totalItems` is used |
| `src/app/dashboard/page.tsx:95-98` | `purchase_orders` + `delivery_notes` `.getList(1, 1, { filter: "is_verified=false" })` | 1 (count) | KPI tile — fine, only `totalItems` |
| `src/app/dashboard/purchasing/page.tsx:22-25` | `delivery_notes.getList(1, 200, { filter: "purchase_order='' && processing_status='needs-review'" })` | 200 | "Needs review" panel — site 201+ needs manual recovery from PB admin |
| `src/app/dashboard/plant/page.tsx:21, 26, 30` | `perPage: 5000` on vehicles/fuel_logs/sites | 5000 | Plant page renders are correct as long as the total is < 5000 items |
| `src/app/api/plant-hours/import/route.ts:216, 238` | `perPage: 5000` on vehicles + sites | 5000 | An import file that names a vehicle/site beyond 5000 fails the whole batch with a non-obvious "vehicle not found" error |
| `src/app/api/plant-hours/exception-report/[batchId]/route.ts:70` | `perPage: 5000` on `plant_hours_log` filter | 5000 | Exception report for a large batch is silently truncated |
| `src/app/api/purchase-orders/by-number/[poNumber]/items/route.ts:81` | `purchase_orders.getFullList({ perPage: 500 })` for Levenshtein fallback | 500 | Fuzzy PO match over a corpus > 500 POs misses legitimate matches |
| `src/app/api/purchase-orders/by-number/[poNumber]/items/route.ts:128` | `purchase_order_items.getFullList({ perPage: 200 })` | 200 | Detail page on a PO with > 200 line items drops items |
| `src/app/api/delivery-notes/[id]/ocr-result/route.ts:151` | `purchase_orders.getFullList({ perPage: 200 })` for normalised/Levenshtein PO match | 200 | OCR call where the matching PO is beyond row 200 fails to match |

**The history of this class of bug.** The comment at
`src/app/dashboard/purchasing/page.tsx:27-31` is direct evidence:

> "Use getFullList so there is no silent truncation if `received_items`
> ever exceeds 500 rows — earlier this used `getList(1, 500, ...)` which
> capped and produced 0% fulfillment whenever low-id POs were dropped."

This is the second time the team has hit "capped getList silently
truncated data" (the first was fulfilment, the second is the Overview
sites). It is the highest-leverage class of bug in the system.

**What the user sees.** The Overview page renders with a "Sites: 7" tile
even when there are 50+ sites. The "Attention required" rail and the
sites list at the bottom of the page both show 7-50 rows. Anything
beyond is invisible until the user navigates to `/dashboard/sites`,
which does call `getFullList`.

**Threshold.** At site 51, the Overview starts being wrong. Today this
is a one-line fix; left unrepaired, it will bite the moment a 51st
contract is added.

### 2. Load-everything-then-filter-in-memory — **CONFIRMED, with extra evidence**

**Lead claim:** "Most dashboard pages call `getFullList()` on entire
collections and filter in JavaScript."

**Evidence.** Every `app/dashboard/**/page.tsx` loads full collections
even when the page is a per-site view:

- `src/app/dashboard/page.tsx:75-82` — `fixed_costs.getFullList` (full) and `fuel_logs.getFullList` (full) for the Overview.
- `src/app/dashboard/sites/page.tsx:33-50` — seven parallel `getFullList` calls, no `filter` on any of them. The list page literally pulls every timesheet, every employee, every fuel log, every fixed cost, every PO, every income claim.
- `src/app/dashboard/sites/[id]/page.tsx:48-57` — the per-site detail page. Per the prompt: "filters *some* collections by `site='<id>'` server-side but pulls **all** timesheets and **all** employees regardless." Confirmed: lines 50-56 show `filter: site='${id}'` for `fixed_costs`, `purchase_orders`, `fuel_logs`, `vehicles`, `income_claims`, but `timesheets.getFullList()` (line 51) and `employees.getFullList({ fields: "id,rate_per_hour,site,name" })` (line 52) are unfiltered. Timesheet attribution is reconstructed in JS via `employeeRates.get(t.employee)?.site === id` (line 67).
- `src/app/dashboard/fuel/page.tsx:20-25` — vehicles (full, fleet bucket) + fuel logs (full, with `expand: "vehicle"`).
- `src/app/dashboard/employees/page.tsx:103-105` — employees (full) + timesheets (full) + sites (full).
- `src/app/dashboard/plant/page.tsx:19-32` — vehicles (full, `perPage: 5000`) + fuel logs (full, `perPage: 5000`) + sites (full, `perPage: 5000`).
- `src/app/dashboard/purchasing/page.tsx:14-33` — every PO (full) + every PO item (full) + every DN (full) + every site (full) + every received item (full, but projected to three fields).
- `src/lib/agent/load.ts:32-66, 72-92, 167-187, 205-216` — the agent tool layer pulls whole collections even when serving a per-site answer. `loadAllSitesBundle` (line 45) literally loads everything; `loadSiteBundle` (line 27) does the per-site filter for fixed_costs/POs/fuel/income but loads all timesheets + all employees.

**Cost growth.** With N sites × M months of data, the rows scale as:

| Collection | Approx rows/site/month | Cost at 10 sites × 12 months | Cost at 50 sites × 24 months |
| --- | --- | --- | --- |
| `timesheets` | 200-2000 (1-2 sites) | 240 000 | 2.4M |
| `fuel_logs` | 50-500 | 60 000 | 600 000 |
| `fixed_costs` | 5-20 | 2 400 | 12 000 |
| `purchase_orders` + items | 10-50 | 6 000 | 30 000 |
| `received_items` | 30-150 | 18 000 | 180 000 |
| `income_claims` | 1-4 | 480 | 2 400 |
| `employees` | 10-100 | 1 200 | 6 000 |
| `vehicles` | 5-30 | 600 | 3 000 |
| `sites` | 1 | 10 | 50 |

These are rough orders of magnitude. The **`timesheets` and `fuel_logs`
rows scale fastest**. The `/dashboard/sites` page, the chat's
`loadAllSitesBundle`, and the `/dashboard/employees` page all do a
**full** `getFullList` of `timesheets` on every render.

**Which page falls over first.** The **Sites** list page
(`src/app/dashboard/sites/page.tsx`) is the worst offender — it pulls
seven full collections in parallel and then runs a per-site
`computeSiteSpend` loop. With 50 sites and a year of timesheets, that
single page will pull 2.4M `timesheets` rows over the wire, build a
200 000-entry `employeeRates` map, and then loop `computeSiteSpend`
50 times over 2.4M timesheets — that's 120M `Map.get` calls in the
Node event loop, which won't return in under 30s. The first page
that's perceptibly slow is the **Sites** list, and it's followed
shortly by the **Site** detail page and the **Workforce** page.

**Threshold.** The Sites list page starts feeling slow at roughly
500 000 timesheet rows (≈ 10 sites × 12 months of heavy data). It
becomes unusable at 2M+.

### 3. No global site scope — **CONFIRMED**

**Lead claim:** "The sidebar has no site selector; each module handles
site filtering independently, mostly client-side."

**Evidence.**

- `src/components/layout/sidebar.tsx:35-43` — the seven nav entries have no site selector.
- `src/app/dashboard/page.tsx:191-193` — the Overview tile shows `data.sites[0]?.name ?? "No sites yet"` as the sub-label, which is a misleading and never-correct value when there are multiple sites.
- `src/app/dashboard/sites/page.tsx:117` — the Sites list page lets the user see all sites side by side (this is the only place "see all sites" exists).
- `src/app/dashboard/sites/[id]/page.tsx` — per-site drill-down, with a back button.
- `src/app/dashboard/fuel/page.tsx:159-165` — passes a `projectCodes: string[]` array to the client view for client-side filtering. Same in `fuel-view.tsx`.
- `src/app/dashboard/employees/page.tsx:159-162` — `projectCodes` and `positions` passed for client-side filter.
- `src/app/dashboard/plant/page.tsx:145` — `projectCodes` passed for client-side filter.
- `src/app/dashboard/purchasing/page.tsx:188` — `projectCodes: Array.from(new Set(rows.map((r) => r.projectCode))).sort()` passed for client-side filter.

**The cost to a user who works on one site.** There is no way to say
"my site is The Hills" once and have every page filter to it. Each
page requires the user to:
- Open the page.
- Find the project-code filter (a dropdown, varies per page).
- Pick their site.
- Wait for the client-side filter to apply.

**Pages that offer no site filter at all.** The Overview page
(`src/app/dashboard/page.tsx`) does not accept a site filter — the
KPI tiles are portfolio-wide. The **Site** detail page
(`src/app/dashboard/sites/[id]/page.tsx`) is already per-site by URL,
so the question is moot there. The other five pages do have the
client-side filter.

**Threshold.** This is a UX problem, not a correctness one — it
doesn't break the data, but at 5+ sites it costs the operator
non-trivial clicks. At 20+ sites it becomes a daily frustration.

### 4. Site resolution by name string — **CONFIRMED with caveats**

**Lead claim:** "Importers match incoming rows to sites by
case-insensitive `sites.name` comparison."

**Evidence.**

- `src/app/api/fuel-logs/import/route.ts:217-224` — `siteByName` keyed by `s.name.trim().toLowerCase()`.
- `src/app/api/plant-hours/import/route.ts:237-250` — same pattern in the orchestrator's `sites` Map.
- `src/lib/purchase-order-schema.ts` — `matchSite` is the canonical version (also used by the chat's free-text `requireSite` indirectly). It does exact `project_code`, then PB's `~` (case-insensitive substring) on `project_code`. Site-by-name is **not** used in PO ingest.
- `src/lib/agent/resolve.ts:21-48` — the chat-side `resolveSite` does id → project code → name → substring on name or code.

**Failure modes as site count grows.**

| Failure mode | What happens | Mitigated? |
| --- | --- | --- |
| Near-identical names ("The Hills" vs "The Hills Extension") | First hit wins; case-insensitive exact match. The importer's `Map.set` for `"the hills"` overwrites any earlier hit. **Last-written wins**, not first. | Partially — operator must rename sites to be unique or change the source row's label. |
| Renamed site | New `sites.name` value; old fuel log rows still carry the old `project_code` from the row. Re-imports of those rows would resolve to nothing or to the wrong site if a new site has the same name. | The 64-char ceiling and unique `project_code` index help, but they protect `project_code`, not `name`. |
| Whitespace / casing drift | Trimmed + lowercased before comparison. Tolerates `"The Hills"`, `"the hills"`, `"  The Hills  "`. | Yes. |
| Two sites sharing a name | Last-written wins in the importer's `Map`. The other site's rows resolve to whatever the most recent PB row with that name was. | No. |
| Source spreadsheet using a different label | Row is dropped, not orphaned — the importer's "no site" path leaves the `site` relation empty and falls back to `vehicle.projectCode` for the text. The fuel log exists but isn't tied to a site by relation. | The fallback is partial — the row survives but is ungroupable in JS-side filtering by `site` id. |

**Is `project_code` a more reliable key?** Yes — `project_code` has
the unique index and cannot be changed after creation
(`src/app/api/sites/[id]/route.ts:23-28`). The PO ingest already uses
`project_code` first. The fuel and plant importers still use `name`.

**What happens to a row that matches nothing.** Fuel: relation empty,
`project_code` falls back to `vehicle.projectCode`. Plant: similar (the
plant orchestrator requires the vehicle to resolve, so unmatched means
the row errored out). Timesheet auto-create: requires `siteId` to be
passed as a form field; no fallback.

**Threshold.** Silent wrong attribution starts at the **second site
with a near-identical name**. Today that means 5-10 sites. The
remediation is to make every importer resolve by `project_code` (or
fall back to name only when the project code is absent on the source
row) — and to surface "unmatched site" as a hard error, not a
silently-empty relation.

### 5. Vehicles, plant and employees moving between sites — **CONFIRMED, with the discipline gap highlighted**

**Lead claim:** "A vehicle or worker is bound to one `site` at a time.
Determine what happens to historical records when that assignment
changes."

**Evidence.**

- `src/lib/pb-types.ts:24-35` — `EmployeeRecord.site` is a single relation. `src/lib/pb-types.ts:39-56` — same for `VehicleRecord.site`.
- `src/lib/metrics/site-spend.ts:71-84` — payroll burn is computed by joining timesheets through `employeeRates` (`map.get(t.employee).site`). **Moving a worker to a new site silently reassigns all their past payroll burn to the new site** the next time a per-site report runs.
- `src/lib/agent/load.ts:32-33` — `loadSiteBundle` fetches fixed_costs/POs/fuel/income per-site, but timesheets globally. Same problem: per-site queries walk past timesheets via `employeeRates`.
- `src/lib/metrics/site-spend.ts:67-99` — the function-level contract: payroll goes to whatever `employee.site` is *at read time*. There is no snapshot on the timesheet.
- `src/lib/metrics/fuel-attention.ts:73-127` — fuel attention is computed from the vehicle's *current* `site` (via the `attentionVehicle.site` field at read time). Same drift.

**The `plant_hours_log.vehicle_unit_type_at_import` discipline.**
Confirmed: `scripts/pb-bootstrap-schema.py:251-252` and
`src/lib/pb-types.ts:209` show that `plant_hours_log` carries a
snapshot of the vehicle's `unit_type` at the moment of import. The
import code (`src/lib/plant-hours-import.ts`) is responsible for
writing it. This is exactly the right discipline — it means a
vehicle reclassified from "plant" to "fuel" six months ago still has
its old logs visible on the Plant page.

**That discipline is missing for `site`.** The `plant_hours_log.site`
field exists and is required, but it is set from `vehicle.site` at
import time. After a vehicle moves, the row keeps the *old* site
relation (good), but new imports for the same vehicle will write
*new* site values. So historical `plant_hours_log` rows do
**not** silently rewrite — they snapshot correctly.

The risk is in **`fuel_logs` and `timesheets`**:
- `fuel_logs` (`src/app/api/fuel-logs/import/route.ts:298-310`) — `site` and `project_code` come from the source row (the site column or the vehicle's project_code). If the source spreadsheet is updated, the row may be re-attributed. The row's `site` is also the one used in `groupAttentionBySite` (read time) — so a moved vehicle's old logs appear under the new site in the attention roll-up, because the join is `log.site` not `vehicle.site`. **Wait, re-checking: `src/lib/metrics/fuel-attention.ts:97-127` joins on `log.vehicle` and looks at the *vehicle's* current site (line 95 via `vehicleById.get(vehicleId)?.fuel_limits`). The attention roll-up groups by `log.site` in `groupAttentionBySite`. So a moved vehicle's old fuel logs DO drift to the new site in the rail — the row's `site` is what gets grouped, not the vehicle's current site. Confirmed in `src/lib/metrics/fuel-attention.ts:118-150` where `vehicleById` is used only for limits/description; the bucket is `log.site`.
- `timesheets` — confirmed above: payroll burn follows the employee's *current* `site` (`src/lib/metrics/site-spend.ts:73-74`).

**The composite `(vehicle_qr, start_date)` index.** Confirmed at
`scripts/pb-bootstrap-schema.py:257` and the route's duplicate-error
handling at `src/app/api/plant-hours/import/route.ts:95-114`. The
index has no `site` in the key, so a vehicle that legitimately moves
between sites (with a different `start_date` for each site) will
not collide. The risk the prompt flagged — a vehicle that goes
"Hills → Pitsana → Hills" within the same week — would collide on
the second Hills entry. Realistic: rare, but possible.

**What the user sees.**

- Workforce page: an employee who transferred from The Hills to
  Cosmo City last month has all their historical hours showing
  under Cosmo City now. Their 2025 P&L attributed to The Hills
  *no longer exists anywhere*. There is no per-timesheet
  `site_at_log_time` field to recover it from.
- Fuel attention: a vehicle moved from The Hills to West Park
  two months ago will have its flagged logs attributed to West
  Park in the current Overview rail. Old reports are wrong
  retroactively.

**Threshold.** The first move of an employee or vehicle between
sites. The team can mitigate by re-running historical reports
before any move and accepting that post-move history is lost.

### 6. Access control per site — **CONFIRMED, and the situation is bleak**

**Lead claim:** "With a single shared PIN and no user records, no user
can be restricted to their own site — everyone who knows the PIN sees
every site's contract values, margins and payroll."

**Evidence.**

- `src/hooks/use-auth.tsx:20` — `const expectedPin = process.env.NEXT_PUBLIC_APP_PIN || "2468";` — the PIN is a single shared string baked into the client bundle.
- `src/hooks/use-auth.tsx:23-34` — verification is a `sessionStorage` flag, set by the client, with no server check.
- `src/app/api/chat/route.ts:69-71` — the chat returns 404 if `ENABLE_CHAT` is unset, but has **no user authentication**. Anyone reaching the route can ask any question.
- `src/lib/pb.ts:74-111` — `pbAdmin()` is a module-singleton superuser. Every server component and route handler uses it.
- `scripts/pb-relax-rules.py:23-34` — the API rules allow any *authenticated* user to read every collection, but the server-side `pbAdmin()` bypasses these rules anyway.

**Is per-site access control achievable without introducing real user
accounts?** Not on the current server. The server-side data path
runs as superuser, so the only way to enforce "user X can only see
site Y" is to (a) introduce a real user model, (b) make every server
read filter by the requesting user's allowed sites, and (c) add a
PocketBase auth layer in front of `pbAdmin()`. That's the same work
as introducing real authentication.

A shortcut exists: a per-PIN site list (e.g. PIN A unlocks
`{Hills, Cosmo}`, PIN B unlocks `{Castle Gate}`). The PIN gate is
client-side today, but moving it server-side and issuing a server-set
session cookie that carries the site list is a ~half-day change.
That gets you a defence-in-depth "PITM and shoulder-surfing won't
leak financials" but **not** per-user audit trails or per-user
revocation.

**What the user sees.** Today: every operator sees every site's
contract values, margins, payroll rates. The chat — when enabled —
returns the same.

**Threshold.** The first time someone outside the company tries to
log in, or the first time a contractor is given the PIN and the
operator wants to limit them to one site.

### 7. The chat / agent layer — **CONFIRMED**

**Lead claim:** "Tools in `src/lib/agent/tools.ts` load portfolio-wide
bundles."

**Evidence.**

- `src/lib/agent/load.ts:45-66` — `loadAllSitesBundle` literally loads every site, every fixed cost, every timesheet, every employee (projected fields), every PO, every fuel log, every income claim. This is what `list_sites` and `site_financials` use as a starting point.
- `src/lib/agent/tools.ts:76-92` — `requireSite` resolves a free-text site query and returns ambiguity, but once it has a single site it uses `loadSiteBundle` (lines 27-42) which still pulls all timesheets + all employees globally.
- `src/lib/agent/tools.ts:125-150` — `list_sites` filters in JS over the global bundle (line 132-142). No server-side filter.
- `src/lib/chat/system-prompt.ts:17-29` — the system prompt's load-bearing rule: the model **never** does arithmetic. It must report values exactly as the tools return them.

**Cost and latency growth.** Every call to `list_sites` does 7
parallel `getFullList` calls plus a per-site JS loop. Latency is
dominated by the `timesheets` and `fuel_logs` fetches. At 10 sites ×
12 months this is ~2-3s; at 50 sites × 24 months it is ~30-60s,
which is well beyond interactive.

**Ambiguity handling.** `src/lib/agent/resolve.ts:21-48` returns
`{ kind: "ambiguous", matches: [...] }` when more than one site
matches. `requireSite` then formats that as an error string the model
relays verbatim. The prompt's concern ("whether the agent can leak
one site's financials to a user who should only see another's") is
**not** a code bug — the model doesn't switch tools based on user
intent, it switches based on the model's own choice. With the
current PIN-only auth, any operator can ask "what's The Hills' burn"
and get an answer; there's no enforcement of "you can only see
West Park." The risk is structural (no auth), not in the agent
code.

**Is the `ENABLE_CHAT` warning still accurate?** Yes, exactly. The
warning at `.env.local.example:46-50` says: "MUST stay unset in
production until real authentication exists — the chat reads every
site's financials and spends LLM credits for anyone who can reach
it." The code at `src/app/api/chat/route.ts:69-71` and
`src/app/dashboard/chat/page.tsx:31` is still gated only by this env
flag. There is **no** user authentication in front of either. The
warning is correct.

**Threshold.** When LLM cost-per-call exceeds the value of the
operator's time saved, or when the first unauthorised user reaches
the chat. Today the gate is honoured; the moment someone sets
`ENABLE_CHAT=true` in production without first adding real auth, the
warning is moot.

### 8. Anything else you find — **FOUND 7 additional things**

The prompt's open invitation. Capped at 5 as suggested, plus 2 bonus
items I think matter more than anything else here.

#### 8.1. `plant_hours_log` requires `site` to be set, but the **importer** doesn't enforce it — **TIER 1**

`scripts/pb-bootstrap-schema.py:235-236` declares
`field("site", "relation", required=True, ..., minSelect=1)`. The
importer at `src/lib/plant-hours-import.ts` is what calls
`pb.collection("plant_hours_log").create(prepRow.row)`. If the
vehicle's `site` is empty (a real condition for newly-added vehicles
with no site assignment yet), the insert fails with a 400 — but the
route surfaces the failure per-row and the operator is left with a
"duplicate" or "validation" error that doesn't make the cause clear.

**Why this matters.** A new vehicle added to PB without a `site` will
have its first plant hours import fail, and the operator may not
realise they need to assign the vehicle to a site first. The
dashboard-side `AddPlantButton` (`src/components/add-plant-button.tsx`)
*does* require `site` on create, so this is mostly a "data migration
or operator-directly-adds-to-PB" path.

#### 8.2. The `process-batch` test failure (404 vs 500) is a real bug, just masked by a bad mock — **TIER 2**

`src/app/api/purchase-orders/process-batch/route.test.ts:168` expects
404 when the batch doesn't exist; the production code at
`src/app/api/purchase-orders/process-batch/route.ts:137` checks
`(err as { status?: number }).status === 404`. The PB SDK does set
`status: 404` on missing-record errors, so production works. The
test mocks `getOne` to throw a plain `new Error("404 Not Found")`
with no `status` field, so the production code falls through to
the 500 branch.

**Why this matters.** When the test was written, the assumption
"the SDK error has `.status: 404`" was correct. If a future PB
version changes that, or if the route gets refactored to a
non-SDK error path, the test will silently start passing the
wrong response code. Worth either fixing the mock to set
`{ status: 404 }` or making the production code fall back to
matching `err.message` for a `404` substring.

#### 8.3. The `purchase_order_items.qty_outstanding` field is denormalised but the dashboard uses `received_items` directly — **TIER 3**

`src/lib/pb-types.ts:146` declares `qty_outstanding` on PO items,
and `src/lib/purchase-order-schema.ts` and the ingest route
(`src/app/api/purchase-orders/ingest/route.ts:135`) populate it
with the ordered qty at creation. The dashboard
(`src/app/dashboard/purchasing/page.tsx:54-67` and onward)
**does not use it** — it joins through `received_items` and
clamps to `min(received, ordered)`. The
`src/app/api/purchase-orders/by-number/[poNumber]/items/route.ts:127-128`
also uses `qty` + `qty_outstanding` only for display, not for
fulfilment.

**Why this matters.** `qty_outstanding` is a denormalised cache
that nobody reads. The OCR/DN update path *does not* decrement it.
It's a dead column. Either remove it (and the corresponding
fulfilment-by-denormalised fallback that doesn't exist) or wire
the `received_items` create path to decrement it under a
transaction. Today it's a tripwire for the next person who tries
to use it.

#### 8.4. `attention_dismissed_at` is a one-way switch with no UI to undo — **TIER 3**

`src/app/api/vehicles/[id]/attention-dismiss/route.ts` sets the
timestamp on dismiss. There's no `PATCH /api/vehicles/[id]/attention-undismiss`
or admin UI to clear it. A vehicle that re-flags after being
dismissed (because new fuel logs come in) will *not* reappear in
the "Attention required" rail because the filter is
`excludeAcknowledged: true` (`src/app/dashboard/page.tsx:131-133`).
The dismissal check uses `isAlertAcknowledged` which compares the
dismiss timestamp against the latest flagged log's date; see
`src/lib/attention-acknowledged.ts`. So a flag that arrives
*after* the dismissal will re-show. But a flag that *re-occurs*
on the same date as the dismissal will stay hidden.

**Why this matters.** UX glitch, not a data correctness issue.
Operators will hit it the first time a vehicle re-flags on the
same day they dismissed an old one.

#### 8.5. No server-side filter on `list_sites` / `list_purchase_orders` / etc. — **TIER 2**

The chat tool layer's `list_*` tools take no `siteId` argument
(and the schemas in `src/lib/agent/tools.ts` have no `siteId`).
`loadPurchaseOrders` (`src/lib/agent/load.ts:125-142`) does accept
a `siteId` arg, but the calling tool `list_purchase_orders`
doesn't surface it. So "what are the POs for The Hills" forces a
full-table load even though the per-site query would be a
two-character filter change. Same for `loadPlantHours`,
`loadFixedCosts`, `loadIncomeClaims`, `loadEmployees`, and
`loadImportBatches` — all accept `siteId`; none of the
corresponding `list_*` tools expose it.

**Why this matters.** A small change (add `siteId` to the tool
schemas, pass it through) would slash chat latency for
per-site questions at scale. Low cost, high payoff.

#### 8.6. (Bonus) `NEXT_PUBLIC_POCKETBASE_URL` is read by `pbAdmin()` server-side too — **TIER 3**

`src/lib/pb.ts:18` and `src/lib/pb.ts:28` both derive the PB URL
from `NEXT_PUBLIC_POCKETBASE_URL`. The `PB_BASE_URL` export on
line 27-28 is a re-export of the same thing. The server's
`pbAdmin()` uses this URL to reach PB. If the URL needs to be
different on the server vs. the client (e.g. an internal
`http://pb:8090` for the container, an external
`https://pb.example.com` for the browser), the current code can't
express that. A `POCKETBASE_INTERNAL_URL` (server-only) +
`POCKETBASE_FILE_URL` (server-only, for file proxies) would
unblock several deploy topologies that the current single-variable
design blocks.

#### 8.7. (Bonus) `ENABLE_CHAT` has no per-environment override — **TIER 3**

The flag is one env var read at request time
(`src/lib/chat/index.ts:13-15`). There's no way to say "chat is
on in staging, off in production, on for an internal demo behind
a feature flag" without redeploying. A `CHAT_ALLOWED_HOSTS` list
(env-driven hostname allowlist) would be a 10-line change that
makes the chat safely demoable on a per-deploy basis.

---

## Part C — What to change

Three tiers, in order of "do this first":

### Tier 1 — Correctness (must fix; produces wrong numbers today)

These are bugs that *silently* mis-attribute or *silently* drop data.
Not optional.

| # | Problem | Proposed change | Files | Effort | Risk of doing | Risk of not doing |
| --- | --- | --- | --- | --- | --- | --- |
| 1.1 | The Overview page caps sites at 50 | Replace `getList(1, 50)` with `getFullList({ sort: "name" })` on `src/app/dashboard/page.tsx:64`. The `sites.items` references that follow (lines 113, 157, 192) need to become `sites` (the array). | `src/app/dashboard/page.tsx` | **S** | Trivial — no shape change. | First site added beyond 50 silently vanishes from the KPI tile and attention rail. |
| 1.2 | The Overview's attention rail groups by `log.site`, which silently rewrites history when a vehicle moves | Either snapshot the site on the fuel log row (the `plant_hours_log` discipline) and add a `site_at_log_time` field with a one-time backfill, or document the drift as known. | `src/lib/metrics/fuel-attention.ts`, possibly a new column on `fuel_logs` + a migration | **L** (column add + backfill) | Backfill has to be done correctly or it double-counts. | Reports for any site that has had a vehicle moved to/from it are wrong retroactively. |
| 1.3 | The "needs review" panel on the purchasing page caps at 200 | Replace `getList(1, 200)` with `getFullList({ filter, sort: "-id" })`. The `items` field on the response needs to become the array directly (line 145-148 already checks for `.items`). | `src/app/dashboard/purchasing/page.tsx:22-25` | **S** | The 200th+ unverified DN stops being shown in the inbox. | The 201st DN needs manual PB admin recovery. |

**Other Tier 1 items I considered and rejected.** The "site resolution
by name" issue (4) is high-impact but Tier 2 because the operator can
fix it by renaming the conflicting sites — it's a workflow fix more
than a code fix. The `process-batch` 404/500 (8.2) is a test bug, not
a production bug — Tier 2. The `qty_outstanding` dead column (8.3)
is Tier 3 because nobody reads it today; if/when someone adds a
fulfilment-by-denormalised fallback, it'll become Tier 1.

### Tier 2 — Scale (do these before site count or data volume grows further)

These are the changes that turn "works at 7 sites" into "works at 50".
The most expensive ones are query patterns, not UI.

| # | Problem | Proposed change | Files | Effort | Risk of doing | Risk of not doing |
| --- | --- | --- | --- | --- | --- | --- |
| 2.1 | Every dashboard page does `getFullList()` on large collections and filters in JS | Add per-collection `filter: site='<id>'` server-side for the per-site pages, and add `date_logged >= '<cutoff>'` for the long-running ones. The plant-hours `perPage: 5000` calls become unbounded. | `src/app/dashboard/sites/[id]/page.tsx:48-57`, `src/app/dashboard/employees/page.tsx:103-105`, `src/app/dashboard/fuel/page.tsx:20-25`, `src/lib/agent/load.ts:32-66` | **M** | Easy to introduce a wrong filter that drops rows; needs good tests. | Sites list page becomes unusable at ~2M timesheet rows (today's level: ~50-100k, so ~1 year out at current ingest rate). |
| 2.2 | The agent's `list_*` tools don't accept `siteId` even though the loaders do | Surface `siteId` in the tool schemas for `list_purchase_orders`, `list_delivery_notes`, `list_employees`, `list_fixed_costs`, `list_income_claims`, `list_plant_hours`, `list_import_batches`. Pass through. | `src/lib/agent/tools.ts` (~7 tool defs) | **S** | Tool schemas change — any custom client using the MCP server has to handle the new field. | Every portfolio-wide chat question scans everything, even when the user only cares about one site. |
| 2.3 | PB indexes are missing on the columns that get filtered on | Add indexes on: `fuel_logs(site, date_logged)`, `fuel_logs(vehicle, date_logged)`, `fixed_costs(site, date_logged)`, `timesheets(employee, date_logged)`, `purchase_orders(site, required_by_date)`, `delivery_notes(site, date_received)`, `delivery_notes(processing_status)`, `income_claims(site, period_end)`, `plant_hours_log(vehicle, start_date)`. Re-run `pb-bootstrap-schema.py` + write a `migrate-2026-09-add-fleet-indexes.py` migration. | `scripts/pb-bootstrap-schema.py`, new migration file | **M** | Index adds are non-blocking on SQLite (PB default) but can be slow on large tables. Run during off-hours. | All per-site queries full-table-scan today. At 50 sites × 24 months of fuel logs, the fuel page would do a 600k-row scan on every render. |
| 2.4 | The plant page has `perPage: 5000` caps | Replace with `getFullList({ ... filter, sort })` — the implicit cap of 5000 is the next silent-truncation bug after sites/50. | `src/app/dashboard/plant/page.tsx:19-32` | **S** | None. | The 5001st plant item disappears. |
| 2.5 | The plant hours import has `perPage: 5000` caps on vehicle + site lookups | Replace with `getFullList({ fields: "..." })` (no perPage). | `src/app/api/plant-hours/import/route.ts:216, 238` | **S** | None. | An import file that names a vehicle beyond row 5000 fails the whole batch. |
| 2.6 | The `/api/purchase-orders/by-number/[poNumber]/items` Levenshtein fallback caps at 500 POs | Replace with `getFullList` (no perPage). | `src/app/api/purchase-orders/by-number/[poNumber]/items/route.ts:81` | **S** | The Levenshtein pass becomes O(N) over all POs — at 50 000 POs that's still < 1s in Node, fine. | A user looking up a recently-added PO gets a wrong/no match. |
| 2.7 | The OCR result webhook's normalised/Levenshtein PO match caps at 200 POs | Replace with `getFullList` (no perPage). | `src/app/api/delivery-notes/[id]/ocr-result/route.ts:151` | **S** | Same as 2.6. | A delivery note scanned against a PO beyond row 200 fails to match. |
| 2.8 | The process-batch test mock doesn't match the production error shape | Either change the mock to `{ status: 404 }` or add a `parseInt(err.message.match(/404/)?.[0] ?? "0")` fallback to the production code. | `src/app/api/purchase-orders/process-batch/route.test.ts`, `route.ts:137` | **S** | None. | If PB SDK ever stops setting `.status`, the route returns 500 instead of 404 and the test goes silently green. |

### Tier 3 — Product (do when the team has time, not blocking)

These are features, not bugs. The team should build them when there's
a clear user need, not prophylactically.

| # | Problem | Proposed change | Files | Effort | Risk of doing | Risk of not doing |
| --- | --- | --- | --- | --- | --- | --- |
| 3.1 | No global site selector in the sidebar | Add a `?site=<id>` query param (or a context) that every page reads at the top. Pages that take per-site filters can use it. Pages that are portfolio-wide (Overview) can show a "filter to my site" CTA. | `src/components/layout/sidebar.tsx`, plus the seven page bodies | **M** | Users with multiple sites lose the portfolio view by default — needs a "show all" toggle. | Daily frustration as site count grows. |
| 3.2 | Per-site access control with real users | Introduce a `users` collection on PB, replace the PIN gate with a server-validated auth check, attach the user's allowed site list to a session cookie, and have every server read filter by it. This is the same work as adding real authentication. | Many. `src/hooks/use-auth.tsx`, `src/components/auth-gate.tsx`, every server component, `src/lib/pb.ts` | **L** | A half-done auth layer is worse than no auth layer — it gives false confidence. | The current "everyone sees everything" model is fine for a single team but blocks working with external contractors. |
| 3.3 | A PIN-gated "site allowlist" shortcut | Move the PIN gate server-side, look up `PINS_TO_SITES` from env, and set a server-validated session cookie that carries the allowlist. Reads filter by it. Doesn't introduce users but does give the operator a way to limit what a contractor sees. | `src/middleware.ts` (new), `src/hooks/use-auth.tsx`, every page's `loadX` function | **M** | A misconfigured PIN allowlist is a security hole. | Same as 3.2 but at a smaller scope. |
| 3.4 | Site archiving for completed contracts | Add an `archived_at` field on `sites` (similar to `attention_dismissed_at`). Hide archived sites from the Sites list and Overview by default; add a "show archived" toggle. | `src/lib/pb-types.ts`, new migration, `src/app/dashboard/sites/page.tsx`, `src/app/dashboard/page.tsx` | **M** | Old links to archived sites need to keep working (server-rendered "site archived" page). | The list page becomes harder to scan as completed contracts accumulate. |
| 3.5 | Point-in-time site attribution for moved assets | Add `site_at_log_time` to `fuel_logs` and `timesheets`. Backfill from current `vehicle.site` / `employee.site` for existing rows. New writes set it from the source's site. `computeSiteSpend` and `groupAttentionBySite` use the snapshot field instead of the join. | Many. Schema, backfill migration, every metrics function that walks timesheets or fuel logs | **L** | Backfill correctness is everything; a botched backfill would re-rewrite history. | A moved employee's historical payroll burn is lost forever; a moved vehicle's old fuel flags drift to the new site. |
| 3.6 | Remove the dead `qty_outstanding` denormalisation, or wire it correctly | Either drop the column, or wrap the `received_items.create` flow in a PocketBase transaction that decrements `qty_outstanding`. | `src/lib/pb-types.ts`, `src/app/api/delivery-notes/[id]/ocr-result/route.ts`, the manual `/api/delivery-notes/[id]/assign-po` route | **S** (drop) or **M** (wire) | Dropping it is fine — nobody reads it. Wiring it requires care so the decrement survives PB's no-real-transactions model. | Future developer trusts the denormalised value, gets wrong numbers. |
| 3.7 | `NEXT_PUBLIC_POCKETBASE_URL` is one variable for both client and server | Add a separate `POCKETBASE_INTERNAL_URL` (server-only) and let `pbAdmin()` use that for in-cluster calls while the client uses the public URL. Add a `POCKETBASE_FILE_URL` for file proxies that need to be publicly resolvable. | `src/lib/pb.ts` | **S** | None. | The current single-variable design blocks several deploy topologies. |
| 3.8 | `ENABLE_CHAT` is binary | Add `CHAT_ALLOWED_HOSTS` (comma-separated hostnames) and `CHAT_ALLOWED_EMAILS` (PB users, if/when 3.2 is done). The chat route returns 404 unless the request's `Host` header is in the allowlist. | `src/app/api/chat/route.ts`, `src/lib/chat/index.ts` | **S** | None. | The chat is either fully on or fully off; no per-environment safe toggle. |
| 3.9 | Re-show dismissed vehicles when a new flag arrives | Extend `isAlertAcknowledged` (`src/lib/attention-acknowledged.ts`) to compare the dismiss timestamp against the *latest flagged log's* date. A new flag post-dismiss re-shows. | `src/lib/attention-acknowledged.ts`, `src/lib/attention-acknowledged.test.ts` | **S** | None. | UX glitch, not data correctness. |
| 3.10 | The Overview "Sites" tile shows `data.sites[0]?.name` as a sub-label | Remove the sub-label (it was never meaningful) or replace with "oldest: X" / "newest: Y" of the sorted list. | `src/app/dashboard/page.tsx:191-193` | **S** | None. | Confusing. |

---

## Bottom line — in plain English

**Can this app run many sites today? Yes, up to about 10.** The data
model is site-aware, the per-site math is right, the importers do the
right thing on the happy path, and the chat answers portfolio questions
correctly. **At 20+ sites, the Overview page starts hiding sites and
the Sites list page starts getting slow.** At 50+ sites, both are
unusable.

**The single most important thing to fix first is the 50-site cap on
the Overview page.** It's a one-line change
(`getList(1, 50)` → `getFullList({ sort: "name" })` on
`src/app/dashboard/page.tsx:64`), and without it, every other
multi-site improvement is invisible to the user — the Overview will
keep telling them they have 50 sites when they have 60. After that,
the next priority is moving the per-site pages to server-side `site=`
filters (Tier 2.1) so the Sites list page stops pulling the whole
world on every render. Together those two changes get the app to
"works correctly at 30-50 sites." Everything else in the assessment
matters, but is downstream of those two.