NTK-10003 — Unregistered Guest Self-Service Check-in¶

Affected Capabilities¶

Affected Services¶

• svc-check-in
• svc-guest-identity
• svc-scheduling-orchestrator

Architecture Decisions¶

• ADR-006
• ADR-007
• ADR-008
• ADR-009

Solution Contents¶

• Requirements
• Analysis
• Decisions
• Impact Assessments (4)
• User Stories
• Implementation Guidance
• Risk Assessment
• Capability Mapping

Related Solutions¶

Solutions that share services or capabilities with this design:

Problem Statement¶

Unregistered guests (partner bookings, gift card recipients, companions) cannot use self-service check-in kiosks and must queue for staff-assisted check-in. This results in average wait times of 22 minutes during peak hours, annual staffing costs of approximately $840K for manual check-in support, and a 34% dissatisfaction rate among partner-booked guests.

Solution Overview¶

Implement a reservation lookup and identity verification flow in svc-check-in that enables unregistered guests to access the self-service kiosk. The solution uses an orchestrator pattern within svc-check-in to coordinate verification across multiple downstream services, with a graceful fallback to partner integration systems when direct reservation lookup fails.

The orchestrator performs the following sequence: 1. Verify identity fields against reservation data 2. Find or create a temporary guest profile 3. Check safety waiver and gear assignment status (in parallel) 4. Grant a time-scoped kiosk session

Architecture Diagram¶

See: lookup-orchestration.puml for the full sequence diagram.

New Endpoint Specification¶

POST /check-ins/lookup-reservation¶

Service: svc-check-in

Purpose: Verify an unregistered guest's identity against a reservation and grant temporary kiosk access for self-service check-in.

Request Schema¶

{
  "last_name": "string (required, 1-100 chars)",
  "confirmation_code": "string (required, 8 chars alphanumeric, case-insensitive)",
  "adventure_date": "string (required, ISO 8601 date: YYYY-MM-DD)",
  "participant_count": "integer (required, 1-20)",
  "kiosk_device_id": "string (required, UUID of the kiosk terminal)"
}

Response Schema - Success (200 OK)¶

{
  "session_token": "string (JWT, 30-minute expiry)",
  "reservation_id": "string (UUID)",
  "guest_profile_id": "string (UUID, temporary or matched profile)",
  "adventure_name": "string",
  "adventure_date": "string (ISO 8601)",
  "check_in_status": {
    "waiver_complete": "boolean",
    "waiver_url": "string (nullable, URL for digital waiver if incomplete)",
    "gear_assigned": "boolean",
    "gear_items": [
      {
        "item_type": "string",
        "size": "string",
        "pickup_location": "string"
      }
    ]
  },
  "participants": [
    {
      "name": "string",
      "role": "string (PRIMARY | COMPANION)"
    }
  ]
}

Response Schema - Failure (404 Not Found)¶

{
  "error": "RESERVATION_NOT_FOUND",
  "message": "We couldn't find a matching reservation. Please verify your details or visit the service desk for assistance.",
  "remaining_attempts": "integer (attempts left in rate limit window)"
}

Response Schema - Rate Limited (429 Too Many Requests)¶

{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Too many attempts. Please visit the service desk for assistance.",
  "retry_after_seconds": "integer"
}

Orchestration Flow¶

Step 1: Validate and Normalize Input¶

• Normalize confirmation_code to uppercase
• Validate adventure_date is today or within the next 24 hours (early check-in allowed)
• Validate participant_count is between 1 and 20

Step 2: Lookup Reservation (svc-reservations)¶

• Call POST /reservations/search with verification fields
• If found: proceed to Step 3
• If not found: proceed to Step 2a (Partner Fallback)

Step 2a: Partner Fallback (svc-partner-integrations)¶

• Call POST /partner-integrations/verify-booking with confirmation code and last name
• If partner confirms booking: create reservation record and proceed to Step 3
• If partner lookup fails or is unavailable (circuit breaker open): return 404 to guest

Step 3: Find or Create Guest Profile (svc-guest-profiles)¶

• Call GET /guest-profiles?reservation_id={id} to check for existing profile
• If no profile exists: call POST /guest-profiles/temporary with last name and reservation ID
• Returns guest_profile_id for session creation

Step 4: Parallel Checks (svc-safety-compliance + svc-gear-inventory)¶

Execute in parallel:

• svc-safety-compliance: GET /safety-compliance/waivers?reservation_id={id}
• Returns waiver completion status and digital waiver URL if incomplete
• svc-gear-inventory: GET /gear-inventory/assignments?reservation_id={id}
• Returns gear assignment list and pickup locations

Step 5: Create Kiosk Session¶

• Generate JWT session token with claims: guest_profile_id, reservation_id, kiosk_device_id
• Set 30-minute expiry
• Store session in Redis with kiosk device ID as secondary key (one active session per kiosk)
• Return aggregated response to kiosk

Fallback Behavior¶

If the primary reservation lookup (Step 2) fails to find a match, the orchestrator attempts partner verification before returning a failure:

1. Extract partner identifier from confirmation code prefix (e.g., EM- for ExploreMore, TF- for TrailFinder, WP- for WildPass)
2. Route to the appropriate partner adapter in svc-partner-integrations
3. If partner confirms the booking, svc-reservations creates a synced reservation record for subsequent lookups
4. Circuit breaker configuration: 30-second timeout, 50% error rate threshold, 60-second recovery window
5. If partner integration is unavailable, return 404 with messaging that directs the guest to the service desk with priority queuing

Security Considerations¶

Impacted Components¶

Total estimated effort: 14.5 days across teams (parallelizable to ~6 days calendar time)

Deployment Sequence¶

Services must be deployed in the following order to avoid runtime errors:

1. svc-reservations - New search endpoint must be available before svc-check-in calls it
2. svc-guest-profiles - Temporary profile endpoint must be available before svc-check-in calls it
3. svc-safety-compliance - Extended waiver lookup must be available before svc-check-in calls it
4. API Gateway - Rate limiting rules for the new endpoint
5. svc-check-in - Orchestrator endpoint (deployed last, depends on all upstream services)
6. Kiosk UI - New check-in flow (deployed after svc-check-in is confirmed healthy)

Phased Rollout Plan¶

Feature flag: KIOSK_UNREGISTERED_CHECKIN_ENABLED (per base camp location, default: false)

Testing Strategy¶

Unit Tests¶

• Orchestration logic with mocked downstream services
• Input validation and normalization
• Rate limiting counter behavior
• JWT session token generation and validation

Integration Tests¶

• svc-check-in to svc-reservations: reservation lookup with valid and invalid inputs
• svc-check-in to svc-guest-profiles: temporary profile creation and deduplication
• svc-check-in to svc-safety-compliance: waiver status retrieval by reservation ID
• Partner fallback flow with simulated partner responses

End-to-End Tests¶

• Full kiosk check-in flow (requires kiosk emulator environment)
• Rate limiting verification across multiple kiosks
• Session expiry and cleanup
• Concurrent lookup requests (target: 100 concurrent, p95 under 5 seconds)

Security Tests¶

• PII masking verification in all log outputs
• Rate limit bypass attempt validation
• Session token scope enforcement
• Cross-reservation data isolation

Version History¶