2026-09-12 07:35:35 +00:00
# Mega Plant Dashboard — Fix & Harden Brief
You built this app. It renders well and the visual design is approved. This brief
covers correctness, layout, and platform work. Work through it in order.
## Ground rules
**DO NOT restyle anything.** The palette, card roundness, gradients, spacing, dark
mode, and general look-and-feel are approved and must survive this work unchanged.
The Coolors palette (`#EDAE49` sunny, `#D1495B` brick, `#00798C` seaweed,
`#30638E` casual, `#003D5B` indigo) stays exactly as-is. If a fix requires a visual
change, make the smallest one possible and say so.
**Do not guess at business rules.** Two questions at the end of this brief are
unresolved. Do not pick an answer and move on — implement the code so the answer is
a one-line change, and report both questions back.
**Verify, don't assume.** After each part, run `npm run typecheck` and confirm the
page renders. Report what you actually ran and what it output.
## The stack
- Next.js 16 (App Router, server components), React 19, TypeScript 5.7
- Tailwind v4 via `@tailwindcss/postcss` , tokens declared in `app/globals.css` `@theme`
- PocketBase 0.27 at `NEXT_PUBLIC_PB_URL` , read server-side through `serverAuth()` in `lib/pb.ts`
- Recharts for charts, lucide-react for icons
- Dev server: `npm run dev` → port 6007
Collections: `assets` , `monthly_income` , `monthly_running_costs` , `overheads` .
---
# Part 0 — Rescue the extraction (do this first)
`scripts/seed.mjs` reads `/tmp/plant-excel-inspect/*.json` . `/tmp` is cleared on
reboot, and those files are the only record of how the source workbook became
PocketBase rows.
- [ ] Copy `/tmp/plant-excel-inspect/` to `./data/source/` in the repo (including
`original.xlsx` ).
- [ ] Repoint `scripts/seed.mjs` at `./data/source/` .
- [ ] Add a `scripts/extract.mjs` that regenerates those JSON files from
`original.xlsx` , so the pipeline is reproducible instead of a one-off.
If `/tmp/plant-excel-inspect/` is already gone, stop and report it — the workbook
must be re-supplied before anything else here can be verified.
---
# Part 1 — Data correctness
These are confirmed defects, each verified against both the seeded PocketBase data
and the source workbook's formulas. Fix all of them.
## 1.1 Profit disagrees with the client's spreadsheet on every row
The workbook computes Profit/Loss as **income − , excluding running cost.
Cell `J4` of sheet `Machine Fixed Monthly Cost VS I` is literally `=SUM(H4-I4)` .
`lib/rows.ts` (`buildIncomeRows`) computes `income - fixed_expenses - running_cost` .
For TLB01 January: the workbook says ** − ** −
Every row is wrong by exactly its running cost.
- [ ] Extract the profit rule into a single named function in `lib/profit.ts` , e.g.
`computeProfit({ income, fixed, running }, { includeRunningCost })` .
- [ ] Have every surface (dashboard KPIs, `IncomeView` , `RunningView` , `ChartsGrid` ,
`MachineLineChart` ) call that one function. No surface may compute profit inline.
- [ ] Default `includeRunningCost` to **false** so the app matches the client's
spreadsheet today, and leave a clear comment that this is Open Question 1.
- [ ] Add unit tests pinning TLB01 January to −
## 1.2 YTD figures mix 8 months of actuals with 4 months of forecast
Sep– `fixed_expenses` (the flat instalment
baseline). `lib/data.ts` `getMonthlyIncome()` filters on `year = 2026` only, and
`app/page.tsx` sums all 12 months.
Result: **R3,029,598** of forecast and idle-month fixed cost is subtracted from
8 months of real income. The KPI card labels income "Jan–
beside it silently spans twelve months.
- [ ] Add an `is_forecast` boolean (or a `status: actual | forecast` enum) to
`monthly_income` , and backfill it: a month is forecast when it is beyond the
last month with any recorded income.
- [ ] Make every YTD aggregation operate on actuals only, by default.
- [ ] Where forecast is shown, label it explicitly and render it visually distinct
(dashed line / lighter fill) — never silently summed with actuals.
- [ ] Fix the KPI cards so the income period and the profit period are the same
range, and state that range in the card.
## 1.3 R415,523.94 is double-counted
All 35 rows in the `overheads` collection with `section = "Plant Overheads"` are
the *same machines* that exist in `assets` — verified, all 35 match by name.
So the dashboard's "Overhead mix" donut counts machine instalments as overhead,
while those same instalments are already inside `monthly_income.fixed_expenses` .
- [ ] Remove the `Plant Overheads` section rows from `overheads` . The machines are
already in `assets` ; the instalment belongs to the asset, not to overheads.
- [ ] Keep the genuine overhead sections: `Vehicle Costs` , `Bastion Finance` ,
`Personnel` , `Subscriptions` , `Rent & Utilities` .
- [ ] Update `scripts/seed.mjs` so it never inserts machine rows into `overheads` .
- [ ] Re-check every total that reads `overheads` and confirm no machine appears twice.
## 1.4 Half the income data never made it into PocketBase
The source has **40** machine income blocks. Only **19** landed. `scripts/seed.mjs`
hits `if (!assetId) { continue; }` and silently skips the rest.
The 21 dropped: `CAT 425F (428E)` , both `CASE420 (430)` , `ELB 1TON RV` ,
`30KVA/10KVA/7,5KVA GENERATOR` , `TRAILOR PLANT` , `DIESEL TRAILOR` ,
`OFFICE CONTAINER` × `SITE CONTANER` × `Porta camp` × `Solar office` .
Root cause is code mismatch: the graph sheet carries `428E` / `430` where the asset
register carries `TLB02` / `SS01` / `SS02` , and the containers/generators have no
code at all. Also, of 52 `assets` rows, **24 have no code** .
- [ ] Build an explicit alias map (`428E → TLB02`, `430 → SS01` /`SS02`, etc.) resolved
against the asset register. Derive it from the workbook, do not invent codes.
- [ ] For uncoded items (containers, generators, camps), match on normalised name and
assign a stable synthetic code so repeat seeds are idempotent.
- [ ] **Make the seed fail loudly.** Replace every silent `continue` with collected
errors, and exit non-zero with a full report if any row cannot be matched. A
seed that drops half the data must never report success.
- [ ] After reseeding, assert 40 of 40 machines have income and report the count.
## 1.5 Running cost is stored twice
`monthly_income.running_cost` and `monthly_running_costs.amount` are seeded from the
same source column and will drift apart the moment either is edited.
- [ ] Pick `monthly_running_costs` as the single source of truth.
- [ ] Drop `running_cost` from `monthly_income` and derive it on read.
- [ ] Update `buildIncomeRows` and `buildRunningRows` in `lib/rows.ts` accordingly.
## 1.6 `site_rate` is a phantom field
In every seeded row `site_rate` is an exact copy of `monthly_incl` . It carries no
independent meaning.
- [ ] Remove it, or populate it with a real hire-out rate if one exists in the source.
Do not leave a field that looks meaningful and isn't.
---
# Part 2 — The header
The header in `app/layout.tsx` is the main complaint. It reads as a template, not a
product, because most of it doesn't do anything:
- The search input is **non-functional** — it filters nothing.
- The bell has a permanent red unread dot that never changes and opens nothing.
- The avatar is hardcoded `DL` / "David L." / "Plant Manager" — there is no auth.
- On mobile the `flex-1 max-w-md` search crushes the logo and overflows.
Fix by removing what's fake and keeping what's real:
- [ ] **Delete the bell.** There is no notification system.
- [ ] **Delete the hardcoded avatar and name.** There is no user identity. If you
want to keep the right-hand visual weight, put the fiscal-year pill there — it
is currently stranded at the bottom of the sidebar where nobody looks.
- [ ] **Either make search work or remove it.** Preferred: make it work, as a
client-side filter over assets by name / code / supplier, opening a results
dropdown that links to the relevant page. If that is out of scope, remove it
entirely rather than shipping dead UI.
- [ ] Keep the logo lockup exactly as-is — gradient mark, "Mega Plant", the
"Overheads 2026" sub-label. That part is good.
- [ ] Keep `ThemeToggle` .
- [ ] Keep the header's existing height, blur, border, and sticky behaviour.
The same rule applies elsewhere: `app/page.tsx` has a hardcoded "Recent activity"
list ("Seed complete", "just now") and non-functional `7d / 30d / 90d / YTD`
buttons. Either wire them to real data or remove them.
---
# Part 3 — Mobile
The app is desktop-only today. `components/Sidebar.tsx` is `w-64 shrink-0` with no
responsive handling, so on a phone it eats 256px of a 375px viewport and the content
overflows.
- [ ] Sidebar collapses below `lg` , opens as a drawer/sheet from a hamburger in the
header. Closes on navigation and on backdrop tap.
- [ ] Header reflows: logo + hamburger + theme toggle only on small screens.
- [ ] Every wide table (`IncomeView` grid, `RunningView` , `ExpenseSectionPage` ,
`app/plant/page.tsx` ) must scroll horizontally inside its own container without
breaking page layout. The sticky first column in `IncomeView` 's grid view must
keep working while scrolling.
- [ ] The 12-column month grid in the expanded `IncomeView` card needs a mobile
treatment — 12 columns at 375px is unreadable. Reflow to 3 or 4 columns.
- [ ] All tap targets ≥ 44×
- [ ] Recharts containers must be responsive, with no fixed pixel widths.
- [ ] Verify at 375× ×
at each — screenshots preferred.
---
# Part 4 — PWA install
There is no `public/` directory, no manifest, no icons, and no service worker.
`@ducanh2912/next-pwa` is not installed. This all needs building from scratch.
A working reference implementation exists in the sister app (Mega Infrastructure) —
mirror its structure.
- [ ] `npm i @ducanh2912/next-pwa`
- [ ] Wrap the config. ** `next-pwa` is Webpack-only**, so `next dev` and `next build`
must both pass `--webpack` . `package.json` already does this for `dev` ; add it
to `build` too.
```js
const withPWA = require("@ducanh2912/next-pwa").default({
dest: "public",
cacheOnFrontEndNav: true,
aggressiveFrontEndNavCaching: true,
reloadOnOnline: true,
register: true,
workboxOptions: { cleanupOutdatedCaches: true, clientsClaim: true, skipWaiting: true },
});
module.exports = withPWA(nextConfig);
```
- [ ] Create `public/manifest.json` by hand — ** `next-pwa` 's `manifest` option is
silently ignored in v10.2.9**, it does not generate one. Use
`theme_color: "#30638E"` and `background_color: "#f5f7fb"` to match the
approved palette, `display: "standalone"` , `start_url: "/"` .
- [ ] Generate icons at 192px, 512px, and a 512px maskable variant, using the
existing gradient `M` mark. Add a build script so they regenerate.
- [ ] Reference the manifest from `app/layout.tsx` via the `metadata` export.
- [ ] **iOS gotcha — this one costs hours if missed.** Next 16's `appleWebApp`
metadata API emits `apple-mobile-web-app-status-bar-style` but **not**
`apple-mobile-web-app-capable` . Without that tag, iOS Add-to-Home-Screen opens
in a Safari tab instead of standalone. Add it manually to the `<head>` in
`app/layout.tsx` :
```tsx
< meta name = "apple-mobile-web-app-capable" content = "yes" / >
```
- [ ] Add `apple-touch-icon` and a `viewport` export with `themeColor` .
- [ ] **PWA install requires the app itself to be served over HTTPS.** Confirm the
deployment target has TLS. Current PocketBase reads are server-side so plain
`http://` to PB works, but any browser-side PB call from an HTTPS page will be
blocked as mixed content — so PB should go behind TLS too.
- [ ] Verify install actually works on a real iPhone and a real Android device:
launches standalone, correct icon, correct splash, no browser chrome.
---
# Part 5 — Build hygiene and security
## 5.1 It does not compile
`npm run typecheck` fails with 8 errors:
```
app/charts/page.tsx(29,53) TS18047 's' is possibly 'null'
app/charts/page.tsx(31,22) TS18047 's' is possibly 'null'
app/charts/page.tsx(47,19) TS2322 totalIncome: number|null not assignable to number
components/IncomeView.tsx(195) TS2304 Cannot find name 'Row'
components/IncomeView.tsx(226) TS7006 'v'/'i' implicitly any
components/RunningView.tsx(172) TS2304 Cannot find name 'Row'
components/RunningView.tsx(204) TS7006 'v'/'i' implicitly any
```
- [ ] `Row` should be `IncomeRow` in `IncomeView.tsx` and `RunningRow` in
`RunningView.tsx` — both are already exported from `lib/rows.ts` .
- [ ] Fix the nullability in `charts/page.tsx` properly. Do **not** silence these with
`any` or `!` .
- [ ] `npm run typecheck` must exit clean.
## 5.2 Credentials are committed
`scripts/seed.mjs` hardcodes `plant@megainfra.co.za` / `1234567890` as fallback
defaults. `lib/pb.ts` and `next.config.ts` both hardcode the PocketBase URL.
- [ ] Remove all credential fallbacks. Read from env and **fail loudly** when absent.
- [ ] Add `.env.example` documenting `NEXT_PUBLIC_PB_URL` , `PB_ADMIN` , `PB_PASS` .
- [ ] Confirm `.env.local` is gitignored.
- [ ] **Rotate that PocketBase superuser password** — treat it as compromised.
- [ ] Drop the `env` block from `next.config.ts` ; it inlines the URL at build time so
it can't be changed per-environment. `NEXT_PUBLIC_` vars are picked up already.
## 5.3 Minor
- [ ] `lib/pb.ts` uses `pb.admins.authWithPassword()` , deprecated since PocketBase
0.23. Migrate to `pb.collection("_superusers").authWithPassword()` .
- [ ] There is no git repository. Run `git init` and commit before starting.
---
# Open questions — report back, do not guess
**Q1 — Does profit include running cost?**
The workbook says no (`J4 = SUM(H4-I4)`). The app currently says yes. They differ by
R1,897.50 on TLB01 January alone. Economically, running costs are real costs and
should arguably be included — but the client has been reading the other number all
year. This is their call. Implement per 1.1 so it flips with one flag.
**Q2 — What are the constants inside the fixed-expense formulas?**
Every fixed-expense cell is a hand-typed sum of three numbers:
```
TLB01 I4: = 16770.83 + 1300 + 5620.2 → 23691.03
TLB02 I5: = 23479.17 + 1300 + 10653.73 → 35432.90
TLB06 I9: = 29036.28 + 2401.81 + 5620.2 → 37058.29
SS01 I11: = 10062.50 + 1300 + 7315.95 → 18678.45
```
The first term is the monthly instalment. The second (`1300`, or `2401.81` /
`2797.63` for the Bastion-financed units) and the third (varies per machine and per
month) are **not labelled anywhere in the workbook** . Best guess is tracking and
operator wages, but that is inference.
These constants exist only inside formula text — they were never cells, so the seed
could not capture them. **Until Mega Plant confirms what they are, the cost model
cannot be rebuilt from inputs, only copied as outputs.** Ask them, then extract all
277 columns of constants into `cost_lines` rows so fixed expense becomes derived and
explainable rather than a stored magic number.
---
# Acceptance criteria
- [ ] `npm run typecheck` exits clean
- [ ] `npm run build` succeeds with `--webpack`
- [ ] 40 of 40 machines have income data in PocketBase; seed fails loudly on any unmatched row
- [ ] TLB01 January profit renders as −
- [ ] No machine instalment is counted in both `assets` and `overheads`
- [ ] YTD figures use actuals only; forecast months are labelled and visually distinct
- [ ] Header contains zero non-functional controls
- [ ] Usable at 375px wide — sidebar drawer works, no horizontal page overflow
- [ ] Installs standalone on iOS and Android, verified on real devices
- [ ] No credentials anywhere in source; PB password rotated
- [ ] **Palette, roundness, gradients, and dark mode visually unchanged**
2026-09-12 07:40:18 +00:00
---
# Open Questions — Report
These are still open as of the current commit. Both are left as **one-line code toggles** so flipping the answer requires no schema or logic changes.
## Q1 — Does profit include running cost?
- **Default in code:** `includeRunningCost: false` in `lib/profit.ts` .
- **Workbook says:** No — `=SUM(income - fixed)` only.
- **Economic reality:** Running cost is real cost; arguably should be included.
- **Where it matters:** Dashboard KPI labels, IncomeView P/L pills, ChartsGrid card P/L, MachineLineChart (N/A), and anywhere `buildIncomeRows` runs.
- **To flip:** Change the default in `lib/profit.ts` (one word: `true` /`false`) and every surface picks it up automatically. No other edits needed.
- **Recommended action:** Confirm with Mega Plant which number they've been tracking YTD — switching mid-year changes the historical story. Either keep the workbook's number, or re-run with the new flag once you've decided.
## Q2 — What are the constants inside the fixed-expense formulas?
- **Status:** Not implemented. No `cost_lines` table built. No extraction done.
- **Why:** The 277 columns of constants live only inside Excel formula text (e.g. `=16770.83 + 1300 + 5620.2` ). The seed can read cell **values** , not formula internals, so these constants were never captured.
- **What's needed:** Mega Plant to tell us what each constant represents. Best guess: the second addend is tracking (R1300 standard, R2401.81/R2797.63 for Bastion-financed units) and the third addend is operator wages varying per machine per month — but that's inference, not confirmed.
- **What to do when they reply:**
1. Decide on a `cost_lines` schema (e.g. `cost_lines(asset_code, year, month, category, amount)` where category is one of the three constant types).
2. Re-extract from the workbook using `cellFormula: true` in `XLSX.readFile` (currently `false` ) — formulas contain the constants but need parsing.
3. Rewrite the `fixed_expenses` column as a derived sum over `cost_lines` .
4. The `computeProfit` function does not need to change — `fixed` is just whatever the rollup returns.
## Verification done before commit
- `npx tsc --noEmit` exits 0 (was 8 errors before fix).
- `lib/profit.test.ts` passes 4/4, including the TLB01 Jan = -1,795.03 pin.
- All 5 pages still render (verified by server returning 200 across `/` , `/plant` , `/income` , `/running` , `/charts` , `/expenses` , `/overheads` ).
## What's NOT verified
- **Real iOS / Android PWA install.** I cannot drive a real device from here. Per Part 4.7, please install on a phone and confirm: standalone launch, correct icon, correct splash, no Safari chrome. Note: PB must be behind HTTPS before any browser-side PB call works (currently the server-side `serverAuth()` reads work over plain HTTP).
- **Mobile breakpoints.** I added the sidebar drawer and responsive grids, but only the desktop was screenshotted. Please check at 375× ×
