SmartKey

SmartKey is a key management web application for the University of Lagos Senate Building. It replaces the paper logbook at the security desk with role-specific dashboards, an immutable audit trail, and three supporting AI components.

The Senate Building has two zones (New Senate and Old Senate). Staff borrow physical room keys from a security desk. SmartKey tracks who is authorised to collect each key, issues a short-lived verification code for each request, records every issue and return, and flags requests that fall outside normal patterns.

Roles

Four roles share the application, each with its own dashboard:

• CSO (Chief Security Officer) — system-wide oversight. Reviews anomalies, generates shift reports, manages user accounts and key inventory, searches the audit log, and configures operational settings.
• Dean — authorises up to three collectors per faculty key, approves weekend access requests, and uploads a reference signature and stamp on first sign-in. (Internal identifiers — hod_decisions, HOD_APPROVED, /api/requests/hod-decision — keep the older "HOD" name for historical continuity; the role itself is DEAN.)
• Verifier — security personnel at the desk, working 8-hour shifts. Issues and receives keys, acknowledges outstanding keys at shift handover, and logs incidents.
• Requester — university staff. Requests a key, receives a 6-digit code by email, and presents it at the desk to collect.

External (non-registered) people can also submit a weekend-only request through a public form; a Dean authorises it and the guest collects with a code, checked against their physical ID at the desk.

How a key request works (weekday)

1. A requester selects an authorised key and confirms a return time. If every copy of that key is already out or reserved, the request is refused here rather than at the desk.
2. The system runs the risk engine, generates a 6-digit code (valid 10 minutes by default; the CSO can set anything from 5 to 60 in /cso/settings), and emails it. The code reserves one copy until it is used or lapses.
3. The requester presents the code at the desk. The verifier sees the requester's name, photo, the key, and a risk tier before issuing.
4. On return, the verifier records the handover. Every step writes an audit entry.

A key record is a room's set of interchangeable copies (keys.key_count), not a bunch handed over as a unit. A room with three keys can be with three people at once and the fourth request is refused; most rooms have one, where this behaves exactly as a single key always did.

Weekend access is a separate flow. It needs Dean approval first (or CSO approval, for Administration keys) — the Dean can decide straight from the notification email through a one-click link, without signing in. The code is not issued at approval time: the requester mints it themselves on the requested day, so it is never long-lived.

AI components

• Risk scoring — a rule-based engine (pure TypeScript, no external API) assigns each request a Low / Medium / High tier from explainable rules. The verifier can see the contributing factors.
• Shift reports — Google Gemini generates a readable summary of a shift from its raw audit events, with a deterministic template fallback when the API is unavailable.
• Signature verification — Sharp and Pixelmatch compare a Dean's submitted signature against their onboarded reference at the pixel level to detect gross tampering. It is a tamper check, not proof of authorship, and its threshold is still calibrated against synthetic fixtures rather than real signatures — see docs/AI.md. A mismatch never auto-blocks: it holds the action (a weekend request approval, or a Dean replacing their own reference signature/stamp) and raises a review item on the CSO dashboard, where the CSO approves or declines it after comparing the images side by side.

All AI runs server-side, and every AI output is inspectable rather than presented as a black-box decision.

Tech stack

• Framework: Next.js (App Router), React, TypeScript (strict)
• Database / Auth / Realtime / Storage: Supabase (Postgres with Row Level Security, email-OTP MFA, websocket subscriptions, file storage). Storage buckets are private; images are served through an authenticated proxy route that re-checks the session on every request, not via public or signed URLs.
• Scheduled jobs: pg_cron inside Postgres (there is no separate scheduler, and the Edge Functions that once held these jobs have been removed)
• UI: Tailwind CSS with shadcn/ui and lucide-react icons
• Forms: react-hook-form with zod
• Client data: TanStack Query; date handling via date-fns
• Email: Nodemailer over Gmail SMTP
• Testing: Vitest (unit and component), Playwright with axe-core (E2E), pgTAP for RPCs and RLS. The pgTAP suites run in CI on every push and pull request; running them locally needs a local Supabase stack, so Docker is required. They cover a subset of the RPCs — see docs/TESTING.md for what is and is not covered.
• Hosting: Vercel (frontend and API routes), Supabase Cloud (backend), Vercel Blob (daily audit-log export)

