Visitor System — Requirements & Implementation Plan

Date: 2026-10-04 Status: Core business requirements discussed and confirmed. Suggestions and pending verification items marked in this document are not confirmed requirements. Product Language: English; this document is written in English.

Implementation Status (2026-10-04): 3-step visitor check-in, email check-out, agreement snapshot, signature/photo capture, evidence review with administrator authorization, and notifications to visitors and host employees are implemented. Azure PostgreSQL migration 20261005000000_visitor_checkin_evidence has been applied. Photos and signatures are currently stored locally in the project directory .visitor-files where the application runs. Before deploying to multiple instances or cloud environments, these files must be migrated to private, persistent object storage. Actual tablet/phone camera testing, Brother printer integration, queued email delivery, data export, and record cleanup are pending.

1. Product Goal & Deployment

Build a simple self-service visitor registration system for companies. Visitors check in using a front-desk tablet or scan a QR code to register on their own mobile phones. Pre-registration is not required.

• Use the same application codebase; each company gets an independent deployment with its own dedicated PostgreSQL database.
• Version 1 does not implement a multi-tenant platform. Each company instance supports multiple user accounts with three built-in roles.
• Company profile, departments, visit purposes, legal agreements, SMTP settings, and printer configurations are managed by administrators via configuration screens, not hard-coded in source code.
• Front-desk tablets boot into Kiosk Mode. Admin portal is accessed by administrators, receptionists and employees from their own computers.

2. Tech Stack

Layer	Solution
Frontend	Next.js App Router, TypeScript
Backend	Node.js, Next.js Server Actions / Route Handlers
Database	PostgreSQL
Data Access	Prisma ORM 7
PostgreSQL Driver	pg, @prisma/adapter-pg
Database Version Control	Prisma Migrate
Development Data Viewer	Prisma Studio (not used as production admin backend)

Recommendation: Store photo and signature files in controlled persistent storage; store only file references inside the database. Final storage and deployment architecture to be confirmed before implementation.

3. Visitor Check-in Flow

3.1 Tablet Home Screen

Displays company branding and the following entry points:

• Check In
• Check Out
• Print Badge — for visitors who completed mobile check-in to retrieve or reprint visitor badges.
• QR code for mobile registration, which opens this company’s visitor registration page.

Recommendation: Clear form and return to home page after submission or cancellation. Timeout to clear idle forms to prevent subsequent visitors from viewing prior visitor data. Web page cannot fully enforce OS-level Kiosk lock; true kiosk lockdown is handled via device configuration.

3.2 Step 1 — Your Details

Field	Rules
Full Name	Required
Company Name	Required for company visits; hidden for personal visits
Email	Required
Phone Number	Required
Vehicle Registration Number	Required only if visitor arrives by vehicle

Provide a yes/no toggle for arriving by car to conditionally show the license plate input. Click Next to proceed. Personal details and visit details are separated onto different pages.

3.3 Step 2 — Visit Details

• Person to Visit: Search by employee first name or last name to select the host employee.
• Only active, eligible employees are shown. Deactivated / terminated employee accounts are excluded from search results.
• Purpose of Visit: Dropdown selection. Options are maintained by the administrator.
• Message when host is not found: Person not found. Please ask reception for assistance.
• Reception staff may fill forms on behalf of visitors, but cannot sign or capture photos in place of the visitor.

Recommendation: Search results show both name and department to reduce confusion from duplicate names. Pending confirmation: Workflow when the host employee is not present in the employee list; workflow for reception-assisted form completion before visitor signature and photo capture.

3.4 Agreement & Photo Capture

• Display company-specific agreement template for visitor to provide digital signature.
• Use tablet front camera or visitor mobile camera to capture photo.
• Allow photo preview and retake before confirmation.
• Submit to finalize check-in and record submission timestamp.

Recommendation: Save immutable snapshot of the agreement text at signing time, visitor signature, and timestamp. Historical visit records preserve the agreement version active at check-in; later edits to the agreement template do not modify old records. Pending confirmation: Page layout and fallback handling when camera access fails.

3.5 Completion & Post Check-in Behaviour

A visit record is marked as checked-in once persisted successfully. Email delivery failure or print failure does not invalidate the check-in record and the visitor does not need to re-register.

• Confirmation email sent to visitor: includes company name, host employee, check-in timestamp.

• Notification email sent to host employee: visitor name, company, purpose of visit.

  Photos are not attached to emails.

• Tablet check-in triggers badge print according to printer settings. Mobile check-in prompts visitor to print badge at front desk tablet.

