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 a frontier vision LLM 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.