# Nowills SQC ERP — Stone Quarry & Construction ERP

Enterprise ERP for quarry, crushing, haulage, ready-mix/construction operations in Ghana.
**Stack:** PHP Laravel + MySQL only. No Node, no Docker, no build step — plain Blade + vanilla JS/CSS.

## Quick start

```bash
cp .env.example .env          # set DB_DATABASE/DB_USERNAME/DB_PASSWORD (MySQL)
php artisan key:generate
php artisan migrate:fresh --seed
php artisan serve              # http://127.0.0.1:8000
```

**Default login:** `admin` / `Admin#2026` (all demo users share the documented passwords in `database/seeders/RbacSeeder.php`).

Seed chain: `RbacSeeder → CoreSeeder (CoA, banks, tax, settings) → MasterSeeder (parties, fleet, HR, projects) → DemoSeeder (6 months of live transactions)`. Runs in ~12 s.

## Modules

| Area | Highlights |
|---|---|
| Quarry & crushing | Production entries (draft→approve→stockpile), crusher lines, downtime log, stockpiles |
| Weighbridge | Ticket open (1st weight) → close (2nd weight, auto net), dispatch linkage |
| Inventory & stores | GRN post with landing cost, issues/returns, adjustments, explosives register with officer sign-off |
| Plant & fleet | Equipment register, maintenance work orders (parts + labour), fuel log, trip register, document expiry |
| Sales | Quotation → sales order → delivery note → invoice (NHIL/GETFund/COVID/VAT) → receipt → credit note |
| Procurement | Requisition → approval → LPO → GRN → bill (3 % WHT) → supplier payment |
| Projects & IPC | BOQ, subcontractor claims, client IPCs (retention, advance recovery) → invoice |
| Finance | Double-entry journals (draft→post→reverse), bank book + reconciliation, budgets, expense claims with multi-level approvals |
| Payroll (Ghana) | SSNIT 5.5 %/13.5 %, graduated PAYE bands, allowances/deductions/loans, payslips, bank schedule |
| HR | Employees, attendance, leave (approval workflow), advances, appraisals |
| Compliance | Permits (Minerals Commission/EPA), HSE incidents, explosives magazine log |
| Reports | 43 reports (production, sales, AR/AP aging, stock, fleet, projects, TB/P&L/BS/GL, VAT, WHT…) + CSV export + print |

78 registry entities under `/app/{key}` plus dedicated document controllers, role-based permissions, approval inbox, company/preference settings, and an executive dashboard.

## Ghana tax configuration

All rates live in **Settings → Preferences** (no code change needed): NHIL 2.5 %, GETFund 2.5 %, COVID levy 1 %, VAT 15 % (on levied base), WHT 3 %, SSNIT/PAYE bands. GhanaTaxService is the single source of truth.

## Verification status (2026-09-07)

Live smoke test against seeded MySQL database — all green:

- 78/78 CRUD index pages `200`
- 86/86 document pages (indexes, creates, shows, prints) `200`
- 43/43 reports `200` + CSV export verified
- 12 end-to-end POST workflows verified (production approve → pile +150 t; journal post; leave approve; approval inbox decide; weighbridge open→close net 20 t; quote→order→invoice→receipt; PR→PO→GRN→bill→pay-to-zero; expense pay; full payroll compute→approve→pay; role/user create; bank reconcile; WO complete)
- Ledger integrity: 48 posted journals, **0 unbalanced**, Dr = Cr = GH₵2,431,567.09; AR/GL1100, AP/GL2000, bank book/GL all tie; zero negative stockpiles/items

## Command Centre (new UI shell)

The attached `index.html` command-centre prototype is now the live application shell at `/command`
(login lands here; the previous dashboard remains at `/dashboard`).

- `public/cc/` — the prototype split verbatim into `css/command.css` + 12 JS files
  (`chartkit.js`, `edata*.js`, `modules*.js`, `mounts*.js`, `app.js`), plus `js/bridge.js`
- `app.js` carries 7 minimal patches only: server identity, server scope lists,
  `NWX.remount()` hook, role-switch guard, real logout
- `bridge.js` overrides demo `MODULES.*` with API-fed versions module-by-module;
  unwired modules render the prototype dataset behind a "SAMPLE" ribbon, live ones get "● LIVE"
- `app/Http/Controllers/CommandController.php` — shell + `__SERVER` payload
  (user, role, permission-filtered module allow-list, real quarries/projects scope lists)
- `app/Http/Controllers/Api/V1/DashboardController.php` — live endpoints

**Live modules (31/31):**
- Executive Dashboard — 12 period-aware KPIs, 7 charts, projects portfolio,
  pending approvals, live exceptions (all from the posted ledger)
- Quarry Operations — 12 KPIs (today/MTD production, ROM, blasting, hours, fuel...),
  5 charts (per-quarry trend, product mix, op-vs-downtime, piles, downtime reasons),
  3 live tables (entries, blasts, benches) with record drill-down
