visitor-signin/.claude-context/00-overview.md

visitor-signin — overview

Self-hosted visitor sign-in/out kiosk for school campuses. Visitors sign in at an iPad kiosk (photo, WWCC/VIT, host), recurring visitors use mobile number + 4-digit PIN, and a label badge prints automatically from a networked Brother QL-820NWB. Staff manage everything from an admin console. A Google Sheet mirrors who is currently on site for evacuation roll calls.

Stack

• Node.js 22, Express, SQLite (better-sqlite3), vanilla JS front end — no build step.
• Single Docker container on an Ubuntu docker host; authoring happens on Windows.
• Server-side badge rendering with @napi-rs/canvas; printing via brother_ql (Python) over TCP 9100.
• Self-signed TLS: local CA + auto-renewing server certificate, distributed to iPads via Jamf Pro.

Surfaces

• / — kiosk (guest sign in, PIN sign in, sign out). No admin link on purpose.
• /admin/login — standalone login (email + password + TOTP).
• /admin — console: on site, visit log, recurring visitors, people to visit, sites, admins, system.
• HTTP helper port — serves the CA (/ca.crt, /ca.cer, /ca.zip) and redirects to HTTPS.

Running it

• Deploy branch: deploy. Host update: git fetch origin && git reset --hard origin/deploy && docker compose up -d --build
• After changing .env: docker compose up -d (never restart).
• Check what's deployed: docker compose exec visitor-signin npm run version.
• Printing diagnostics: docker compose exec visitor-signin node scripts/print-test.mjs.

Where to look

• 01-architecture.md — current design and the reasoning behind it.
• sessions/ — dated session records.
• README.md in the repo root — operator documentation.

Session Log

• 2026-09-23 — Visitor sign-in kiosk: build, HTTPS, and server-side label printing — Built the app end to end; added multi-site, 2FA admin accounts, self-signed CA for Jamf-managed iPads, server-side QL-820NWB printing (found --red is mandatory on DK-22251), single-tab evacuation sheet, branding, and photo halftoning.