Message for successful mobile registration: Check-in complete. Please collect your visitor badge at the reception tablet.

Recommendation: Persist visit record and pending notification jobs in one database transaction. Background worker handles email delivery and logs delivery status. Duplicate submit clicks cannot create duplicate visit records. Email retry logic must not create new visit entries.

4. Badge Printing

• Uses Brother wireless label printer.
• Badge prints visitor full name and company name only; photos are not printed.
• Visitors who checked in via mobile go to tablet and click Print Badge. They enter email to retrieve their latest same-day check-in record.
• No re-registration required. Retry print on failure or request reception support.
• Error message: Unable to print your badge. Please try again or ask reception for assistance.

Recommendation: Show Personal for visitors selecting personal visit in the company name field. Print toggle, label dimensions and layout configurable in backend settings. Pending verification: Wireless LAN connectivity does not guarantee browser direct printing. After confirming Brother model and label size, validate SDK, print bridge service and tablet compatibility. Cloud application cannot directly access LAN printer by default. Printing logic is decoupled from check-in state; print job status stored separately. Do not mark print job complete unless successful paper output is confirmed.

5. Check Out

• Check-out is optional; visitors may leave without checking out.
• Visitor enters email, system retrieves the most recent visit record for that email (not limited to same day).
• If latest record is not checked out: update record with check-out timestamp.
• If latest record is already checked out: show Already checked out. Do not modify older historical records.
• Older unchecked-out records remain unchanged; system will not auto-fill departure times.
• Status label Not Checked Out does not guarantee visitor is still on-site.

Recommendation: Email matching is case-insensitive and trims leading/trailing whitespace. Public check-out page only loads data required for the operation; no full history list or photos exposed.

6. User Accounts & Permissions

Three roles share one backend portal; server-side permission validation enforced. Employee accounts may only view visit records where they are the host.

Function	Administrator	Receptionist	Employee
Access backend portal	Yes	Yes	Yes
Visit record scope	All records	All records	Only visits where they are host
Company configuration, user & employee management	Yes	No	No
Assist registration, manual check-out, badge reprint	Yes	Yes	No
Manual record deletion / cleanup	Yes	No	No
Excel export	Yes	Pending confirmation	Pending confirmation

Roles are confirmed. Permissions marked as recommended or pending will be finalized before implementation. Receptionist role is optional; administrator can perform reception duties if no receptionist account exists.

6.1 Initialization & Login

• First-time setup creates initial administrator account and password.
• Unified Email + Password login flow. Password reset via email.
• Administrators can update their own profile and password.

Recommendation: Initial setup entry point can run only once and protected by one-time deployment credential. Disable initialization entry after first setup to prevent unauthorized public account creation. Email change, password reset and SMTP changes require strong authentication.

6.2 Invitation & Employee Profile

1. Administrator enters email and assigns role (Receptionist or Employee)
2. System sends invitation email
3. Recipient accepts invite, sets password
4. Login and complete personal profile

• Employee fills First Name, Last Name, selects Department from configurable list.

  Recommendation: Employee only appears in host search after profile is fully completed.

• Invite and password reset links have expiry and one-time use only. Resend invitation supported.

• When employee is deactivated: cannot login, removed from host search, historical visit records retained.

7. Configuration Settings

Module	Contents
Company Settings	Company name, logo, address, timezone
Departments	Add, edit, deactivate departments
Visit Purposes	Add, edit, deactivate visit purpose options
Agreement Template	Custom visitor agreement text
SMTP Settings	SMTP Host, Port, TLS, Username, Password, Sender Name, Sender Email
Printer Settings	Print toggle, connection config, label size and layout

Recommendation: SMTP passwords stored encrypted, never returned in plaintext. Add Send Test Email function. Encryption key managed from environment variables separate from encrypted secrets. Clear warning shown when SMTP is not configured (invites and notifications cannot send). Store snapshot of configuration values alongside historical visit records.

8. Record Management & Excel Export

• Visitor records, photos and signatures retained indefinitely; no automatic expiry or deletion.
• Manual cleanup action available only for administrators.
• Backend portal includes visit list, detail view, date filters and search.
• Export to .xlsx: includes name, company / personal visit flag, email, phone, plate number, host employee, visit purpose, check-in and check-out timestamps. Photos are not embedded in Excel.
• Dashboard shows today’s check-in count and count of records marked Not Checked Out. Not Checked Out count is not equivalent to actual on-site visitor headcount.

