yuvaraj4-s/visitor_management_system

Purpose and runtime

This is a Frappe/ERPNext v15 application for visitor lifecycle management: invitation/pre-registration, pass approval, QR gate events, identity/blacklist checks, hospitality, room booking, and audit reporting. It runs as a Python Frappe app backed by MariaDB; ERPNext and HRMS provide dependent doctypes/services. App registration and runtime hooks enter through visitormanagement/hooks.py, with modules declared in visitormanagement/modules.txt.

Domain model and workflow boundary

Frappe DocType JSON defines persistent schema, Desk forms, permissions, and workflow-facing state; Python controllers enforce server-side lifecycle rules, while JS supplies Desk interactions. Core records are Visitor Pass, Invitation, Security Log, Blacklist, Contact Trace, and immutable event history:

• visitormanagement/visitor_management/doctype/visitor_pass/visitor_pass.py

• visitormanagement/visitor_management/doctype/security_log/security_log.py

• visitormanagement/visitor_management/doctype/visitor_invitation/visitor_invitation.py

Preloaded roles and approval state machines are migration fixtures, rather than custom workflow code:

• visitormanagement/fixtures/workflow.json

• visitormanagement/fixtures/workflow_transition.json

• visitormanagement/fixtures/role.json

Pre-visit intake and pass orchestration

Hosts create invitations or reception creates passes. Invitation tokens drive the public pre-registration surface; submitted data creates/updates a Visitor Pass, whose visitor type selects an approval lane. Pass approval is the orchestration boundary that produces QR-ready access and conditional downstream services.

• visitormanagement/visitor_management/web_form/visitor_pre_registration_form/visitor_pre_registration_form.py

• visitormanagement/www/visitor_pre_registration.py

• visitormanagement/visitor_management/doctype/visitor_pass/visitor_pass.py

Portal/web entry behavior is separated from authenticated Desk UI, with client behavior in visitormanagement/visitor_management/web_form/visitor_pre_registration_form/visitor_pre_registration_form.js.

Gate security and audit lifecycle

Gate operations create Security Log events from a QR/pass lookup, require live-photo and identity confirmations for entry/exit, recheck active blacklist status, and transition the pass between checked-in and checked-out. These events open/close contact-tracing records and preserve immutable security/event audit trails.

• visitormanagement/visitor_management/api/visitor_gate.py

• visitormanagement/visitor_management/doctype/security_log/security_log.py

• visitormanagement/visitor_management/doctype/contact_trace_record/contact_trace_record.py

Blacklist matching and policy validation sit in the visitor domain:

• visitormanagement/visitor_management/doctype/visitor_blacklist/visitor_blacklist.py

• visitormanagement/visitor_management/validators.py

• visitormanagement/visitor_management/lifecycle.py

Hospitality and room-booking projections

Approved passes with hospitality selections create Hospitality Requests; selected rooms create Conference Room Bookings. These are separate approval workflows, allowing operational teams to execute services independently from security access. Booking validates room capacity and operating windows.

• visitormanagement/visitor_management/doctype/hospitality_request/hospitality_request.py

• visitormanagement/conference_room/doctype/conference_room_booking/conference_room_booking.py

• visitormanagement/conference_room/doctype/conference_room/conference_room.py

Notifications, scheduling, and presentation

Frappe notifications deliver approval, host, VIP, gate-security, and service alerts through configured site email. Background tasks handle scheduled lifecycle work such as pending-pass handling.

• visitormanagement/visitor_management/tasks.py

• visitormanagement/visitor_management/notification/gate_security_alert/gate_security_alert.py

• visitormanagement/visitor_management/notification/vms_approval_email/vms_approval_email.py

Desk workspaces, dashboards, reports, number cards, calendars, and print formats are read-model/UI projections over the same DocType data:

• visitormanagement/visitor_management/report/active_visitors/active_visitors.py

• visitormanagement/conference_room/report/room_utilization/room_utilization.py

• visitormanagement/visitor_management/print_format/visitor_badge/visitor_badge.html

Installation evolution

Schema/data evolution is performed through Frappe patches listed in visitormanagement/patches.txt; post-model-sync patches backfill data, synchronize workflow/notification fixtures, and update roles/settings. This is the principal upgrade boundary.

• visitormanagement/patches.txt

• visitormanagement/patches/post_model_sync/sync_visitor_pass_workflow.py

• visitormanagement/patches/post_model_sync/backfill_visitor_summary.py