Visitor
Registry
The Visitors module manages facility access through a structured check-in/check-out system, pre-registration for scheduled visits, and a security blacklist. Every entry is logged with visitor identity, patient relationship, purpose, and duration.
What is Visitor Management?
Visitor Management handles the complete facility access lifecycle: check-in (record visitor identity, CNIC, phone, patient linkage, purpose, ward), check-out (single or bulk with duration logging), pre-registration (schedule expected visits with planned arrival), blacklist management (restrict individuals from entry with reasoning), patient visit history (complete timeline of all visitors for a patient), and real-time stats (active visitors, today's volume, peak hours, average visit duration, ward distribution).
Each visitor record captures the check-in/check-out timestamps, ward location, relationship to patient, purpose of visit, and optionally a badge number, creating a complete access governance trail.
Why Does It Exist?
- → Ward security — Unrestricted visitor access compromises patient privacy and clinical safety
- → Patient privacy — Every visitor is logged with their relationship and purpose, creating an auditable access trail
- → Regulatory compliance — Healthcare facilities must maintain visitor logs for safety and legal compliance
- → Operational intelligence — Visitor volume and peak hour data helps optimize reception staffing and ward access policies
Check-In / Check-Out Workflow
Visitor Arrival
At the reception desk, the visitor provides their name, CNIC (optional, validated format XXXXX-XXXXXXX-X), phone, relationship to patient, and purpose. The receptionist optionally links them to an admitted patient via search.
Check-In Registration
The system logs the check-in with an automatic timestamp. The visitor receives a badge (optional badge number). Their record shows their ward, purpose, and expected duration. Status is set to 'checked_in'.
Active Monitoring
The visitor appears in the active visitors list. Reception staff can view all currently checked-in visitors grouped by ward, track duration, and manage extensions if needed.
Check-Out & Duration
At departure, the receptionist checks the visitor out. The system records the check-out timestamp and calculates the visit duration in minutes. The record is archived but remains visible in the visit history.
Pre-Registration & Blacklist
Pre-Register Visitor
Staff schedule a future visit by capturing the visitor's details and expected arrival time. The record is stored in 'pre_registered' status. Pre-registrations are visible in a dedicated queue for check-in processing.
Convert to Check-In
When the pre-registered visitor arrives, staff locate them in the queue and perform check-in. The pre-registration data populates the check-in form, and the status transitions from 'pre_registered' to 'checked_in'.
Blacklist Entry
Security or management can add individuals to the blacklist with their name, identifying number (CNIC), and reason. Blacklist entries can have an optional expiry date for time-bound restrictions.
Blacklist Enforcement
Reception staff check arriving visitors against the blacklist. Matched individuals are denied entry. Blacklist entries can be removed by authorized staff with audit logging.
Every Feature Explained
Visitor Check-In & Check-Out
Record visitor arrivals and departures with full identity and context.
Creates an auditable trail of who entered the facility, when, and why.
Check-in captures name, CNIC (validated format), phone, relationship, purpose, ward, badge number, and optional patient linkage. Check-out auto-records timestamp and calculates duration. Bulk checkout supports up to 500 IDs simultaneously.
Pre-Registration Queue
Schedule expected visits in advance with planned arrival times.
Streamlines reception workflows by batching visitor processing and managing expected volumes.
Pre-registration captures all check-in fields plus expectedArrival datetime. Records stay in 'pre_registered' status until check-in. Paginated view with expected arrival sorting. Pre-registrations are excluded from active visitor counts.
Security Blacklist
Restrict specific individuals from facility entry with reasoning.
Essential for patient protection, staff safety, and institutional security compliance.
Blacklist entries store name, optional ID number, reason (mandatory), addedBy user ID, and optional expiresAt date. Paginated list view. Deletion is authorized only for visitors:manage permission holders. Full audit logging on add and remove.
Patient Visit History
Complete timeline of all visitors for a specific patient.
Provides clinical staff with visibility into who has been visiting their patients.
History is retrieved by patientId via /history/:patientId endpoint. Returns patient details + chronologically-ordered visits (newest first). Each visit includes calculated durationMinutes. Table view shows visitor name, check-in, check-out, and duration.
Real-Time Stats & Analytics
Live dashboard of visitor activity with operational metrics.
Enables data-driven staffing decisions and capacity management at reception.
Stats endpoint computes: totalToday, currentlyActive, byWard distribution, avgVisitDurationMinutes (from today's completed visits), peakHourToday (hour with most check-ins today), totalThisWeek, totalThisMonth. Ward counts show where active visitors are currently located.
Visit Extension Management
Authorize extended visit durations beyond standard limits.
Accommodates special circumstances (e.g., critical patient status, family conferences) while maintaining audit.
The /extend endpoint accepts extendedUntil datetime and extensionReason. Both are stored on the visitor record alongside original check-in timestamp. Extensions are audited with deep change capture.
Visitor Search & Filters
Search visitors by name, CNIC, or phone across all records.
Quick retrieval for reception staff handling inquiries and security checks.
Search queries name, CNIC, and phone fields with case-insensitive partial matching (/search endpoint). Filters by check-in date range, status (inside/out/all), and patient. Dedicated /active endpoint returns only currently checked-in visitors.
Patient Linkage & Record Detail
Link visitors to specific patients and view the full record payload.
Clarifies the clinical relationship and provides context for security assessments.
Linked visitor records include patient name, MRN, and ID. Full record detail dialog shows the complete server payload including all timestamps, notes, and extension data. Patient names link to visit history for quick lookup.
Technical Architecture
| Field | Type | Institutional Role |
|---|---|---|
| visitor_id | UUID | Unique visitor log identifier. |
| visitor_name | VarChar(200) | Full name of the visitor. |
| visitor_cnic | VarChar(15) | National ID (format: XXXXX-XXXXXXX-X). |
| status | Enum | Pre-Registered, Checked In, Checked Out. |
| patient_id | UUID (nullable) | Linked patient reference (optional). |
Note: Sensitive fields use AES-256 field-level encryption where applicable.
Governance & Power
visitors:viewvisitors:checkinvisitors:checkoutvisitors:manageCNIC Validation
Visitor CNIC follows the Pakistan NADRA format XXXXX-XXXXXXX-X with regex validation. This ensures consistent identity records across all facility entry points.
Checked-In Protection
Visitors with active check-in status cannot be deleted, they must be checked out first. This prevents loss of active visitor tracking data.
Bulk Operations
The bulk checkout endpoint supports up to 500 concurrent check-outs with individual result tracking per ID. Each checkout is independently audited with before/after snapshots.