Recommendation: Show preview count and confirmation prompt before deletion. Delete associated photos and signature files when purging records. Maintain audit log of destructive operations. Sanitize exported text fields to avoid Excel formula injection. Restore and recovery strategy pending confirmation.

9. Data Model Planning

The schema draft below is preliminary and cannot be used directly for production migration.

Entity	Purpose
User	Email, password hash, role, account status, first/last name, department
Department	Configurable departments, active status
Invitation / PasswordResetToken	Account invites and password reset tokens with expiry and consumption status
CompanySettings	Company profile and timezone
VisitPurpose	Configurable visit purpose options
AgreementVersion	Agreement content and version history (recommended)
VisitRecord	Snapshot of each visit, host reference, photo & signature file references, check-in / check-out timestamps
EmailJob / PrintJob	Background jobs for notifications and printing, status and failure reason (recommended)
OperationLog	Audit log for config changes, account changes, manual check-out, record cleanup

• Version 1 can store visitor details directly inside VisitRecord. A separate dedicated Visitor table for repeat visitors is optional and to be evaluated during schema design. Avoid merging records from different people based only on email.

• Remove VisitAppointment, appointment approval and appointment QR code relationships.

• Blacklist feature not confirmed and excluded from Version 1 scope.

• PostgreSQL JSONB field in Prisma defined as Json @db.JsonB.

• Prisma 7 connection URL defined in prisma.config.ts. Runtime client uses PostgreSQL adapter.

  Recommendation: Use Prisma 7 prisma-client generator with custom output path; reuse single Prisma client instance server-wide.

• All timestamps stored in UTC. Display and filtering use company local timezone.

• Attachments and secrets excluded from audit logs. Photo and signature downloads require permission validation.

10. Implementation Sequence & Acceptance Criteria

Phase 1: Foundation & Database

Setup Next.js project, Prisma 7 configuration, data models and initial migration. Implement initial admin setup, login and role-based access control. Finalize photo storage strategy, HTTPS and deployment architecture. Validate Brother printer integration early to discover hardware/network limitations before delivery.

Acceptance: Initial setup runs once only; role-based record access enforced; database and photo assets can be backed up and restored.

Phase 2: Configuration & Account Management

Implement company profile, departments, visit purposes, agreement template, SMTP configuration, user invitation workflow, profile completion and account deactivation.

Acceptance: Config changes do not require code deployment. Employees appear in host search only after completing profile. Deactivated users cannot login or be selected as host; old visit records preserved.

Phase 3: Check-in Core Flow

Build responsive kiosk and mobile forms, QR code entry, host search, digital signature, camera capture and visit record persistence.

Acceptance: Personal visit and conditional license plate fields work correctly. Host not found error handled. Repeated submission cannot create duplicate records. Signature and photo correctly linked to visit. Form cleared between visitors.

Phase 4: Notifications & Badge Printing

Implement SMTP email notifications, Brother print adapter, on-demand badge reprint for mobile check-in visitors, error messaging.

Acceptance: Email/print failure does not break check-in. Mobile visitors can reprint badge without re-registering. Badge label prints only name and company.

Phase 5: Check-out & Record Backend

Email-based check-out lookup, backend record browsing, detail view, Excel export and admin record cleanup.

Acceptance: Check-out only modifies latest record, no backfill of old entries. Excel export contains all required fields. Permission checks applied to export, file downloads and delete APIs.

Phase 6: On-site Trial & Handover

End-to-end testing on real tablets, mobile phones and Brother printer. Test failure scenarios: no network, camera permission denied, SMTP down, printer offline, duplicate submissions. Deliver configuration guide, startup instructions and backup/recovery documentation.

11. Open Items to Finalize Before Implementation

These do not block planning but need final decision without expanding product scope:

1. Brother printer model, label dimensions, on-site network topology and print integration approach.
2. Export permission for Receptionist and Employee roles; visibility rules for photos and signatures.
3. Reception assisted form workflow before visitor signature and photo capture; handling when host employee is missing.
4. Source of default agreement text (customer-provided or sample template). Versioned snapshot implementation for signed agreements.
5. Deployment strategy, persistent file storage, backup/restore and camera fallback handling.
6. Scope of record cleanup, confirmation workflow and linked file deletion rules.

12. Out of Scope for Version 1

Pre-visit appointments & approval workflows, multi-tenant shared platform, physical access control integration, facial recognition, SMS notifications, and unconfirmed visitor blacklist features.

This document also acts as Version 1 acceptance checklist. Partial implementation exists in local environment and Azure PostgreSQL deployment; on-site hardware validation and production deployment remain pending.

