visitor-signin/.claude-context/01-architecture.md

visitor-signin — architecture

Current state of the design. Established 2026-09-23 (first recorded session). When a later session changes something here, edit the relevant section and note the date and reason.

Process layout

One Node process in one container:

• HTTPS listener on container port 3000 (kiosk, admin, APIs).
• Plain-HTTP helper on 3001: serves the CA certificate and redirects everything else to HTTPS.
• Background jobs in-process: photo retention purge, optional nightly auto sign-out, daily certificate renewal check, Google Sheet sync retries.

Data

• SQLite at /data/visitors.db (bind-mounted ./data), WAL mode.
• Photos on disk under /data/photos/YYYY/MM/; banners under /data/branding/; certs under /data/certs/.
• Migrations are additive and idempotent (addColumn in src/db.js) — never destructive.
• visits denormalises name, contact, host and site name, so history survives deletion of the related records.

Identity and access

• Admin accounts: email + scrypt password + TOTP (RFC 6238), eight one-shot recovery codes. Roles owner (manages admins and sites) and admin (optionally scoped to one site). Optional email-domain restriction. First account created once from ADMIN_BOOTSTRAP_*.
• Recurring visitors: mobile number is the username; PIN is 4 digits, stored AES-256-GCM encrypted with a keyed HMAC pin_lookup for uniqueness. Phone, email and PIN are each unique.
• APP_SECRET keys sessions, PIN encryption and pin_lookup. Changing it breaks every PIN.

Multi-site

• sites owns: people to visit (hosts), badge settings, printer settings, branding.
• A kiosk is bound to a site by /?site=<slug> (remembered in the tablet's local storage) or a first-run picker; a single-site install never asks.
• Sign in, sign out and duplicate detection are scoped per site.

TLS

• Local CA (10 years) + server certificate (398 days), generated by the container with openssl.
• Server cert renews inside 30 days and is hot-swapped with setSecureContext; the CA is never replaced except by an explicit --force, so devices trust it once.
• Reissue is triggered by a change in HTTPS_HOSTNAMES (tracked in certs/.hostnames.json), not by the full SAN list, because the container's own bridge IP changes between restarts.
• CA distributed as PEM .crt, DER .cer (required by Jamf Pro) and a zip bundle (browsers block bare certificate downloads).

Printing

• The server renders the badge (src/printer.js, @napi-rs/canvas) at 300 dpi, 696 dots across (QL-820NWB head width on a 62 mm roll), and sends it with brother_ql over TCP 9100.
• Photos are halftoned in the renderer (Floyd–Steinberg by default) so preview equals print.
• The loaded roll is an explicit per-site setting (printer_label: 62 or 62red). 62red always adds --red; without it the job is monochrome and the printer refuses it.
• Sign in waits up to PRINT_SIGNIN_WAIT_MS for the print; on failure the kiosk falls back to a browser print of the HTML badge (src/sites.js).
• brother_ql's network backend never reads the socket and the QL-820NWB does not answer status requests on 9100, so the server cannot confirm a label came out. Brother Status Monitor on a connected PC is the source of truth for refusals.

Google Sheet

• Evacuation mirror only: one tab ("On site now"), rewritten in full on every sign in/out and every 15 minutes. No history is sent to Google; history lives in the app (Visit log, CSV).
• A failed write marks the tab stale and is retried; it never blocks the kiosk.

Front end

• Three separate documents: kiosk (index.html), login (login.html), console (admin.html).
• Kiosk theming is per site: four chosen colours, the rest derived with WCAG contrast rules.
• HTML/JS/CSS served with Cache-Control: no-cache so an upgrade is never masked by a cached console.

Deployment

• Author on Windows, deploy on an Ubuntu docker host from the deploy branch with git reset --hard origin/deploy (the host is a mirror, never merges).
• docker-entrypoint.sh fixes ownership of the bind-mounted /data, then drops to node.
• pull_policy: build — the image is always built locally.