- Drilling & Blasting — 12 KPIs (blasts, tonnage/volume broken, holes, depth,
  explosives issued/received/stock, powder factor...), 4 charts (tonnage trend,
  powder factor per blast, usage by type, magazine stock), 2 live tables
  (blast register, explosives magazine register) with record drill-down
- Crushing & Processing — 12 KPIs (output, throughput, rated capacity, utilization,
  availability, hours, fuel...), 5 charts (per-line trend, tph, availability by line,
  product mix, downtime reasons), 2 live tables (line scorecard with per-line
  utilization, crusher production log) with record drill-down
- Weighbridge — 12 KPIs (tickets/net today & period, gross/tare, avg net,
  trucks served, turnaround, open trucks...), 5 charts (net trend, turnaround
  trend, product mix, top transporters, weigh-ins by hour), 2 live tables
  (weighbridge register, open trucks on site) with record drill-down
- Stockpile Management — 12 KPIs (live on-hand, capacity, fill, in/out, net
  change, days of cover, low/full pile alerts...), 4 charts (in-vs-out flows,
  on-hand level, fill by pile, stock by product), 2 live tables (pile balances,
  movement ledger) with record drill-down
- Aggregate Sales — 12 KPIs (orders, order/dispatch/invoice value, tonnage,
  collections, collection rate, receivables, overdue...), 4 charts (orders vs
  dispatch vs cash, tonnage, mix by product, top customers), 5 live tables
  (orders, delivery notes, invoices, receipts, credit notes) with drill-down
- Equipment & Plant — 12 KPIs (fleet strength, availability, fleet value, fuel
  use/cost, open WOs, maintenance cost, breakdown hours, doc expiries...),
  4 charts (fuel trend, maint-vs-fuel cost, fleet mix, top consumers), 4 live
  tables (register, work orders, fuel log, document expiry watch) with drill-down
- Construction Projects — 12 KPIs (portfolio value, weighted progress, earned
  value, certified, WIP, spend, margin, tasks...), 4 charts (spend trend,
  manpower, progress by project, spend by category), 4 live tables (portfolio
  scorecard, WBS tasks, IPC valuations, site diaries) with record drill-down
- Procurement — 12 KPIs (requisitions, PO value, open commitments, GRNs, bills,
  payments, payables, overdue, WHT...), 3 charts (POs vs bills vs payments,
  top suppliers, PO value by status), 5 live tables (PRs, LPOs, GRNs, supplier
  invoices, payments) with record drill-down
- Inventory & Warehouse — 12 KPIs (stock value, receipts/issues value, net
  movement, reorder/stockout/overstock alerts...), 4 charts (receipts vs issues,
  value trend, value by category, top issued items), 4 live tables (item balances,
  stock ledger, adjustments, PPE issues) with record drill-down
- Finance & Accounting — 12 KPIs (revenue, expenses, profit, margin, assets,
  liabilities, equity, cash, GL receivables/payables, journals, integrity check),
  3 charts (P&L trend, revenue mix, top expenses), 4 live tables (P&L statement,
  balance sheet with A=L+E+P&L check, trial balance, journals) with drill-down
- HR & Payroll — 12 KPIs (headcount, joiners/exits, gross/net payroll, PAYE,
  SSNIT, employer cost, advances, leave, attendance rate...), 4 charts (daily
  attendance, overtime, headcount by dept, payroll cost split), 5 live tables
  (employee register, payroll runs, payslips, leave, advances) with drill-down
- Health & Safety — 12 KPIs (open incidents, LTIs, fatalities, days since last,
  inspections, closure rate, permits, PPE...), 4 charts (monthly trend, severity,
  type, inspection closure), 4 live tables (incidents, inspections, permits, PPE)
- Environmental Management — 12 KPIs (readings, compliance rate, breaches,
  worst/avg % of limit, dust & noise latest...), 4 charts (readings trend, PM10
  vs EPA limit, compliance split, % of limit by parameter), 2 live tables
  (monitoring register, limit breaches) with record drill-down
- Cash, Bank & Treasury — 12 KPIs (cash position, per-account balances, cash
  in/out, net flow, unreconciled backlog, claims, payables due...), 4 charts
  (flows, balance trend, cash by account, outflows by source), 4 live tables
  (accounts with GL tie-out, transactions, recon backlog, claims) with drill-down
- Ghana Tax & Statutory — 12 KPIs (output/input/net VAT, GL payables, levies,
  WHT withheld & suffered, PAYE, SSNIT...), 3 charts (VAT trend, liability mix,
  WHT by supplier), 4 live tables (GL-vs-source tie-out, output/input schedules,
  IPC WHT) with record drill-down