13. AI & Microsoft Copilot Integration (Future Phase, Not Version 1)

13.1 Project Objective

Expose secured, filtered visitor data via dedicated API endpoints, so Microsoft Copilot (or other LLM services such as OpenAI) can perform reporting, trend analysis, and detection of unusual/suspicious visitor activity. This phase is experimental research and development work and is excluded from Version 1 core visitor check-in functions.

13.2 Core Capabilities to Build

1. Secure External Integration API
   • Build authenticated, role-restricted API layer separate from internal admin backend.
   • API returns only pre-defined, sanitized dataset. PII redaction: mask emails, partial phone numbers; raw photos and signatures are never exposed.
   • API key authentication, IP allowlist and full audit logging for all API access events.
   • Support pagination and date range filtering; disable unlimited bulk data export.
   • Follow principle of minimum necessary access and PIPEDA compliance.
2. Controlled Access to Azure PostgreSQL Visitor Data
   • Design read-only PostgreSQL database views for AI consumption instead of granting direct database access.
   • Enforce row-level security: API queries can only retrieve permitted visit records.
   • Log every read operation originating from AI integrations for audit trail.
   • Biometric captured assets (photos, handwritten signatures) are never exposed to LLMs.
3. Copilot / LLM Query & Reporting Workflow
   • Microsoft Copilot consumes this API as a custom plugin or custom skill.
   • Example natural language questions supported:
     • “Show daily visitor volume trend for this month.”
     • “List visits with no check-out after business hours.”
     • “Count visits grouped by department and visit purpose.”
   • The LLM works in read-only mode and cannot write changes back to visitor database.
4. Detection of Unusual / Suspicious Visitor Activity This is the experimental R&D component:
   • Establish baseline patterns from historical visit logs: typical arrival times, repeat visitor frequency, after-hours visits.
   • Build pipeline combining static rules and lightweight statistical anomaly detection:
     • Multiple submissions from same name/email within a very short time window
     • Visits outside standard business hours
     • Long-duration visits without check-out recorded
     • Repeated unknown vehicle plate entries
   • Output anomaly alerts to administrator dashboard.
   • Important: The system flags potential unusual patterns only. It does not automatically classify visitors as threats and requires human administrator review.
5. Data Structuring & Privacy Controls for LLM Analysis
   • Sanitize dataset before sending to LLM; redact personal identifiable information where not required for analysis.
   • Test multiple schema designs to balance analytical usefulness and privacy protection.
   • Evaluate prompt engineering techniques to reduce LLM hallucination when summarizing visitor logs.
   • Validate which fields are safe to transmit and which must be excluded. Images and signatures are never sent to Copilot or OpenAI.

13.3 Technical Uncertainties (R&D Focus)

These unknowns define the experimental development nature:

1. How to design API schema so Copilot reliably interprets visitor domain data without custom model fine-tuning.
2. Threshold tuning for anomaly detection and reduction of false positives for unusual visitor behaviour.
3. How to maintain PIPEDA compliance while enabling AI analytics on visitor logs.
4. Performance impact of repeated natural language Copilot queries against Azure PostgreSQL.
5. Mitigation of prompt injection risks for the custom API plugin.

13.4 Scope Boundary

• AI integration work is outside Version 1 scope.
• Version 1 delivers core visitor registration, photo/signature capture, badge printing, email notifications and record management only.
• No LLM inference and no automatic threat detection active in Version 1 production release.
• All AI features are prototype research for future product releases.

13.5 Suggested Implementation Sequence

1. Build secured read-only API and full audit logging.
2. Create sanitized read-only PostgreSQL views and implement PII redaction testing.
3. Build lightweight anomaly detection prototype based on statistical rules.
4. Integrate API as custom plugin for Microsoft Copilot and test natural language reporting.
5. Evaluate output quality, tune detection thresholds, document privacy risks and limitations.
6. Finalize test report and evaluate whether to promote these capabilities into production.

---

Short paragraph for Question 9 form:

The project aims to extend the visitor-management application into an integrated monitoring and reporting platform. Planned R&D activities include:

1. Developing an API for secure external application integration.
2. Implementing and testing controlled, privacy-preserving access to visitor records stored in Azure PostgreSQL.
3. Researching integration with Microsoft Copilot to generate visitor reports and analytics.
4. Developing prototype logic to identify potentially unusual visitor activity.
5. Testing methods to structure and share visitor datasets for AI analysis without exposing unnecessary personal information.

These AI and anomaly detection functions are development objectives under investigation, and are not implemented in the initial production version of the visitor system.

---