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

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:

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

Docker / Coolify: see COOLIFY.md and the Dockerfile.

MCP server (stdio, read-only):

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

---

Modules

The sidebar (src/components/layout/sidebar.tsx) has four top-level pages and three groups. Each is documented in docs/modules.md.

Path	Module	What it shows
/dashboard	Overview	KPI tiles, fuel-attention card grouped by site, 7-day rain outlook, every site
/dashboard/sites, /dashboard/sites/[id]	Sites	Per-site profitability, burn, P&L, payroll, weekly & monthly trends
/dashboard/workforce	Workforce	Landing: people cost this week
/dashboard/workforce/workers[/[employeeId]]	Workers	Every worker, hours, cost, printable QR badge
/dashboard/workforce/timesheets	Timesheets	Every entry from every source; spreadsheet import
/dashboard/workforce/on-site	On site now	Today's MEGA Clock attendance + Needs attention (missed scan-outs)
/dashboard/plant	Plant	Landing: fuel pumped, hours run, cost
/dashboard/plant/vehicles[/[vehicleId]]	Vehicles (L/km)	Fleet fuel efficiency, variance, dismissable attention
/dashboard/plant/equipment[/[vehicleId]]	Equipment (L/h)	Plant hour-meters, L/h, billable value
/dashboard/plant/fuel-logs	Fuel logs	Every fuel log across both buckets
/dashboard/plant/map	Map	Leaflet view of each vehicle's last scanned position
/dashboard/financial	Financial	Landing: open PO value, slips received, uploads waiting
/dashboard/financial/purchase-orders[/[poId]]	Purchase Orders	Every PO, fulfilment %, line editing, verify
/dashboard/financial/delivery-notes (+ /inbox, /work-queue, /document/[id])	Delivery Notes	Upload → OCR → match → post pipeline and its review queues
/dashboard/financial/suppliers[/[supplierId]]	Suppliers	Ordered / delivered / outstanding per supplier
/dashboard/chat	Ask	Read-only LLM chat with the same metrics the dashboard uses
/clock	MEGA Clock	Installable phone PWA: worker badge scan in/out + vehicle hour-meter scan

Old paths (/dashboard/employees, /dashboard/fuel[/id], /dashboard/purchasing[/id], /dashboard/plant/[id]) still work — they redirect to the pages above and keep ?site=.

---

Documentation

Document	What's in it
docs/architecture.md	Runtime topology, the two PB clients, rendering model, auth model, build/deploy
docs/data-model.md	Every PocketBase collection, fields, relations, the project_code denormalisation, indexes, API rules
docs/modules.md	One section per dashboard module — what it reads, computes, lets the user do
docs/data-flows.md	End-to-end ingestion pipelines with sequence diagrams (timesheets, fuel, plant, PO, DN)
docs/api-reference.md	Every API route — method, auth, request/response, error cases
docs/operations.md	Env vars, scripts, tests, feature flags, deploy / smoke test
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?
docs/clock-daily-exceptions-rollout.md	MEGA Clock new-day scans and the missed scan-out correction flow
docs/pwa-install-verification.md	Checking the dashboard / clock PWAs install correctly on iOS + Android
docs/n8n/	The n8n PO-ingest and DN-OCR workflows
docs/setup/env-and-mcp.md	Local env + MCP client setup

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/[sheetId], 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/purchase-orders/ingest, GET …/[id]/status, POST …/[id]/retry, GET …/[id]/document, GET …/[id]/pages/[n], POST …/[id]/items, PATCH / DELETE …/[id]/items/[itemId]	server-only / x-ingest-secret (ingest)	PO queue, source document, and manual line edits (blocked once verified)
POST /api/dn-batches/tick (cron), …/[id]/rerun, …/[id]/dismiss, …/[id]/assembly, GET …/[id]/pages/[n], …/pages/[n]/dismiss	x-ingest-secret (tick) / server-only	Staged delivery-note batches
PATCH /api/dn-batches/[id]/notes/[noteId], …/resolve-entities, …/resolve-item, …/post, …/dismiss, …/correct-receipt	server-only / RECEIPT_CORRECTION_SECRET (correct-receipt)	Correct, match, post, or stand down one candidate note
POST /api/suppliers, PATCH /api/suppliers/[id]	server-only	Supplier create / rename
POST /api/vehicles/import-summary	server-only	Sync the Buildsite Vehicle Fuel Summary CSV into vehicles
POST /api/vehicles/[id]/merge	server-only	Merge a duplicate vehicle into another (dry run unless confirm)
GET /api/pb-files/[collection]/[recordId]/[...filename]	server-only	Same-origin proxy for PocketBase files (PDF slips in iframes)
POST /api/chat	ENABLE_CHAT=true (no user auth)	SSE chat stream
GET /api/clock/employee-lookup, POST /api/clock/scan, POST /api/clock/vehicle-lookup, POST /api/clock/vehicle-scan	server-only	MEGA Clock PWA: badge clock-in/out + vehicle hour-meter scan
POST /api/clock/events/[id]/correct	same-origin + x-app-pin = APP_PIN	Record the real leaving time for a missed scan-out

Full reference: docs/api-reference.md.

---

Tests

npm run typecheck   # tsc --noEmit
npm run test:run    # vitest run
npm run lint        # eslint . — not yet clean, see docs/operations.md §4.1

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.