FairShift: every shift gets a receipt

Live: https://fairshift-five.vercel.app · Prompt Wars 2026 · UN SDG 8 (Decent work)

Construction sites and college campuses run their workforce on paper registers. The register belongs to the boss, so pay is opaque, complaints get traced, and hazards are ignored until someone is hurt. FairShift makes the worker's phone a second register: their own copy of hours, pay math and the status of every report, in Tamil.

Chosen vertical

UN SDG 8, Decent work and economic growth (targets 8.5 equal pay, 8.8 labour rights and safe work). Persona: a daily-wage or contract worker (mason, helper, security guard, housekeeping) who speaks Tamil, uses a low-end Android phone and has no say over the paper register. Second persona: the site admin who needs to see hazards and overwork early.

Approach and logic

• Context decides the logic. Each worker belongs to a site, and each site runs a rule pack (lib/rules.ts): wage basis, overtime thresholds, hazard categories, severity floors, feedback themes. The same report or the same 12-hour shift gives a different, correct result on a construction site and on a college campus.
• AI listens, rules decide. Gemini turns Tamil speech or text into schema-constrained JSON. Pay, overtime, fatigue flags, severity floors and the Sealed Voice unlock threshold are plain functions with unit tests.
• Decisions are explainable. Every flag states its rule and an action ("13 days without rest: schedule a day off").
• A shift assistant decides the next step. lib/assistant.ts turns each person's own context into ranked next steps, each with the rule behind it (see How FairShift decides below).

How it works

Screen	What it does	Code
Landing page /	Live Shift Receipt hero, key figures, problem → features story, worker tiles, rule-pack comparison	app/page.tsx
Worker app /w/[id]	Key figures and the worker's own rest flags; weekly pay receipt with overtime bars and Tamil read-aloud; Voice Hazard recorder; "Speak up (sealed)"	app/w/[id]/page.tsx, components/HazardReporter.tsx, components/SpeakButton.tsx
Admin dashboard /admin?site=	Key figures, hazard-resolution gauge, crew hours chart, worker × day heatmap, filterable live hazards (cards on phones), attention list, Sealed Voice, crew pay table with CSV export	app/admin/page.tsx, components/LiveWidgets.tsx, components/Kpi.tsx
Shift assistant	Worker: "What to do next" in English + Tamil, read aloud. Admin: ranked "Do this first"	lib/assistant.ts, app/w/[id]/page.tsx, components/LiveWidgets.tsx
Live data	One poller for the whole dashboard (4s, 204 when unchanged, paused when hidden)	components/live.tsx
Shared UI	One look on all three screens: top bar, cards, key figures, status pills	components/TopBar.tsx, components/Card.tsx, components/Kpi.tsx, components/StatusBadge.tsx
API	Hazards POST/GET/PATCH and Sealed Voice in one route (shares one in-memory store)	app/api/hazards/route.ts, lib/store.ts
Rules (tested)	Pay, fatigue, severity floor, Sealed Voice grouping, site totals and CSV, rule packs, rate limit	lib/pay.ts, lib/fatigue.ts, lib/severity.ts, lib/sealed.ts, lib/crew.ts, lib/rules.ts, lib/ratelimit.ts
AI	Gemini, schema-constrained JSON, temperature 0, falls back across models on quota errors	lib/ai.ts

How FairShift decides (user context → decision)

Who	Context	Decision (most urgent first)	Why it is shown
Worker	7+ days in a row	Act now: ask for a day off	7+ days without rest is HIGH
Worker	Over 60h (or 48h) in 7 days	Act now (or Check): ask for shorter shifts	Over 48h/week is overtime; over 60h is HIGH
Worker	Under 10h between shifts	Check: start later tomorrow	At least 10h rest between shifts
Worker	Any overtime	Check: pay slip shows the overtime amount	Over 8h/day or 48h/week is paid at 2×
Worker	None of the above	All good	Within the site's rule pack
Admin	Open HIGH hazard	1. Fix it (oldest first)	Safety first
Admin	Report Gemini could not read	2. Read the original report	Never lose a report
Admin	Worker with a HIGH fatigue flag	3. Take the flag's action	Overwork before feedback
Admin	Open MEDIUM hazard, unlocked Sealed Voice theme, WARN flag, LOW hazard	4–7, in that order	Lower risk

The same report or shift gives a different, correct decision under each site's rule pack. Tested in tests/assistant.test.ts.

Assumptions

• Demo workers, sites and shifts are fictional and seeded relative to server start (lib/seed.ts).
• Overtime is 2× beyond 8h/day or 48h/week; monthly wages assume 26 working days. These are illustrative defaults.
• Workers have a phone with Chrome; Tamil read-aloud needs a Tamil text-to-speech voice and hides itself otherwise.
• One warm server instance serves the demo (in-memory store); a real deployment would use a database.