- Budgeting & Forecasting — 12 KPIs (annual/YTD/MTD budget vs GL actual,
  variances, utilization, over-budget accounts, commitments...), 3 charts (FY
  trend, YTD by account, budget mix), 3 live tables (budgets, account control,
  48 monthly lines) with record drill-down
- Contracts & BOQ — 12 KPIs (contract/BOQ value, executed, % complete,
  certified, uncertified, retentions, subcontracts...), 4 charts (monthly
  valuations, BOQ by project, execution split, subcontracts), 5 live tables
  (contract register, BOQ schedule, IPCs, subcontracts, sub claims) with drill-down
- Maintenance — 12 KPIs (open/high-priority WOs, raised/completed, breakdowns,
  planned work %, cost, downtime, PM overdues, repair time...), 5 charts (monthly
  trend, cost, type mix, cost by equipment, backlog age), 3 live tables (work
  orders, meter-based PM schedule, parts consumed) with record drill-down
- Fleet & Transport — 12 KPIs (trips, tonnage, km, transport cost, cost/t & /km,
  truck & driver counts, hired jobs, own-fleet share...), 4 charts (tonnage & cost
  trends, by truck, by destination), 4 live tables (trip log, truck scorecard,
  hired haulier jobs, haulier register) with record drill-down
- Fuel Management — 12 KPIs (diesel issued/cost, fills, rate, bay stocks, days
  of cover, burn rate...), 4 charts (issue trend, rate trend, top consumers, burn
  rates), 3 live tables (issue log, bay stock, equipment burn scorecard) with drill-down
- Interim Payment Certificates — 12 KPIs (certified count, gross/net, retention,
  advance, WHT, to-date totals, cycle time, WIP, valuation watch...), 3 charts
  (monthly valuations, certified by project, valuation split), 3 live tables (IPC
  register, valuation watch, IPC-to-invoice tie-out) with record drill-down
- Site Management — 12 KPIs (active sites, diaries, coverage %, manpower, plant,
  issues, rain days, spend, task dues...), 4 charts (manpower, spend, coverage by
  site, weather), 4 live tables (site status board, diaries, issues, plant
  deployments) with record drill-down
- Customers & CRM — 12 KPIs (customers, debtors, credit breaches, pay speed,
  pipeline, conversion, AOV, repeat rate...), 4 charts (orders vs collections,
  top customers, aging bands, customer mix), 3 live tables (customer master,
  quotations, aging detail) with record drill-down
- Suppliers & Subcontractors — 12 KPIs (vendors, creditors, overdue bills &
  value, pay speed, POs, GRNs, subcontracts...), 4 charts (billed vs paid,
  top suppliers, AP aging, vendor mix), 4 live tables (supplier master, open
  bills, subcontracts, claims) with record drill-down
- Documents & Permits — 12 KPIs (docs on file, expiring/expired, permits live &
  pending, blasting permits, fleet doc cover...), 4 charts (expiry pipeline,
  permits by status, docs by type, cover per machine), 3 live tables (equipment
  docs, work permits, compliance gaps) with record drill-down
- Reports & Analytics — 12 KPIs (live modules, records managed, activity events,
  creates/updates, active users, catalogue size, debtors, creditors, cash...),
  4 charts (30-day activity, activity by entity/user, ERP coverage), 3 live
  tables (25-report catalogue, data volumes, audit trail) with drill-down
- AI Insights — 12 KPIs (critical/warning/opportunity counts, at-risk value,
  overdue bills & debtors, undocumented machines, quiet sites...), 4 charts
  (severity split, insights by area, money at stake, site reporting pulse),
  3 live tables (insight register, unified watchlist, recommended actions)
- Approvals & Workflow — 12 KPIs (pending queue & value, approved/rejected,
  approval rate, oldest pending, PRs/POs/certs...), 4 charts (monthly decisions,
  requests by flow, queue status, decisions by approver), 3 live tables (pending
  queue with SLA flags, decision history, flow health) with drill-down
- Setup & Configuration / Admin — 12 KPIs (users, logins, roles, permissions,
  permit runway, FY progress, sequences, tax rates...), 4 charts (permissions by
  module, users by role, licence runway, system load), 6 live tables (users,
  roles, sites & stores, numbering, tax rates, settings) — serves #/setup and
  #/admin
**Complete:** all 31 sidebar modules live against `/api/v1/*`.

Runtime-verified headless (jsdom): shell boot, live exec render (12 cards / 10 panels),
scope-change refetch, demo-module fallback, ribbon switching — zero errors.

## Key paths

- `app/Support/CrudRegistry.php` — the 78-entity registry (columns, fields, transitions)
- `app/Services/` — Finance, Stock, Payroll, GhanaTax, Approval, Sequence
- `app/Http/Controllers/` — CrudController + dedicated document controllers
- `database/seeders/` — Rbac / Core / Master / Demo seeders
- `public/css/erp.css`, `public/js/erp.js` — construction-theme UI, no framework
