# yuvaraj4-s/visitor_management_system architecture

> Architecture diagram of the GitHub repository yuvaraj4-s/visitor_management_system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yuvaraj4-s/visitor_management_system
- Repository: https://github.com/yuvaraj4-s/visitor_management_system

## Overview

#### 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`

Main entry points: [`visitormanagement/visitor_management/doctype/visitor_pass/visitor_pass.py`](https://github.com/yuvaraj4-s/visitor_management_system/blob/main/visitormanagement/visitor_management/doctype/visitor_pass/visitor_pass.py) (Visitor Pass), [`visitormanagement/visitor_management/api/visitor_gate.py`](https://github.com/yuvaraj4-s/visitor_management_system/blob/main/visitormanagement/visitor_management/api/visitor_gate.py) (QR gate operations), [`visitormanagement/visitor_management/doctype/security_log/security_log.py`](https://github.com/yuvaraj4-s/visitor_management_system/blob/main/visitormanagement/visitor_management/doctype/security_log/security_log.py) (Security Log), [`visitormanagement/hooks.py`](https://github.com/yuvaraj4-s/visitor_management_system/blob/main/visitormanagement/hooks.py) (App hooks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Frappe Runtime"]
  node_hooks["App hooks<br/>Frappe registration<br/>[hooks.py]"]
  node_frappe_db[("MariaDB DocType data<br/>persistence")]
  node_dependencies["ERPNext &amp; HRMS<br/>dependent apps"]
end

subgraph group_visitor["Visitor Lifecycle"]
  node_invitation["Visitor Invitation<br/>DocType controller"]
  node_preregistration["Public pre-registration<br/>web form and page"]
  node_visitor_pass["Visitor Pass<br/>DocType controller<br/>[visitor_pass.py]"]
  node_workflow_fixtures["Roles &amp; approval workflows<br/>migration fixtures<br/>[workflow.json]"]
  node_policy["Blacklist &amp; lifecycle policy<br/>domain validation"]
end

subgraph group_operations["Operations"]
  node_gate_api["QR gate operations<br/>Frappe API<br/>[visitor_gate.py]"]
  node_security_log["Security Log<br/>immutable event DocType<br/>[security_log.py]"]
  node_contact_trace["Contact Trace Record<br/>DocType controller"]
  node_hospitality["Hospitality Request<br/>service workflow"]
  node_room_booking["Conference Room Booking<br/>service workflow"]
  node_notifications["Notifications"]
  node_scheduled_tasks["Scheduled lifecycle tasks<br/>background tasks<br/>[tasks.py]"]
end

subgraph group_evolution["Upgrade &amp; Presentation"]
  node_read_models["Desk reports &amp; badge<br/>read-model UI<br/>[active_visitors.py]"]
  node_patches["Schema and data patches<br/>Frappe migration<br/>[patches.txt]"]
end

node_hooks -->|"schedules"| node_scheduled_tasks
node_hooks -->|"runs on"| node_frappe_db
node_dependencies -->|"shares"| node_frappe_db
node_invitation -->|"issues token for"| node_preregistration
node_preregistration -->|"creates or updates"| node_visitor_pass
node_visitor_pass -->|"uses approval states"| node_workflow_fixtures
node_visitor_pass -->|"validates against"| node_policy
node_visitor_pass -->|"projects selected services"| node_hospitality
node_visitor_pass -->|"projects selected rooms"| node_room_booking
node_visitor_pass -->|"triggers alerts"| node_notifications
node_gate_api -->|"looks up and transitions"| node_visitor_pass
node_gate_api -->|"rechecks blacklist"| node_policy
node_gate_api -->|"creates"| node_security_log
node_security_log -->|"opens or closes"| node_contact_trace
node_visitor_pass -->|"persists"| node_frappe_db
node_security_log -->|"persists audit trail"| node_frappe_db
node_hospitality -->|"persists"| node_frappe_db
node_room_booking -->|"persists"| node_frappe_db
node_read_models -->|"reads"| node_frappe_db
node_scheduled_tasks -->|"processes pending passes"| node_visitor_pass
node_patches -->|"evolves schema and data"| node_frappe_db
node_patches -->|"synchronizes"| node_workflow_fixtures

click node_hooks "https://github.com/yuvaraj4-s/visitor_management_system/blob/main/visitormanagement/hooks.py"
click node_invitation "https://github.com/yuvaraj4-s/visitor_management_system/blob/main/visitormanagement/visitor_management/doctype/visitor_invitation/visitor_invitation.py"
click node_preregistration "https://github.com/yuvaraj4-s/visitor_management_system/blob/main/visitormanagement/visitor_management/web_form/visitor_pre_registration_form/visitor_pre_registration_form.py"
click node_visitor_pass "https://github.com/yuvaraj4-s/visitor_management_system/blob/main/visitormanagement/visitor_management/doctype/visitor_pass/visitor_pass.py"
click node_workflow_fixtures "https://github.com/yuvaraj4-s/visitor_management_system/blob/main/visitormanagement/fixtures/workflow.json"
click node_policy "https://github.com/yuvaraj4-s/visitor_management_system/blob/main/visitormanagement/visitor_management/doctype/visitor_blacklist/visitor_blacklist.py"
click node_gate_api "https://github.com/yuvaraj4-s/visitor_management_system/blob/main/visitormanagement/visitor_management/api/visitor_gate.py"
click node_security_log "https://github.com/yuvaraj4-s/visitor_management_system/blob/main/visitormanagement/visitor_management/doctype/security_log/security_log.py"
click node_contact_trace "https://github.com/yuvaraj4-s/visitor_management_system/blob/main/visitormanagement/visitor_management/doctype/contact_trace_record/contact_trace_record.py"
click node_hospitality "https://github.com/yuvaraj4-s/visitor_management_system/blob/main/visitormanagement/visitor_management/doctype/hospitality_request/hospitality_request.py"
click node_room_booking "https://github.com/yuvaraj4-s/visitor_management_system/blob/main/visitormanagement/conference_room/doctype/conference_room_booking/conference_room_booking.py"
click node_notifications "https://github.com/yuvaraj4-s/visitor_management_system/blob/main/visitormanagement/visitor_management/notification/gate_security_alert/gate_security_alert.py"
click node_scheduled_tasks "https://github.com/yuvaraj4-s/visitor_management_system/blob/main/visitormanagement/visitor_management/tasks.py"
click node_read_models "https://github.com/yuvaraj4-s/visitor_management_system/blob/main/visitormanagement/visitor_management/report/active_visitors/active_visitors.py"
click node_patches "https://github.com/yuvaraj4-s/visitor_management_system/blob/main/visitormanagement/patches.txt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_hooks,node_frappe_db,node_dependencies toneBlue
class node_invitation,node_preregistration,node_visitor_pass,node_workflow_fixtures,node_policy toneAmber
class node_gate_api,node_security_log,node_contact_trace,node_hospitality,node_room_booking,node_notifications,node_scheduled_tasks toneMint
class node_read_models,node_patches toneRose
```

## Components

### Frappe Runtime

- [App hooks](https://github.com/yuvaraj4-s/visitor_management_system/blob/main/visitormanagement/hooks.py): Frappe registration · Registers runtime integration and scheduled behavior. · `visitormanagement/hooks.py`
- **MariaDB DocType data**: persistence · Frappe-managed persistent records, permissions, and workflow state.
- **ERPNext & HRMS**: dependent apps · Provide dependent doctypes and services.

### Visitor Lifecycle

- [Visitor Invitation](https://github.com/yuvaraj4-s/visitor_management_system/blob/main/visitormanagement/visitor_management/doctype/visitor_invitation/visitor_invitation.py): DocType controller · Host-created invitation and token source. · `visitormanagement/visitor_management/doctype/visitor_invitation/visitor_invitation.py`
- [Public pre-registration](https://github.com/yuvaraj4-s/visitor_management_system/blob/main/visitormanagement/visitor_management/web_form/visitor_pre_registration_form/visitor_pre_registration_form.py): web form and page · Token-driven unauthenticated visitor intake. · `visitormanagement/visitor_management/web_form/visitor_pre_registration_form/visitor_pre_registration_form.py`
- [Visitor Pass](https://github.com/yuvaraj4-s/visitor_management_system/blob/main/visitormanagement/visitor_management/doctype/visitor_pass/visitor_pass.py): DocType controller · Approval and access orchestration boundary. · `visitormanagement/visitor_management/doctype/visitor_pass/visitor_pass.py`
- [Roles & approval workflows](https://github.com/yuvaraj4-s/visitor_management_system/blob/main/visitormanagement/fixtures/workflow.json): migration fixtures · Preloaded roles, states, and transitions. · `visitormanagement/fixtures/workflow.json`
- [Blacklist & lifecycle policy](https://github.com/yuvaraj4-s/visitor_management_system/blob/main/visitormanagement/visitor_management/doctype/visitor_blacklist/visitor_blacklist.py): domain validation · Matches blacklist records and enforces lifecycle rules. · `visitormanagement/visitor_management/doctype/visitor_blacklist/visitor_blacklist.py`

### Operations

- [QR gate operations](https://github.com/yuvaraj4-s/visitor_management_system/blob/main/visitormanagement/visitor_management/api/visitor_gate.py): Frappe API · Looks up passes and records verified entry or exit. · `visitormanagement/visitor_management/api/visitor_gate.py`
- [Security Log](https://github.com/yuvaraj4-s/visitor_management_system/blob/main/visitormanagement/visitor_management/doctype/security_log/security_log.py): immutable event DocType · Preserves gate audit events and confirmations. · `visitormanagement/visitor_management/doctype/security_log/security_log.py`
- [Contact Trace Record](https://github.com/yuvaraj4-s/visitor_management_system/blob/main/visitormanagement/visitor_management/doctype/contact_trace_record/contact_trace_record.py): DocType controller · Opened and closed from gate lifecycle events. · `visitormanagement/visitor_management/doctype/contact_trace_record/contact_trace_record.py`
- [Hospitality Request](https://github.com/yuvaraj4-s/visitor_management_system/blob/main/visitormanagement/visitor_management/doctype/hospitality_request/hospitality_request.py): service workflow · Independently approved hospitality execution. · `visitormanagement/visitor_management/doctype/hospitality_request/hospitality_request.py`
- [Conference Room Booking](https://github.com/yuvaraj4-s/visitor_management_system/blob/main/visitormanagement/conference_room/doctype/conference_room_booking/conference_room_booking.py): service workflow · Validates capacity and operating windows. · `visitormanagement/conference_room/doctype/conference_room_booking/conference_room_booking.py`
- [Notifications](https://github.com/yuvaraj4-s/visitor_management_system/blob/main/visitormanagement/visitor_management/notification/gate_security_alert/gate_security_alert.py): Frappe notifications · Configured email alerts for approval, gate, VIP, and services. · `visitormanagement/visitor_management/notification/gate_security_alert/gate_security_alert.py`
- [Scheduled lifecycle tasks](https://github.com/yuvaraj4-s/visitor_management_system/blob/main/visitormanagement/visitor_management/tasks.py): background tasks · Handles pending-pass and scheduled lifecycle work. · `visitormanagement/visitor_management/tasks.py`

### Upgrade & Presentation

- [Desk reports & badge](https://github.com/yuvaraj4-s/visitor_management_system/blob/main/visitormanagement/visitor_management/report/active_visitors/active_visitors.py): read-model UI · Reports, dashboards, calendars, and print projections. · `visitormanagement/visitor_management/report/active_visitors/active_visitors.py`
- [Schema and data patches](https://github.com/yuvaraj4-s/visitor_management_system/blob/main/visitormanagement/patches.txt): Frappe migration · Post-sync backfills and fixture synchronization define upgrades. · `visitormanagement/patches.txt`

## Connections

- App hooks → Scheduled lifecycle tasks: schedules
- App hooks → MariaDB DocType data: runs on
- ERPNext & HRMS → MariaDB DocType data: shares
- Visitor Invitation → Public pre-registration: issues token for
- Public pre-registration → Visitor Pass: creates or updates
- Visitor Pass → Roles & approval workflows: uses approval states
- Visitor Pass → Blacklist & lifecycle policy: validates against
- Visitor Pass → Hospitality Request: projects selected services
- Visitor Pass → Conference Room Booking: projects selected rooms
- Visitor Pass → Notifications: triggers alerts
- QR gate operations → Visitor Pass: looks up and transitions
- QR gate operations → Blacklist & lifecycle policy: rechecks blacklist
- QR gate operations → Security Log: creates
- Security Log → Contact Trace Record: opens or closes
- Visitor Pass → MariaDB DocType data: persists
- Security Log → MariaDB DocType data: persists audit trail
- Hospitality Request → MariaDB DocType data: persists
- Conference Room Booking → MariaDB DocType data: persists
- Desk reports & badge → MariaDB DocType data: reads
- Scheduled lifecycle tasks → Visitor Pass: processes pending passes
- Schema and data patches → MariaDB DocType data: evolves schema and data
- Schema and data patches → Roles & approval workflows: synchronizes