MEGAINFRA-WEBAPP/docs/minimax-multi-site-audit-prompt.md

# Prompt for MiniMax agent — Document the app + assess multi-site readiness

> Paste everything below the line into the MiniMax agent. It assumes the agent has
> read/write access to this repository.

---

## Role

You are a senior engineer joining the **MEGA INFRASTRUCTURE** codebase. Your job has two
parts, in this order:

1. **Write the missing technical documentation** for the app as it exists today.
2. **Deliver a multi-site readiness assessment**: can this app genuinely run many
   construction sites at once right now, and what specifically has to change for it to do
   so reliably at scale?

You are producing **documentation and analysis only**. Do **not** change application code,
schema, or config. The only files you create or modify are the deliverables listed at the
bottom.

---

## Ground rules

- **Evidence over assumption.** Every factual claim you make must cite a real
  `path/to/file.ts:line`. If you cannot find evidence for something, write "unverified" and
  say what you looked at.
- **The `README.md` at the repo root is stale and actively wrong.** It describes an earlier
  mock-data version. It references `src/lib/fuel.ts`, `src/lib/types.ts`,
  `src/app/api/mcp/`, `src/app/api/upload/`, and `/dashboard/orders` — **none of these
  exist**. Do not use it as a source. Treat the source code as the only truth.
- **Read `AGENTS.md` first.** This is a modified build of Next.js 16; conventions may differ
  from what you expect. Authoritative docs live in `node_modules/next/dist/docs/`. Read the
  relevant guide there before making any claim about Next.js behaviour (caching, dynamic
  rendering, route handlers, server components).
- **Do not invent severity.** Distinguish clearly between: (a) a bug that breaks correctness
  today, (b) a limit that will break at a known threshold, (c) a design choice that is fine
  now but will cost more to change later.
- Verify claims by reading code. Where useful, run `npm run typecheck` and `npm run test:run`
  to confirm the suite's current state, and report the actual output.

---

## What the app is

A Next.js 16 (App Router, React 19, Tailwind v4) operations dashboard for a South African
civil construction company, backed by **PocketBase**. It tracks, per construction site:
sites/contracts, employees & timesheets, vehicles (fuel and plant units), fuel logs, plant
hour meters, fixed costs, income claims, purchase orders + line items, and delivery notes
with OCR-driven receipting. There is also an LLM chat ("Ask") surface with a read-only tool
layer over the same data, and an MCP server.

Key entry points to orient yourself:

| Area | Path |
| --- | --- |
| PocketBase clients (`pb` browser, `pbAdmin` superuser) | `src/lib/pb.ts` |
| Full collection type definitions | `src/lib/pb-types.ts` |
| Dashboard pages (server components) | `src/app/dashboard/**/page.tsx` |
| Route handlers | `src/app/api/**/route.ts` |
| Pure metric/calculation functions | `src/lib/metrics/` |
| Import parsers (timesheets, fuel, plant hours, POs) | `src/lib/*-parse.ts`, `src/lib/*-import.ts` |
| Chat/agent tool layer | `src/lib/agent/`, `src/lib/chat/` |
| Auth (PIN gate) | `src/hooks/use-auth.tsx`, `src/components/auth-gate.tsx` |
| Schema bootstrap / rules scripts | `scripts/pb-bootstrap-schema.py`, `scripts/pb-relax-rules.py` |
| Existing design/plan docs | `docs/superpowers/specs/`, `docs/superpowers/plans/` |

---

## Part 1 — Documentation to write

Write these as Markdown into `docs/`. Aim for documents a new engineer could use to become
productive without reading every file, and that a non-technical owner could use to
understand what the system does.

### 1. `docs/architecture.md`

- Runtime topology: Next.js app → PocketBase → n8n webhooks (PO ingest, delivery-note OCR)
  → LLM providers. Draw it as a Mermaid diagram.
- Rendering model: which pages are server components, what `export const dynamic` settings
  are in use, where data fetching happens, and what is client-side.
- The two PocketBase clients and **when each is used**. Be explicit about the fact that
  server routes and pages authenticate as the PocketBase **superuser** via `pbAdmin()`
  (`src/lib/pb.ts`) and what that implies.
- Auth model as it actually is today: a shared numeric PIN from `NEXT_PUBLIC_APP_PIN`
  (default `2468`), held in `sessionStorage`, with a `?demo=1` query-string bypass
  (`src/hooks/use-auth.tsx`). State plainly that there is **no per-user identity** in the
  application.
