Karimu Field Audit

Offline-first maintenance audit app for Karimu Foundation volunteers. Approved by Nelson to go live for water point audits: pick a Ward, Village, optional Sub-Village, and Asset Tag from the Water Assets registry, work the maintenance checklist without any connection, then Sync when back online. School building / school bathroom / health post audits are built and still in the code (available:false in lib/checklists.js), but are not in active use right now — flip that flag back on if/when they're needed again.

Ported from an interactive prototype — see lib/checklists.js for the full item lists and applicability rules, lib/waterAssets.js for the embedded Water Assets registry powering the picker, and lib/engine.js for the app itself (screens, offline storage, sync).

Run locally

npm install
npm run dev

Open http://localhost:3000.

Deploy

This is a stock Next.js App Router project — deploy it to Vercel by connecting this repository (Import Project → this repo) or with vercel deploy from a machine that can reach vercel.com. No special build settings needed.

Water Assets registry

lib/waterAssets.js embeds the full "Water Assets" tab of the Water Assets sheet — 1,717 assets across the Ayalagaya, Arri, and Kiru wards, as of the 2026-08-25 export — so the Ward → Village → Sub-Village → Asset Tag picker works fully offline, same as everything else in this app.

Of those, 1,693 are Water Points and 24 are Water Tanks. Only Water Points are in the picker right now — Nelson's scope decision, confirmed 2026-08-25 — via a filter on WATER_ASSETS in lib/waterAssets.js; the raw 1,717-row list stays in the file either way. If tanks come into scope later, dropping that one filter brings them back, and the 51-item "Tanks and Intake" checklist in lib/checklists.js (WATER_TANK_SECTIONS) is already written and wired up to assetType === "T" — it's just unreachable while every asset in the picker is a Water Point.

Of the 1,693 Water Points, the sheet's "Ownership" column marks 332 as Public and 1,361 as Private. Only Public Water Points are in the picker — Edu's scope decision, confirmed 2026-08-26: private water points aren't part of Karimu's audit program. Same reversible-filter pattern as Water Tanks above (an isPublic flag on each row, checked alongside the Water Point type check in WATER_ASSETS) — the 1,361 private rows stay in the file, just unreachable from the picker, route, or map anywhere in the app. Two of the 332 Public Water Points (in Kiru) have no village on file and so don't surface in the Ward → Village → ... picker either — that's the sheet's data (see the Kiru note below), not something this filter did.

The Water Point checklist itself (WATER_POINT_SECTIONS in lib/checklists.js) is sourced from the "Maintanence checklist-Water Project" tab of a separate sheet, and picked automatically based on the selected asset's type.

This data goes stale as the registry sheet changes — new water points, renamed villages, corrected wards, ownership changes. There's no live sync back to the sheet; re-export it and regenerate lib/waterAssets.js (a plain array of [assetTag, assetType, ward, village, subVillage, location, lat, lon, volunteer, routeOrder, isPublic] tuples — see "Volunteer identification and routes" below for the volunteer/routeOrder pair) when it's meaningfully out of date. Two Kiru assets have no village/sub-village on file and use "" — that's the sheet's data, not a bug here.

The 81 individual checklist statements (in both the Water Point and Tanks and Intake sections) are kept verbatim from Nelson's checklist and are only in English — see the i18n note below on why that's an acceptable gap for now, and how to close it later.

Auditor accounts and audit projects

Added 2026-10-28. Replaces picking a name from a fixed list (see the historical section below).

Accounts. On the admin page, "Add auditor" (name + email) creates an account and shows an invite link once — copy it or send it by WhatsApp. The auditor opens it on their phone, picks a language, and creates a password (8+ characters); the phone is then signed in. The link works once and expires after 7 days. The same button ("New invite link" / "Reset password") issues a fresh link to reset a forgotten password; using it signs out every device still on the old password. "Deactivate" blocks sign-in and signs the auditor out of every device at its next sync.

On the phone. Sign-in needs signal once; after that the device keeps a 90-day token and the auditor's assignments, and works offline as before. Both refresh from /api/me whenever there's signal. Sync now requires that token (/api/sync used to accept anything from anyone) and records who sent each audit (auditorId/auditorEmail). A device that's signed out keeps its unsynced audits and syncs them after signing in again.

Projects. "Create project", then assign each of the 24 water-point groups (the existing ones in lib/waterAssets.js) to an auditor with a field day — e.g. 5 groups on days 1-5 for one auditor. Only active projects reach phones; an auditor's "My route" lists their groups by day.

This is the beginning of the README. Read the rest at the original. Read the full README ↗