ca-grow-ops-manager/specs/009_escort_handoff_mode.md

Visitor Kiosk - Escort Handoff Mode Specification

Overview

This document specifies the "Escort Handoff Mode" for the mobile visitor kiosk. In this mode, a staff member hands their tablet/phone to the visitor for registration, but the digital badge remains on the staff device rather than transferring to the visitor's personal phone.

Use Case

In controlled facilities, staff may prefer to:

1. Hand their mobile device to a visitor for self-registration
2. Keep the visitor badge displayed on the staff device
3. Maintain "escort mode" where staff carries the badge throughout the visit

User Flow

1. Staff Initiates Handoff

Staff Device (Kiosk Mode)
├── Staff taps "Register Visitor"
├── Device locks into "Handoff Mode"
│   └── Shows: "Please hand device to visitor"
└── Optional: Staff enters their ID as escort

2. Visitor Self-Registration (On Staff Device)

Visitor receives device
├── Fills in:
│   ├── Name (required)
│   ├── Company
│   ├── Purpose (required)
│   └── Type (Visitor, Contractor, etc.)
├── Takes selfie using front camera
├── Accepts NDA (checkbox)
└── Taps "Complete Registration"

3. Badge Display (Stays on Staff Device)

After successful check-in:
├── Badge displays on staff's device
├── Shows: "Return device to staff" overlay
├── QR code for security scan
├── Staff name shown as "Escort"
└── NO auto-redirect to visitor's phone

Key Differences from Standard Mode

Feature	Standard Kiosk	Escort Handoff
Badge Location	Visitor's phone (via QR scan)	Staff's device
Escort Assignment	Optional	Automatic (logged-in staff)
Device Return	Not applicable	Required step
Badge Portability	On visitor's device	Carried by escort

Technical Implementation

1. Mode Detection

type KioskMode = 
  | 'standard'      // Fixed tablet kiosk
  | 'escort-handoff' // Mobile escort mode
  | 'self-service';  // Visitor's own device

interface HandoffSession {
  escortId: string;      // Staff user ID
  escortName: string;    // For display
  startedAt: Date;
  deviceId?: string;     // For audit
}

2. API Changes

// POST /api/visitors/:id/check-in
{
  escortId: string;       // Required in handoff mode
  handoffMode: boolean;   // Flag for escort mode
  ndaAccepted: boolean;
  photoUrl?: string;
}

// Response includes escortRequired: true

3. Badge Page Updates

When in escort-handoff mode, the badge page should:

• Display "Escorted by: [Staff Name]"
• Show a prominent "ESCORT REQUIRED" badge
• Add "Return Device to Staff" button after registration
• Disable "Send to My Phone" option

4. Staff Authentication

For staff to initiate handoff mode, they should:

• Be logged into the app on their device
• Have appropriate permissions (e.g., can_escort_visitors)
• Their user ID auto-populates as escort

UI Mockup Concepts

Handoff Initiation Screen (Staff View)

┌─────────────────────────────────────┐
│     777 Wolfpack Visitor Kiosk      │
│                                     │
│   ┌─────────────────────────────┐   │
│   │    📱 Escort Mode Active    │   │
│   │                             │   │
│   │   Hand this device to the   │   │
│   │   visitor for registration  │   │
│   │                             │   │
│   │   Escort: John Smith        │   │
│   │   Badge will stay on device │   │
│   │                             │   │
│   │      [Cancel Handoff]       │   │
│   └─────────────────────────────┘   │
│                                     │
└─────────────────────────────────────┘

Post-Registration Screen (Visitor View on Staff Device)

┌─────────────────────────────────────┐
│         ✓ Registration Complete     │
│                                     │
│        [Visitor Photo]              │
│        Jane Doe                     │
│        ACME Corp                    │
│                                     │
│   ┌─────────────────────────────┐   │
│   │   🔒 ESCORT REQUIRED        │   │
│   │   Badge: V-20251211-042     │   │
│   │   Escort: John Smith        │   │
│   └─────────────────────────────┘   │
│                                     │
│   Please return this device to      │
│   your escort to complete check-in  │
│                                     │
│     [ Return to Escort View ]       │
│                                     │
└─────────────────────────────────────┘

Security Considerations

1. Session Timeout: Handoff mode should timeout after 5 minutes of inactivity
2. Escort Validation: Staff must be logged in with valid credentials
3. Audit Trail: Log device handoffs for compliance
4. Data Isolation: Visitor cannot access staff's other data on device
5. Photo Storage: Photos stored securely, not accessible via device gallery

Future Enhancements

1. Geofencing: Alert if escorted visitor moves outside allowed zones
2. NFC Badge Tap: Staff can tap NFC to transfer badge to facility kiosk for checkout
3. Multi-Visitor Escort: Staff manages multiple visitors on one device
4. Offline Mode: Queue registrations when network is unavailable

Implementation Priority

Phase	Feature	Effort
P1	Basic handoff mode toggle	Low
P1	Escort auto-assignment	Low
P1	Badge stays on device	Medium
P2	"Return device" confirmation	Low
P2	Session timeout	Low
P3	Staff authentication	Medium
P3	Geofencing	High