WhiteFleet

The tensions

A worker belongs to several companies at once. So their identity, documents, and pay details can't live under any one company. But every shift, task, and attendance record is company-scoped and must stay walled off from the others.

One API serves four different roles. A company admin, a supervisor who sees only their own departments, an accountant, a WhiteFleet staffer, and a worker all hit the same Express server. The permission boundaries can't be a frontend decision — a supervisor could just call the endpoint directly.

The same email can be three people. Someone might be a platform staffer, a company admin, and a worker all at once. On login the server has no idea which of its three apps is asking.

---

The build

Making the worker the root, not the company

The situation: a worker's licence, bank details, and tax file live on the person, but eight companies might each need to read them.

The decision: split the schema down the middle. Worker-owned tables — wallet_documents, wallet_grants, users_bank_details, users_tax_information — hang off the person. Company-scoped tables — user_company_memberships, user_details, attendance, tasks — hang off the membership. A company never holds the worker's data. It holds a grant that lets it read a live copy.

Why not the usual approach: copying the worker's documents into each company's record would have been faster to ship and a compliance landmine later. Eight stale copies of a licence, no single source of truth, no clean way to prove consent. I didn't want to be writing cleanup jobs a year in.

What it produced: a 57-model Prisma schema with a hard line between what the worker owns and what the company sees. The invite→accept handshake is the spine — a company sends an invite, the worker accepts it on the mobile app, and the membership activates with zero admin action on the other end.

The consent ledger that never deletes

This is the part I'm most sure about. A company reads a worker's bank details through a wallet_grants row. Revoke the grant and the data disappears from the company's view immediately — no cleanup, no stale copy, because the company never had a copy to begin with.

The decision: make grants append-only. Revoking doesn't delete the row; it stamps revoked_at. The table is simultaneously the live access-control mechanism and the audit trail. The history is the proof of consent.

What it produced: privacy enforced by the data model rather than by policy. When a worker pulls a grant, the code sets revoked_at on the active rows and the next read returns nothing. The trail of who could see what, and until when, is permanent.

One API, four permission surfaces, server-enforced

The situation: a supervisor must see only their own departments' workers, attendance, and tasks. The same endpoint has to return everything for an admin. And it has to hold up against someone calling the API by hand.

The decision: a three-step resolution chain on the server. resolveCompanyActor authenticates the Supabase JWT, finds the user, and verifies an active membership or admin link for the requested company. resolveCompanyAdmin adds an admin gate for mutations. resolveCompanyActorOrSupervisor enriches the actor with their systemrole and the exact supervisedGroupIds they oversee, so every downstream query filters by those IDs.

On the client, a useRole hook derives boolean permission flags from the role string, and a useDepartmentScope hook auto-appends the correct department filter to API queries. Supervisors get narrowed everywhere without per-page wiring.

Why this way: a frontend filter would have been a lie. The scoping lives on the server, so a supervisor who curls the endpoint for another department gets nothing back — not a 403 that leaks the department exists, just an empty result.

Routing one identity to the right app

The situation: three frontends, one Supabase Auth instance, one server. The same email could be a platform staffer, a company admin, and a worker.

The decision: a single dashboard-gate resolver that runs on every app load. It looks the user up by Supabase ID and email in parallel, checks platform_staff first, then company admin links and memberships, and if none of those match but a worker membership exists, it returns an "employee → use the mobile app" signal. Company access also runs through a registration and billing state machine — pending_review → approved → active / grace / expired / suspended / canceled — so a lapsed company hits a locked screen, not stale data.

The result is cached in-memory for 30 seconds per user to kill redundant DB roundtrips. Registration and error states are never cached, so an approval takes effect on the next load instead of thirty seconds later.

---

Under the hood

One Express 5 + Prisma 6 server over Postgres (Supabase), fronted by three clients: a React 19 / Vite company-admin app, a React 19 platform app for internal staff, and an Expo SDK 54 / React Native worker app. Auth is a single Supabase JWT the server validates on every request; the resolver chain turns that token into a scoped actor before any query runs. The mobile client uses TanStack Query with company ID baked into every query key, so switching companies refetches cleanly instead of showing another company's cache. No websockets — chat and task updates are request-driven, and recurring rosters run off a node-cron engine on the server. State machines, not booleans, guard both billing and document lifecycle.

---

What shipped

A working four-surface platform on a 57-table schema, in early pilot with Australian labour-hire clients testing it against real operations. No large user base yet — I'm not going to dress that up. What it demonstrates is the quality of the decisions underneath: a consent model that makes data leaks structurally hard, server-enforced role scoping that survives a hand-crafted request, and one auth system that routes three apps without role confusion. The hard parts are the ones you can't retrofit later — the data model and the permission boundaries — and those are built.

---

Looking back

I designed the document system around AI-first verification — Claude Haiku auto-clearing uploads for cents each, humans reviewing only the low-confidence ones. I built the badge that travels with the worker and reserved an ai_verified status for it. Then V1 shipped with human-only review, the AI leg still a stub. It was the right call to cut for the pilot, but I'd started the wrong end first: I wired the verification plumbing before I had the volume of documents that would justify automating it. If I did it again I'd ship the manual queue, watch what real uploads actually looked like, and let that shape the model — instead of building for a scale I was guessing at.