Scheduled jobs

Seven pg_cron jobs run inside Postgres. Three of them (the reminder, digest, and export jobs) call an API route over HTTP with a shared bearer secret, because sending email and writing to Blob storage cannot be done from plpgsql. All times are UTC.

Job	Schedule	What it does
expire-lapsed-codes	every 10 min	Tidies up unclaimed collection codes¹
overdue-key-check	hourly	Marks overdue keys, then emails overdue reminders
daily-shift-summary	18:00	Queues a shift report for the day's last shift
expire-stale-weekend-requests	00:15	Expires weekend requests whose date has passed
weekend-code-reminders	06:00 Sat, Sun	Reminds approved requesters to mint their code
daily-digest	07:00	Sends the opt-in activity digest to Deans and the CSO
audit-log-export	02:00	Exports the previous day's audit log to Vercel Blob

¹ It marks the request EXPIRED; it is not what frees the key. A code stops reserving its copy the moment it lapses, so the key is requestable again immediately rather than up to ten minutes later.

Getting started

Install dependencies and start the development server:

bun install
bun run dev

Open http://localhost:3000.

Copy .env.local.example to .env.local and fill in the required values (Supabase URL and keys, Gemini API key, Gmail SMTP credentials, and risk-engine thresholds) before running against a real backend.

To confirm the app can reach the database:

curl http://localhost:3000/api/health

GET /api/health is unauthenticated and runs a real query, returning 200 when Postgres answers and 503 when it does not. It exists for external uptime monitoring: the landing page is statically rendered and returns 200 with the database completely down, so a monitor pointed at / would stay green through a total outage.

Common commands

bun run dev          # Start the development server
bun run build        # Production build
bun run lint         # Run ESLint
bun run typecheck    # Type-check with tsc
bun run format       # Format src/** with Prettier
bun run test         # Unit and component tests
bun run test:e2e     # Playwright E2E tests
bun run test:db      # pgTAP suites (needs a local Supabase stack, so Docker)
bun run db:migrate   # Apply Supabase migrations
bun run db:types     # Regenerate src/types/database.ts from the local schema

Project layout

src/app/          App Router routes, one group per role plus public and api
src/components/   ui/ (shadcn primitives) and smartkey/ (app components)
src/hooks/        Realtime subscriptions, connection status, small utilities
src/lib/          Supabase clients, audit writer, AI integrations, utilities
src/types/        Shared TypeScript types and zod schemas
src/tests/        Unit and component tests (not co-located with components)
src/proxy.ts      Auth and role gating (Next.js 16's rename of middleware.ts)
supabase/         Migrations, RLS policies, seed data, pgTAP tests
tests/            Playwright E2E specs and the post-deploy smoke test
design-system/    DESIGN.md (design tokens), screens, prompt files
docs/             Long-form documentation

Documentation

• CLAUDE.md — conventions and project rules
• docs/PRODUCT.md — domain and product context
• docs/ARCHITECTURE.md — architectural decisions
• docs/BACKEND.md — backend system design
• docs/API.md — API route catalogue
• docs/DATABASE.md — database schema
• docs/AI.md — AI integration details
• docs/TESTING.md — testing strategy
• docs/SCREEN_CHECKLIST.md — required states and checks for any new screen
• docs/GLOSSARY.md — project and UNILAG-specific terms
• docs/GITHUB.md — labels, milestones, branch and PR conventions
• docs/CHANGELOG.md — what changed and why, newest first
• docs/adr/ — architectural decision records
• design-system/DESIGN.md — design system and tokens