- Build/deploy: `Dockerfile`, `docker-compose.yml`, `COOLIFY.md`, the `--webpack` requirement
  for the PWA plugin, and the icon/OG-image prebuild scripts.

### 2. `docs/data-model.md`

- Every PocketBase collection from `src/lib/pb-types.ts`: fields, types, relations, and
  which are optional/legacy.
- An entity-relationship Mermaid diagram.
- For **each** collection, state explicitly whether it carries a `site` relation, a
  `project_code` string, both, or neither. Flag the ones that carry neither and explain how
  those records are attributed to a site (if at all).
- Document the `project_code` denormalisation: it is copied onto child records rather than
  read through the `site` relation. Describe the drift risk and where it is written.
- Document known unique indexes and constraints you can find (e.g. the composite unique index
  on `plant_hours_log` referenced in `src/app/api/plant-hours/import/route.ts`), and what
  happens on collision.
- Document PocketBase API rules as configured by `scripts/pb-relax-rules.py`
  (list/view/create = any authenticated user; update/delete = superuser only) and what that
  means for who can read what.

### 3. `docs/modules.md`

One section per dashboard module (Overview, Sites, Workforce, Plant & Equipment, Fleet &
Fuel, Purchasing, Ask). For each: purpose, route, which collections it reads, which metric
functions it uses, what the user can do there, and which API routes it calls.

### 4. `docs/data-flows.md`

Trace each ingestion pipeline end to end, with a sequence diagram:

- Timesheet import (`/api/timesheets/import`) — including the auto-create-employees path.
- Fuel log import (`/api/fuel-logs/import`).
- Plant hours import (`/api/plant-hours/import`) + exception report.
- Purchase order upload → n8n → `/api/purchase-orders/ingest` → `process-batch`.
- Delivery note upload → OCR → `/api/delivery-notes/[id]/ocr-result` → received items.

For each pipeline, answer precisely: **how is the target site determined for each imported
row?** Name the exact matching strategy and the failure behaviour when no match is found.

### 5. `docs/api-reference.md`

Every route under `src/app/api/`: method, path, auth/secret requirements, request shape,
response shape, error cases. Note which are protected by `N8N_INGEST_SECRET` and which have
no protection at all.

### 6. `docs/operations.md`

Environment variables (from `.env.local.example`), what each does, which are
client-exposed (`NEXT_PUBLIC_`), the scripts in `scripts/`, how to run tests, and the
existing feature flags (e.g. `ENABLE_CHAT`).

---

## Part 2 — Multi-site readiness assessment

Write this as `docs/multi-site-assessment.md`. This is the deliverable that matters most.

### The question to answer

**Multiple construction sites** — 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?**

Structure your answer in three parts.

### Part A — What works today

The data model is already site-aware. Verify and document this properly: which collections
carry a `site` relation, which UI surfaces group or filter by site, how per-site financials
are computed (`src/lib/metrics/site-spend.ts`, `site-projection.ts`,
`income-vs-expenses.ts`), and how the chat tool layer resolves a site from free text
(`src/lib/agent/resolve.ts`). Give a plain verdict: **at what scale does the app work
correctly as-is?**

### Part B — Where it breaks

Investigate each of the following. **These are leads I have partially verified — confirm or
refute each one yourself with file:line evidence, correct me where I am wrong, and add
anything I missed.** Do not simply restate this list; test each claim.

1. **Hard 50-site cap on the Overview page.**
   `src/app/dashboard/page.tsx:64` calls
   `pb.collection("sites").getList<SiteRecord>(1, 50, { sort: "name" })`. Determine what
   happens to site 51+ — does it silently vanish from KPI tiles and the "Attention required"
   rail? Search the whole codebase for other capped `getList(page, perPage)` calls and list
   every one with its cap and its blast radius. There is a related comment at
   `src/app/dashboard/purchasing/page.tsx:29` about a previous cap that silently truncated
   data — treat that as evidence this class of bug has already bitten once.

2. **Load-everything-then-filter-in-memory.** Most dashboard pages call `getFullList()` on
   entire collections and filter in JavaScript — e.g.
   `src/app/dashboard/page.tsx`, `src/app/dashboard/sites/page.tsx`,
   `src/app/dashboard/purchasing/page.tsx`, `src/app/dashboard/fuel/page.tsx`,
   `src/app/dashboard/employees/page.tsx`. Note especially
   `src/app/dashboard/sites/[id]/page.tsx:50-56`, which filters *some* collections by
   `site='<id>'` server-side but pulls **all** timesheets and **all** employees regardless.
   Quantify: with N sites × M months of fuel logs, timesheets, POs and received items, how
   does page cost grow? Estimate the row counts at which pages become slow, and identify
   which single page falls over first.

