# arcrek/vms architecture

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

- Interactive diagram: https://gitdiagram.com/arcrek/vms
- Repository: https://github.com/arcrek/vms

## Overview

Acme Corp VMS manages visitor registration, physical check-in/out, role-restricted staff surfaces, and digital passes. The main workflow is host pre-registration or kiosk/mobile walk-in, followed by reception verification and badge issuance; SSE updates the roster and arrival alerts. The app also provides rotating kiosk QR handoff, photo/NDA capture, pass verification, and multi-actor RBAC. Backend calls are shown where excerpts establish them; broader surface workflows follow README documentation, since several UI and API excerpts are partial.

Main entry points: [`src/context/VMSContext.jsx`](https://github.com/arcrek/vms/blob/main/src/context/VMSContext.jsx) (Shared VMS State), [`src/components/kiosk/KioskWizard.jsx`](https://github.com/arcrek/vms/blob/main/src/components/kiosk/KioskWizard.jsx) (Check-In Wizard), [`src/components/reception/ReceptionConsole.jsx`](https://github.com/arcrek/vms/blob/main/src/components/reception/ReceptionConsole.jsx) (Reception Console), [`src/components/mobile/MobileCheckin.jsx`](https://github.com/arcrek/vms/blob/main/src/components/mobile/MobileCheckin.jsx) (Mobile Check-In)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Identity and Access"]
  node_auth["Actor Authentication<br/>[AuthContext.jsx]"]
  node_access_guard["Surface RBAC<br/>[RBACGuard.jsx]"]
end

subgraph group_registration["Visitor Registration"]
  node_host_portal["Host Portal<br/>[HostPortal.jsx]"]
  node_pre_register["Pre-Registration"]
  node_kiosk["Entrance Kiosk<br/>[KioskView.jsx]"]
  node_kiosk_wizard["Check-In Wizard<br/>[KioskWizard.jsx]"]
  node_camera["Photo Capture<br/>[CameraCapture.jsx]"]
  node_signature["NDA Signature<br/>[SignaturePad.jsx]"]
  node_rolling_qr["Rolling QR<br/>[RollingQR.jsx]"]
  node_mobile_checkin["Mobile Check-In<br/>[MobileCheckin.jsx]"]
end

subgraph group_operations["Reception Operations"]
  node_reception["Reception Console"]
  node_visitor_table["Visitor Roster<br/>[VisitorTable.jsx]"]
  node_scanner["Code Scanner"]
  node_visitor_detail["Visit Verification"]
  node_badge["Printable Badge<br/>[BadgeModal.jsx]"]
end

subgraph group_platform["Visit Platform"]
  node_api["REST API<br/>[api.js]"]
  node_visit_service["Visit Lifecycle<br/>[visitService.js]"]
  node_database[("SQLite Store<br/>[index.js]")]
  node_token_service["QR Token Service<br/>[tokenService.js]"]
end

subgraph group_pass["Pass and Updates"]
  node_live_events["SSE Broadcast<br/>[sseService.js]"]
  node_vms_context["Shared VMS State<br/>[VMSContext.jsx]"]
  node_sse_hook["SSE Client<br/>[useSSE.js]"]
  node_mobile_pass["Digital Pass<br/>[MobilePass.jsx]"]
end

node_host_actor(("Host Sponsor"))
node_visitor_actor(("Visitor"))
node_guard_actor(("Reception Guard"))

node_host_actor -->|"uses"| node_host_portal
node_visitor_actor -->|"checks in"| node_kiosk
node_visitor_actor -->|"checks in"| node_mobile_checkin
node_guard_actor -->|"verifies visitors"| node_reception
node_auth -->|"supplies identity"| node_access_guard
node_host_portal -->|"opens"| node_pre_register
node_pre_register -->|"creates visit"| node_vms_context
node_kiosk -->|"starts registration"| node_kiosk_wizard
node_kiosk_wizard -->|"captures photo"| node_camera
node_kiosk_wizard -->|"collects signature"| node_signature
node_kiosk -->|"offers handoff"| node_rolling_qr
node_rolling_qr -->|"opens check-in"| node_mobile_checkin
node_mobile_checkin -->|"collects signature"| node_signature
node_kiosk_wizard -->|"submits walk-in"| node_vms_context
node_mobile_checkin -->|"submits walk-in"| node_vms_context
node_reception -->|"renders roster"| node_visitor_table
node_reception -->|"uses scanner"| node_scanner
node_reception -->|"opens details"| node_visitor_detail
node_visitor_detail -->|"checks in visitor"| node_vms_context
node_reception -->|"opens print dialog"| node_badge
node_vms_context -->|"requests visit actions"| node_api
node_api -->|"routes lifecycle calls"| node_visit_service
node_visit_service -->|"reads and writes"| node_database
node_visit_service -->|"broadcasts changes"| node_live_events
node_api -->|"requests QR token"| node_token_service
node_vms_context -->|"subscribes to events"| node_sse_hook
node_sse_hook -->|"receives event stream"| node_live_events
node_live_events -->|"refreshes live state"| node_vms_context
node_vms_context -->|"provides pass data"| node_mobile_pass
node_host_portal -->|"opens pass link"| node_mobile_pass
node_kiosk_wizard -->|"issues pass"| node_mobile_pass

click node_auth "https://github.com/arcrek/vms/blob/main/src/context/AuthContext.jsx"
click node_access_guard "https://github.com/arcrek/vms/blob/main/src/components/auth/RBACGuard.jsx"
click node_host_portal "https://github.com/arcrek/vms/blob/main/src/components/host/HostPortal.jsx"
click node_pre_register "https://github.com/arcrek/vms/blob/main/src/components/host/PreRegisterModal.jsx"
click node_kiosk "https://github.com/arcrek/vms/blob/main/src/components/kiosk/KioskView.jsx"
click node_kiosk_wizard "https://github.com/arcrek/vms/blob/main/src/components/kiosk/KioskWizard.jsx"
click node_camera "https://github.com/arcrek/vms/blob/main/src/components/kiosk/CameraCapture.jsx"
click node_signature "https://github.com/arcrek/vms/blob/main/src/components/kiosk/SignaturePad.jsx"
click node_rolling_qr "https://github.com/arcrek/vms/blob/main/src/components/kiosk/RollingQR.jsx"
click node_mobile_checkin "https://github.com/arcrek/vms/blob/main/src/components/mobile/MobileCheckin.jsx"
click node_reception "https://github.com/arcrek/vms/blob/main/src/components/reception/ReceptionConsole.jsx"
click node_visitor_table "https://github.com/arcrek/vms/blob/main/src/components/reception/VisitorTable.jsx"
click node_scanner "https://github.com/arcrek/vms/blob/main/src/components/reception/ScannerListener.jsx"
click node_visitor_detail "https://github.com/arcrek/vms/blob/main/src/components/reception/VisitorDetailModal.jsx"
click node_badge "https://github.com/arcrek/vms/blob/main/src/components/badge/BadgeModal.jsx"
click node_api "https://github.com/arcrek/vms/blob/main/server/routes/api.js"
click node_visit_service "https://github.com/arcrek/vms/blob/main/server/services/visitService.js"
click node_database "https://github.com/arcrek/vms/blob/main/server/db/index.js"
click node_token_service "https://github.com/arcrek/vms/blob/main/server/services/tokenService.js"
click node_live_events "https://github.com/arcrek/vms/blob/main/server/services/sseService.js"
click node_vms_context "https://github.com/arcrek/vms/blob/main/src/context/VMSContext.jsx"
click node_sse_hook "https://github.com/arcrek/vms/blob/main/src/hooks/useSSE.js"
click node_mobile_pass "https://github.com/arcrek/vms/blob/main/src/components/pass/MobilePass.jsx"

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_auth,node_access_guard toneBlue
class node_host_portal,node_pre_register,node_kiosk,node_kiosk_wizard,node_camera,node_signature,node_rolling_qr,node_mobile_checkin toneAmber
class node_reception,node_visitor_table,node_scanner,node_visitor_detail,node_badge toneMint
class node_api,node_visit_service,node_database,node_token_service toneRose
class node_live_events,node_vms_context,node_sse_hook,node_mobile_pass,node_host_actor,node_visitor_actor,node_guard_actor toneIndigo
```

## Components

### Identity and Access

- [Actor Authentication](https://github.com/arcrek/vms/blob/main/src/context/AuthContext.jsx): `src/context/AuthContext.jsx`
- [Surface RBAC](https://github.com/arcrek/vms/blob/main/src/components/auth/RBACGuard.jsx): `src/components/auth/RBACGuard.jsx`

### Visitor Registration

- [Host Portal](https://github.com/arcrek/vms/blob/main/src/components/host/HostPortal.jsx): `src/components/host/HostPortal.jsx`
- [Pre-Registration](https://github.com/arcrek/vms/blob/main/src/components/host/PreRegisterModal.jsx): `src/components/host/PreRegisterModal.jsx`
- [Entrance Kiosk](https://github.com/arcrek/vms/blob/main/src/components/kiosk/KioskView.jsx): `src/components/kiosk/KioskView.jsx`
- [Check-In Wizard](https://github.com/arcrek/vms/blob/main/src/components/kiosk/KioskWizard.jsx): `src/components/kiosk/KioskWizard.jsx`
- [Photo Capture](https://github.com/arcrek/vms/blob/main/src/components/kiosk/CameraCapture.jsx): `src/components/kiosk/CameraCapture.jsx`
- [NDA Signature](https://github.com/arcrek/vms/blob/main/src/components/kiosk/SignaturePad.jsx): `src/components/kiosk/SignaturePad.jsx`
- [Rolling QR](https://github.com/arcrek/vms/blob/main/src/components/kiosk/RollingQR.jsx): `src/components/kiosk/RollingQR.jsx`
- [Mobile Check-In](https://github.com/arcrek/vms/blob/main/src/components/mobile/MobileCheckin.jsx): `src/components/mobile/MobileCheckin.jsx`

### Reception Operations

- [Reception Console](https://github.com/arcrek/vms/blob/main/src/components/reception/ReceptionConsole.jsx): `src/components/reception/ReceptionConsole.jsx`
- [Visitor Roster](https://github.com/arcrek/vms/blob/main/src/components/reception/VisitorTable.jsx): `src/components/reception/VisitorTable.jsx`
- [Code Scanner](https://github.com/arcrek/vms/blob/main/src/components/reception/ScannerListener.jsx): `src/components/reception/ScannerListener.jsx`
- [Visit Verification](https://github.com/arcrek/vms/blob/main/src/components/reception/VisitorDetailModal.jsx): `src/components/reception/VisitorDetailModal.jsx`
- [Printable Badge](https://github.com/arcrek/vms/blob/main/src/components/badge/BadgeModal.jsx): `src/components/badge/BadgeModal.jsx`

### Visit Platform

- [REST API](https://github.com/arcrek/vms/blob/main/server/routes/api.js): `server/routes/api.js`
- [Visit Lifecycle](https://github.com/arcrek/vms/blob/main/server/services/visitService.js): `server/services/visitService.js`
- [SQLite Store](https://github.com/arcrek/vms/blob/main/server/db/index.js): `server/db/index.js`
- [QR Token Service](https://github.com/arcrek/vms/blob/main/server/services/tokenService.js): `server/services/tokenService.js`

### Pass and Updates

- [SSE Broadcast](https://github.com/arcrek/vms/blob/main/server/services/sseService.js): `server/services/sseService.js`
- [Shared VMS State](https://github.com/arcrek/vms/blob/main/src/context/VMSContext.jsx): `src/context/VMSContext.jsx`
- [SSE Client](https://github.com/arcrek/vms/blob/main/src/hooks/useSSE.js): `src/hooks/useSSE.js`
- [Digital Pass](https://github.com/arcrek/vms/blob/main/src/components/pass/MobilePass.jsx): `src/components/pass/MobilePass.jsx`

### Other components

- **Host Sponsor**
- **Visitor**
- **Reception Guard**

## Connections

- Host Sponsor → Host Portal: uses (evidence: `README.md`)
- Visitor → Entrance Kiosk: checks in (evidence: `README.md`)
- Visitor → Mobile Check-In: checks in (evidence: `README.md`)
- Reception Guard → Reception Console: verifies visitors (evidence: `README.md`)
- Actor Authentication → Surface RBAC: supplies identity (evidence: `src/App.jsx`)
- Host Portal → Pre-Registration: opens (evidence: `src/components/host/HostPortal.jsx`)
- Pre-Registration → Shared VMS State: creates visit (evidence: `README.md`)
- Entrance Kiosk → Check-In Wizard: starts registration (evidence: `src/components/kiosk/KioskView.jsx`)
- Check-In Wizard → Photo Capture: captures photo (evidence: `src/components/kiosk/KioskWizard.jsx`)
- Check-In Wizard → NDA Signature: collects signature (evidence: `src/components/kiosk/KioskWizard.jsx`)
- Entrance Kiosk → Rolling QR: offers handoff (evidence: `src/components/kiosk/KioskView.jsx`)
- Rolling QR → Mobile Check-In: opens check-in (evidence: `README.md`)
- Mobile Check-In → NDA Signature: collects signature (evidence: `src/components/mobile/MobileCheckin.jsx`)
- Check-In Wizard → Shared VMS State: submits walk-in (evidence: `README.md`)
- Mobile Check-In → Shared VMS State: submits walk-in (evidence: `README.md`)
- Reception Console → Visitor Roster: renders roster (evidence: `src/components/reception/ReceptionConsole.jsx`)
- Reception Console → Code Scanner: uses scanner (evidence: `src/components/reception/ReceptionConsole.jsx`)
- Reception Console → Visit Verification: opens details (evidence: `src/components/reception/ReceptionConsole.jsx`)
- Visit Verification → Shared VMS State: checks in visitor (evidence: `README.md`)
- Reception Console → Printable Badge: opens print dialog (evidence: `src/App.jsx`)
- Shared VMS State → REST API: requests visit actions (evidence: `README.md`)
- REST API → Visit Lifecycle: routes lifecycle calls (evidence: `server/routes/api.js`)
- Visit Lifecycle → SQLite Store: reads and writes (evidence: `server/services/visitService.js`)
- Visit Lifecycle → SSE Broadcast: broadcasts changes (evidence: `server/services/visitService.js`)
- REST API → QR Token Service: requests QR token (evidence: `server/routes/api.js`)
- Shared VMS State → SSE Client: subscribes to events (evidence: `src/context/VMSContext.jsx`)
- SSE Client → SSE Broadcast: receives event stream (evidence: `README.md`)
- SSE Broadcast → Shared VMS State: refreshes live state (evidence: `src/context/VMSContext.jsx`)
- Shared VMS State → Digital Pass: provides pass data (evidence: `README.md`)
- Host Portal → Digital Pass: opens pass link (evidence: `src/App.jsx`)
- Check-In Wizard → Digital Pass: issues pass
