💻 Device Loans

Overview

A three-interface loan management system covering the full device lifecycle — from self-service borrowing through staff processing to admin fleet oversight. Each interface is tailored to its audience: a kiosk for borrowers, a queue for ICT staff, and a dashboard for administrators. Authentication is managed via NextAuth with role enforcement from mc-rbac.

Key Features

• Self-serve kiosk — Borrowers use /kiosk to initiate a loan with a confirmation flow, no staff interaction required
• Staff queue — ICT staff manage reservations, handovers, and returns at /staff with a real-time view of pending actions
• Admin dashboard — Administrators manage device pools, view fleet status, and configure loan policies at /admin
• Real-time staff streaming — Server-Sent Events via /api/staff/stream push live updates to the staff queue (new reservations, returns) with keep-alive pings every 15 seconds
• Smart due-date calculation — Domain logic in /src/domain/deviceLoans/dueAt.ts computes return dates based on loan type and school calendar rules

Architecture

Follows domain-driven design with business logic isolated in /src/domain/deviceLoans/ — including the loan service, custom error types, and due-date calculation. This keeps framework concerns (Next.js routing, Prisma queries) separate from core business rules.

Testing

• Vitest unit tests for domain logic
• Playwright E2E tests for kiosk, staff, and admin flows
• Stryker mutation testing with 100% score thresholds on critical domain files (dueAt.ts, service.ts)
• Docker integration tests for full-stack verification

Design Decisions

• SSE over WebSockets: The staff queue only needs server-to-client updates — “a new reservation came in,” “a device was returned.” There’s no need for bidirectional communication. SSE is simpler: standard HTTP, automatic reconnection on disconnect, no WebSocket server or upgrade handling. Polling would work but adds unnecessary latency and bandwidth waste. SSE hits the sweet spot for a one-way notification stream.
• 100% Stryker mutation threshold: Due-date calculation involves school calendar rules — term dates, weekends, holidays. Getting this wrong has real consequences: a student keeps a loaned laptop over a break, or gets asked to return it during an exam period. It’s the single piece of logic the entire loan workflow depends on. 100% mutation score ensures every conditional branch is genuinely exercised by tests, not just line-covered — the kind of logic where a subtle off-by-one silently causes problems for weeks before anyone notices.