MEGAINFRA-WEBAPP/README.md

# MEGA INFRASTRUCTURE — Operations Dashboard

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

> **Default login PIN is `2468`.** Change `NEXT_PUBLIC_APP_PIN` in
> production. Append `?demo=1` to any URL to bypass the PIN during
> development.

---

## Quick start

```bash
cp .env.local.example .env.local
# edit NEXT_PUBLIC_POCKETBASE_URL, POCKETBASE_ADMIN_*, N8N_*
npm install
npm run dev    # next dev -H 0.0.0.0 -p 6004 --webpack
```

Production build / start:

```bash
npm run build   # icons + og-image + next build --webpack
npm run start   # next start -H 0.0.0.0 -p 3000
```

Docker / Coolify: see [`docs/COOLIFY.md`](./docs/COOLIFY.md) and the
[`Dockerfile`](./Dockerfile).

MCP server (stdio, read-only):

```bash
npm run mcp     # uses the PocketBase creds in .env.local
```

---

## Modules

The sidebar lists seven modules. Each is documented in
[`docs/modules.md`](./docs/modules.md).

| Path | Module | What it shows |
| --- | --- | --- |
| `/dashboard` | Overview | KPI tiles, fuel-attention rail grouped by site, every site summary |
| `/dashboard/sites` and `/dashboard/sites/[id]` | Sites | Per-site profitability, burn, P&L, payroll, weekly & monthly trends |
| `/dashboard/employees` | Workforce | Per-employee hours, rates, weekly trend, casual-matrix import |
| `/dashboard/plant` and `/dashboard/plant/[vehicleId]` | Plant & Equipment | Hour-meter history, weekly logs, billable rate |
| `/dashboard/fuel` and `/dashboard/fuel/[vehicleId]` | Fleet & Fuel | Variance per log, over-limit flags, dismissable attention |
| `/dashboard/purchasing` and `/dashboard/purchasing/[poId]` | Purchasing | Every PO, DN fulfilment %, OCR exception inbox |
| `/dashboard/chat` | Ask | Read-only LLM chat with the same metrics the dashboard uses |

---

## Documentation

| Document | What's in it |
| --- | --- |
| [`docs/architecture.md`](./docs/architecture.md) | Runtime topology, the two PB clients, rendering model, auth model, build/deploy |
| [`docs/data-model.md`](./docs/data-model.md) | Every PocketBase collection, fields, relations, the `project_code` denormalisation, indexes, API rules |
| [`docs/modules.md`](./docs/modules.md) | One section per dashboard module — what it reads, computes, lets the user do |
| [`docs/data-flows.md`](./docs/data-flows.md) | End-to-end ingestion pipelines with sequence diagrams (timesheets, fuel, plant, PO, DN) |
| [`docs/api-reference.md`](./docs/api-reference.md) | Every API route — method, auth, request/response, error cases |
| [`docs/operations.md`](./docs/operations.md) | Env vars, scripts, tests, feature flags, deploy / smoke test |
| [`docs/multi-site-assessment.md`](./docs/multi-site-assessment.md) | **The main deliverable** — will this app hold up at 50 sites? Where does it break, and what to fix in what order? |

The `docs/superpowers/` directory has older design notes; treat as
historical, not authoritative.

---

## Tech stack

- **Next.js 16** (App Router, modified build — see `AGENTS.md`)
- **React 19** + **TypeScript 5.7**
- **Tailwind v4** (via `@tailwindcss/postcss`)
- **PocketBase 0.27** (PocketBase v0.22+ schema shape, see
  `scripts/pb-bootstrap-schema.py`)
- **SheetJS** (xlsx) + **PapaParse** (csv) for imports
- **Recharts** for charts
- **Vitest** for tests
- **`@ducanh2912/next-pwa`** (Webpack-only — `next dev`/`build` pass
  `--webpack` to support it)
- **Anthropic** or **MiniMax** as the chat LLM provider

---

## API surface (summary)

| Route group | Auth | Notes |
| --- | --- | --- |
| `GET /api/health` | none | Docker healthcheck |
| `POST /api/sites`, `PATCH /api/sites/[id]`, `POST /api/sites/[id]/fixed-costs` | server-only | Sites CRUD |
| `POST / PATCH / DELETE /api/vehicles[ /[id]]` | server-only | Vehicles CRUD (unified fuel + plant) |
| `POST /api/plant-hours/import`, `GET /api/plant-hours/template`, `GET /api/plant-hours/exception-report/[batchId]`, `DELETE /api/plant-hours/[id]` | server-only | Plant hours ingest + reporting |
| `POST /api/timesheets/import` | server-only | Timesheet ingest (three formats auto-detected) |
| `POST /api/fuel-logs/import` | server-only | Fuel log ingest |
| `POST /api/purchase-orders/upload`, `POST /api/purchase-orders/process-batch` (n8n), `GET /api/purchase-orders/by-number/[poNumber]/items`, `PATCH /api/purchase-orders/[id]/supplier` | server-only / `x-ingest-secret` | PO ingest pipeline |
| `POST /api/delivery-notes/upload`, `GET /api/delivery-notes/[id]/slip` (n8n), `POST /api/delivery-notes/[id]/ocr-result` (n8n), `POST /api/delivery-notes/[id]/assign-po` | server-only / `x-ingest-secret` | DN pipeline + manual fallback |
| `GET / POST /api/data-import-batches/[id]/status\|retry` | server-only | Batch lifecycle |
| `POST /api/records/[collection]/[id]/verify` | server-only | Verify toggle for POs and DNs |
| `POST /api/chat` | `ENABLE_CHAT=true` (no user auth) | SSE chat stream |

Full reference: [`docs/api-reference.md`](./docs/api-reference.md).

---

## Tests

```bash
npm run typecheck   # tsc --noEmit
npm run test:run    # vitest run
```

The metric helpers under `src/lib/metrics/*.test.ts` pin every
computation the dashboard exposes. Run after any change to the
financial roll-up.

---

## License

Proprietary. Internal use only.