3. **No global site scope.** The sidebar (`src/components/layout/sidebar.tsx`) has no site
   selector; each module handles site filtering independently, mostly client-side. Assess
   what this costs a user who works on one site: how many clicks/filters to see just their
   data, and which modules offer no site filter at all.

4. **Site resolution by name string.** Importers match incoming rows to sites by
   case-insensitive `sites.name` comparison (see `src/app/api/fuel-logs/import/route.ts`
   around lines 214-224 and `src/app/api/plant-hours/import/route.ts` around lines 237-245),
   and PO matching goes through `src/lib/purchase-order-schema.ts`. Evaluate the failure
   modes as site count grows: near-identical names, renamed sites, whitespace/casing drift,
   two sites sharing a name, source spreadsheets using a different label than PocketBase.
   What happens to a row that matches nothing — is it dropped, orphaned, or rejected? Is
   `project_code` a more reliable key, and is it consistently present?

5. **Vehicles, plant and employees moving between sites.** A vehicle or worker is bound to
   one `site` at a time. Determine what happens to historical records when that assignment
   changes: do past fuel logs and timesheets stay attributed to the old site, or do they
   follow the current assignment and silently rewrite history? Check whether logs snapshot
   the site at import time or read it through the relation. Note that
   `plant_hours_log` stores `vehicle_unit_type_at_import`, which suggests the codebase
   already understands point-in-time snapshotting — does the same discipline apply to `site`?
   Also check the `(vehicle_qr, start_date)` unique index for cross-site collisions.

6. **Access control per site.** 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. Confirm this, and confirm that server-side data access runs
   as PocketBase superuser (`pbAdmin()`), meaning collection-level API rules do not constrain
   it. State whether per-site access control is achievable without introducing real user
   accounts.

7. **The chat/agent layer.** Tools in `src/lib/agent/tools.ts` load portfolio-wide bundles
   (`list_sites` and friends). Assess: cost and latency growth as sites multiply, whether
   ambiguous site names are handled safely (`src/lib/agent/resolve.ts`), and whether the
   agent can leak one site's financials to a user who should only see another's. Note that
   `.env.local.example` already warns `ENABLE_CHAT` must stay off in production until real
   authentication exists — verify whether that warning is still accurate.

8. **Anything else you find.** Cross-site data leakage, missing indexes, N+1 queries, unbounded
   `getFullList()` calls in route handlers, aggregates that double-count when a record has a
   stale `project_code`, and the `$autoCancel: false` workarounds in `src/lib/pb.ts` and the
   dashboard pages — do those indicate a concurrency problem that worsens with more sites?

For every finding, give: **what breaks, at what threshold, what the user sees when it breaks,
and the file:line evidence.**

### Part C — What to change

A prioritised remediation plan. For each item: the problem, the proposed change, the files
affected, rough effort (S/M/L), the risk of doing it, and the risk of *not* doing it. Group
into:

- **Tier 1 — Correctness.** Things that silently produce wrong numbers or hide data today.
  These are not optional.
- **Tier 2 — Scale.** Query patterns, pagination, indexes, and server-side filtering needed
  before the site count or data volume grows further. Say explicitly what the app should do
  instead of `getFullList()` and where PocketBase filters/indexes belong.
- **Tier 3 — Product.** A global site scope/selector, per-site access control (and the user
  model it requires), site archiving for completed contracts, and point-in-time site
  attribution for moved assets.

End with a one-paragraph **bottom line** in plain English, written for the business owner,
not an engineer: can this app run many sites today, how many, and what is the single most
important thing to fix first.

---

## Deliverables

Create exactly these files:

```
docs/architecture.md
docs/data-model.md
docs/modules.md
docs/data-flows.md
docs/api-reference.md
docs/operations.md
docs/multi-site-assessment.md
```

Then **replace the stale root `README.md`** with an accurate short overview that links to the
documents above. Keep it under 100 lines; the detail belongs in `docs/`.

Do not modify any file under `src/`, `scripts/`, or any config file.

Finish with a short summary in chat covering: your multi-site verdict, the top three things
that must be fixed, and any claim in this prompt that turned out to be wrong.