Public Access
72 lines
4.1 KiB
Markdown
72 lines
4.1 KiB
Markdown
# 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.
|