Brief → feature → code → SDG 8

Worker pain	FairShift feature	Code	SDG 8 target
Pay and overtime are opaque	Shift Receipt: day-by-day hours, regular × rate, overtime × 2 × rate, total owed, read aloud in Tamil	lib/pay.ts, app/w/[id]/page.tsx	8.5 equal pay, 8.8 labour rights
Workers and admins don't know what to act on first	Shift assistant: ranked next steps from each person's own records, each with its rule	lib/assistant.ts	8.8, 8.5
Hazards ignored, reporters identified	Voice Hazard: speak or type in Tamil → Gemini → HIGH card on the admin board → Acknowledged → Fixed → status read aloud on the worker's phone. No reporter identity stored	app/api/hazards/route.ts, lib/ai.ts, lib/severity.ts, components/HazardReporter.tsx	8.8 safe working environments
Overwork goes unseen	Attention list: explainable fatigue flags with an action ("13 days without rest: schedule a day off")	lib/fatigue.ts, app/admin/page.tsx	8.8, 8.5

AI listens, rules decide. Gemini only converts speech/text into structured JSON (schema-constrained, temperature 0, validated with zod). Money and alerts are plain functions with unit tests. Gemini never touches a rupee, and it can raise a hazard's severity but never lower it below the rule pack's floor.

Cross-industry: config, not code

	Construction site	College campus
Wage basis	daily (Rs 700/day)	monthly (Rs 15,000)
Overtime	2× beyond 8h/day or 48h/week	2× beyond 8h/day or 48h/week
Hazard categories	fall from height, scaffolding, electrical, no PPE, heat stress	electrical, lab chemical, fire exit blocked, structural damage, slippery floor
Severity floor (HIGH)	fall from height, electrical	electrical, fire exit blocked

A hospital or factory is one more entry in lib/rules.ts. Defaults are illustrative; verify the applicable state rule before using real figures. Under this pack a 12-hour guard shift is worth two 8-hour days of pay.

Architecture

Worker phone (/w/[id])            Admin (/admin?site=...)
   record / type / poll status       poll every 4s (204 when unchanged)
            \                         /
          Next.js 16 on Vercel: /api/hazards (POST, GET, PATCH)
            lib/* pure functions (pay, fatigue, severity, rules)
            lib/ai.ts -> Gemini API (Flash-Lite, falls back across models on quota errors), server-only key

Run, test, deploy

npm install
cp .env.example .env.local   # set GEMINI_API_KEY (server-only, never NEXT_PUBLIC_)
npm run dev
npm test                     # Vitest (46 tests): pay, fatigue, severity, sealed, assistant, crew, format, rate limit
npm run lint

Deploy: push to main; Vercel builds it. GEMINI_API_KEY is set as a Vercel sensitive environment variable. Demo workers (fictional): Murugan and Selvi (construction), Ravi and Lakshmi (college).

Security and accessibility

• No keys in the repo or the browser bundle: the Gemini key is a server-only Vercel secret; .env* is gitignored.
• Every request body is validated (zod, size caps: audio ≤ 1 MB, text ≤ 500 chars). Audio is processed and discarded.
• Rate limit: each client may file 8 reports per 10 minutes (429 + Retry-After), which also protects the Gemini quota. The limiter key lives in memory for the window only and is never logged or stored with a report.
• Prompt injection: the system instruction treats the report as data; output is schema-constrained; React escapes display.
• Headers: frame-ancestors 'none', nosniff, Referrer-Policy: no-referrer, Permissions-Policy: microphone=(self).
• Real buttons and labels, skip link, 3px focus ring, 48px+ targets, mic is a toggle with aria-pressed and a visible timer (keyboard-usable), severity is icon + word + color, overtime bars use a stripe pattern, lang="ta" on Tamil text, role="status" / aria-live for updates. Read-aloud only uses a Tamil voice; it hides rather than reading Tamil with an English voice.
• Checked with Lighthouse: accessibility 100 on /, /admin and /w/murugan, mobile and desktop. Layouts verified at 1440px and 390px with no horizontal scrolling; on phones the hazard table becomes cards so actions stay on screen.

Limitations (honest)

• Demo store is in memory behind one API route: it resets on a cold start and assumes one warm instance. Next step: Supabase or Upstash Redis.
• No login yet: worker and admin pages are open for the demo. Next step: PIN login and an admin role check.
• Gemini free tier allows about 20 requests per model per day; lib/ai.ts falls through several models on 429s. Google may use submitted content to improve its products; a production deployment should use a paid tier or Vertex AI.
• Hosting logs keep IP and time, so someone with project access could correlate anonymous reports.
• Rule packs are defaults, not legal advice.