How StaffPortal works

Every request must answer two questions: who is the user, and which organisation are they acting in? Both questions are answered before any business logic runs.

Supabase Auth issues a JWT with user_id (auth.uid()) and a custom organisation_id claim populated on sign-in. The JWT lives in an HttpOnly cookie. Server components and route handlers read it via the @supabase/ssr helper. Every PostgreSQL policy reads both claims to scope rows.

Hours worked are the bedrock of payroll. The system must capture them accurately on the web, on a tablet kiosk, and via manager bulk edits — and produce a single approved timesheet at the end of the period.

clock_events records every clock-in and clock-out as a discrete row with timestamp, source (web/kiosk/manual), photo URL when available, and geofence flag. A nightly job aggregates events into timesheet_lines with break deduction and overtime calculation. Managers approve at the timesheet level; the underlying events remain immutable.

Per-employee allowances must accrue continuously, decrement on approval, and be auditable retroactively. Conflict detection prevents two key team members booking the same week off.

leave_balances is a SQL view computed from leave_allowances and approved leave_requests. Submission triggers a notification to the line manager. Approval mutates the request status and fires a calendar event to the team channel. The team_calendar view aggregates all approved leave for visualisation.

Receipts are the single biggest source of HR data-entry friction. The fastest path is photograph, OCR, validate, submit — under ten seconds.

POST /api/expenses/scan accepts a multipart image. The image passes through sharp.rotate().resize(1568).jpeg(85), then to Anthropic Claude vision with the Receipt Scanner system prompt. Output is Zod-validated and inserted as a pending expense with full raw JSON in the raw column. A manager approval notification fires.

On-site staff need to clock in from a wall-mounted tablet, often on flaky Wi-Fi. The kiosk has to work offline and sync on reconnect.

A separate /kiosk route renders a touch-first React UI. Service worker caches the shell. IndexedDB stores queued sign-in events as { user_id, timestamp, photo_blob, geo? }. On navigator.online, a flush handler POSTs each queued event to /api/kiosk/sign-in and removes it from the queue on 200.

Compliance, security, and host-notification needs converge in visitor sign-in. The system tracks pre-registration, photo capture, NDA acknowledgement, and host alerts in one flow.

Pre-register a visit via /visitors/new. On arrival, the visitor signs in via the kiosk by name lookup, captures a photo, acknowledges the host's NDA if applicable, and triggers an email + Slack alert to the host. visitor_visits records the full lifecycle. Watchlist matches block sign-in and notify security.

Approval workflows, leave decisions, expense rejections, announcements, and visitor alerts all require timely delivery. Three channels — email, Slack, in-app — with per-user preferences.

lib/notify.ts exposes notify(userId, eventType, payload). Reads notify_preferences for the user, fans out to enabled channels. Email via Resend with templated HTML. Slack via incoming webhook with formatted blocks. In-app via realtime broadcast to the user's subscribed channel. Every send is logged to notify_log for audit.

Managers need real-time visibility on attendance trends, leave balances, and expense patterns. Payroll teams need a clean monthly export.

Materialised views over the live tables compute attendance heatmaps, leave-by-team breakdowns, and expense totals by category. /analytics renders these via server components with chart components from recharts. Monthly close exports CSV in Xero/QuickBooks/Sage-compatible formats with the correct GL codes.

Server components keep authorisation and DB queries server-side. Server actions cut form-submission boilerplate. File-based routes map to module structure.

Pages Router — older paradigm, more client-side state, less natural fit for streaming and partial pre-rendering.

Postgres + Auth + RLS + Storage + Realtime in one service. Reproducing this in-house is 3,000+ lines and a permanent operational burden.

Custom Postgres + Lucia/NextAuth + S3 + custom WebSocket layer — works, but you maintain four systems instead of one.

Multi-tenancy at the application layer is one bug away from data leakage. RLS makes Postgres refuse cross-tenant reads regardless of route logic.

Application-layer scoping only — works until it does not. Authorisation should be defence in depth.

One codebase. No app store. Updates ship instantly. IndexedDB offline queue handles real site Wi-Fi conditions reliably.

Native iOS/Android — multiplies maintenance, app store gatekeeping for what is fundamentally a PIN-and-photo screen.

Reuses a published, hardened OCR pipeline. Same prompt, same Zod schema, same accuracy.

Reimplement OCR per product — duplicates work, drift between expense scanning here and the standalone product, no shared improvements.

Cleanest API, simplest verification, generous free tier, SDK-level templated HTML.

SendGrid — heavier API, opaque pricing. SES — IAM and sandbox approval drag for what should be one env var.

leave, expense, timesheet, visitor approvals share 90% of their logic. One table with target_type halves the route code.

Per-entity approval tables — duplicates schema, route code, and notification logic five times.