EP-005A: Check-In / Check-Out Operations
Parent Epic: EP-005 Front Desk Operations Split Note: EP-005 has been split into sub-epics EP-005A, EP-005B, EP-005C, EP-005D. This file covers check-in, check-out, room moves, registration, and kiosk self-service.
| Field | Value |
|---|---|
| Epic ID | EP-005A |
| Epic Name | Check-In / Check-Out Operations |
| Parent Epic | EP-005 Front Desk Operations |
| Owner | Front Desk Module Lead |
| Created | 2026-03-27 |
| Last Updated | 2026-03-27 |
| Status | In Progress |
| Priority | P0 - Critical |
1. Business Objective
Transform the guest arrival and departure experience from the current industry average of 8-12 minutes (check-in) and 5-8 minutes (check-out) to under 3 minutes and under 2 minutes respectively. This is the hotel's first and last physical touchpoint with the guest — speed and accuracy here directly determine NPS scores and review ratings. For a 100-room Indian hotel with ~80 arrivals/day, shaving 7 minutes per check-in recovers approximately 9 staff-hours daily.
2. Audience
| Role | Interaction |
|---|---|
| Front Desk Agent | Primary: standard check-in/out, room assignment, keycard encoding |
| Front Desk Manager | Room moves, upgrades, rate overrides, walk-in approvals |
| Guest (Self) | Kiosk self-check-in, express pre-arrival web check-in |
| Housekeeping | Room status updates consumed by check-in flow |
3. Scope
3.1 In Scope
- Standard check-in with Aadhaar / passport ID scanning and digital registration card
- Express / pre-arrival check-in (guest completes details before arrival via booking engine link)
- Batch check-in (group arrivals — multiple rooms checked in simultaneously)
- Kiosk self-check-in (5-step wizard: find booking → verify ID → select room → encode key → welcome screen)
- Standard check-out with folio review and automated invoice dispatch
- Express check-out (zero-balance folios settled automatically at configured time)
- Late check-out request and automated surcharge application
- Early check-in with dynamic room availability check and early charge posting
- Room move / upgrade with folio adjustment and new keycard encoding
- Registration card: digital PDF generation, guest signature capture (tablet/kiosk)
- C-Form generation for foreign nationals (compulsory under Foreigners Act 1946)
- Room assignment: manual, auto-suggest by guest preference, upgrade workflow
- Keycard encode, re-encode, deactivate (RFID/BLE mock and real adapters)
- Smart lock integration (BLE via @Integration decorator, currently mock)
- ID scanner integration (Aadhaar QR XML parser, passport MRZ TD3, DL parser)
- Walk-in quick booking + immediate check-in in a single flow
3.2 Out of Scope
- Folio charging and payment recording (EP-005B)
- Night audit (EP-005C)
- Concierge, wake-up calls, PBX (EP-005D)
- Revenue management / BAR engine (EP-007)
- Housekeeping workflows (EP-006)
- OTA / channel sync (EP-009)
4. Current Implementation Status
4.1 Backend — frontdesk-service
| Controller / Endpoint | Status | Notes |
|---|---|---|
POST /checkin | Built | Full workflow: ID validation, room assignment, keycard |
POST /checkout | Built | Folio settlement trigger, room → DIRTY, Kafka event |
POST /checkin/express | Partial | Endpoint exists; not wired to booking engine guest link |
POST /checkin/batch | Not Started | Schema designed; controller not yet implemented |
POST /checkin/walkin | Partial | Works but requires too many manual steps |
PATCH /reservations/:id/room-move | Built | Folio transfer on room move included |
PATCH /reservations/:id/early-checkin | Built | Dynamic charge calculation |
PATCH /reservations/:id/late-checkout | Built | Auto-surcharge based on property policy |
POST /keycards/encode | Built | RFID/BLE mock adapter via @Integration decorator |
POST /keycards/reencode | Built | - |
DELETE /keycards/:id | Built | Deactivate |
POST /id-scan/aadhaar | Built | QR XML parser, extracts name/DOB/address/UID |
POST /id-scan/passport | Built | MRZ TD3 parser |
POST /id-scan/dl | Built | Driving licence parser |
POST /registration-cards | Partial | PDF generates; formatting/legal fields need polish |
POST /cforms | Built | Foreign national C-Form, list/filter endpoints |
| Kiosk check-in page (dashboard) | Built | 5-step wizard component in 02-hmp-web-dashboard |
4.2 Dashboard — 02-hmp-web-dashboard
| Component | Status | Notes |
|---|---|---|
| Room Grid View | Built | Real-time status, color-coded by state |
| Arrivals List | Built | Filterable, sortable, with check-in action button |
| Departures List | Built | Balance alerts, check-out action |
| In-House Guest List | Built | Search by guest, floor, room type |
| Check-In Form (wizard) | Built | Multi-step: reservation → ID scan → room → key |
| Check-Out Form | Built | Folio summary, final payment, invoice dispatch |
| Walk-In Quick Form | Partial | Exists; needs streamlining to fewer steps |
| Express Check-In UI | Not Started | Guest-facing pre-arrival form not yet connected |
| Kiosk Self-Check-In Page | Built | /kiosk/checkin — standalone 5-step wizard |
5. Gap Analysis
| # | Gap | Impact | Effort | Priority |
|---|---|---|---|---|
| 1 | Express check-in not connected to booking engine guest link | High | M | P2 |
| 2 | Batch check-in controller missing for group arrivals | Medium | M | P2 |
| 3 | Walk-in flow requires too many steps (6+) | High | S | P1 |
| 4 | Registration card PDF formatting (legal compliance risk) | Medium | S | P1 |
| 5 | Smart lock integration is mock-only | Medium | L | P3 |
6. User Stories
| Story ID | Title | Priority | Points | Sprint | Status |
|---|---|---|---|---|---|
| US-005-01 | Standard Check-In | P0 | 8 | 1 | Built |
| US-005-02 | Standard Check-Out | P0 | 8 | 1 | Built |
| US-005-08 | Room Assignment (Auto-Suggest) | P1 | 5 | 2 | Built |
| US-005-09 | Registration Card & C-Form | P1 | 5 | 3 | Partial |
| US-005-10 | Aadhaar / Passport ID Scan | P1 | 8 | 3 | Built |
| US-005-12 | Keycard Encode / Manage | P1 | 5 | 3 | Built |
| US-005-13 | Early Check-In / Late Check-Out | P1 | 5 | 4 | Built |
| US-005-14 | Room Move / Upgrade | P1 | 5 | 4 | Built |
| US-005-15 | Walk-In Quick Booking | P1 | 5 | 4 | Partial |
| US-005-16 | Express Check-In (Pre-Arrival) | P2 | 8 | 5 | Partial |
| US-005-17 | Smart Lock Integration | P3 | 13 | 6 | Partial |
| US-005-21 | Room Grid Real-Time View | P0 | 5 | 1 | Built |
| US-005A-01 | Batch / Group Check-In | P2 | 8 | 5 | Not Started |
| US-005A-02 | Kiosk Self-Check-In Wizard | P2 | 13 | 5 | Built |
| US-005A-03 | Express Check-Out (Auto-Settle) | P2 | 5 | 5 | Not Started |
7. Detailed User Stories
US-005-01: Standard Check-In
As a Front Desk Agent, I want to check in a guest with a confirmed reservation by scanning their ID, assigning a room, and issuing a keycard, So that the guest can access their room quickly and the hotel has compliant registration records.
Priority: P0 | Points: 8 | Sprint: 1 | Status: Built
Implementation Status
Fully implemented in frontdesk-service. Dashboard wizard: select reservation → scan Aadhaar QR or passport MRZ → confirm room → encode keycard → print/email registration card. Publishes Kafka event guest.checked_in on completion.
Acceptance Criteria
Scenario: Successful check-in for confirmed reservation
Given a reservation with status "CONFIRMED" for guest "Rajesh Sharma"
And the room "301" is in "CLEAN" status
When the front desk agent scans the guest's Aadhaar card
And assigns room "301"
And encodes the keycard
Then the reservation status changes to "CHECKED_IN"
And the room status changes to "OCCUPIED"
And a registration card PDF is generated with guest details
And a Kafka event "guest.checked_in" is published
And check-in completes in under 3 minutes
Scenario: Check-in blocked for unclean room
Given a reservation for room "405" which is in "DIRTY" status
When the front desk agent attempts check-in
Then the system warns "Room 405 is not ready"
And suggests alternative clean rooms of the same type
US-005-02: Standard Check-Out
As a Front Desk Agent, I want to check out a guest by reviewing and settling their folio then generating a GST-compliant invoice, So that the room is released and the hotel has accurate financial records.
Priority: P0 | Points: 8 | Sprint: 1 | Status: Built
Implementation Status
Check-out API settles all open folios, generates GST e-invoice (IRN via frontdesk-service EInvoiceModule), updates room to DIRTY, publishes guest.checked_out. Dashboard form shows folio summary, accepts final payment, triggers invoice email.
Acceptance Criteria
Scenario: Successful check-out with zero balance
Given guest "Anita Desai" is in room "201" with INR 0 balance
When the agent initiates check-out
Then a GST e-invoice is generated with valid IRN and SAC code 9963
And room "201" changes to "DIRTY"
And the guest receives an email/SMS with invoice link
And a Kafka event "guest.checked_out" is published
Scenario: Check-out blocked with outstanding balance
Given guest has folio balance of INR 2,400
When the agent initiates check-out
Then the system requires payment before proceeding
And shows payment options: Cash, Card (Razorpay), UPI QR
US-005A-01: Batch / Group Check-In
As a Front Desk Manager, I want to check in an entire group (e.g., a corporate booking of 20 rooms) in a single operation, So that the group can be roomed quickly without checking in each reservation individually.
Priority: P2 | Points: 8 | Sprint: 5 | Status: Not Started
Implementation Notes
POST /checkin/batch— accepts array of{ reservationId, roomId }pairs- Validates all rooms are CLEAN before proceeding; returns partial success list
- Issues keycards in sequence; prints batch registration cards
- Publishes individual
guest.checked_inKafka events for each reservation
Acceptance Criteria
Scenario: Batch check-in for corporate group
Given a group booking with 20 confirmed reservations
And 20 CLEAN rooms are pre-assigned by the manager
When the manager triggers "Batch Check-In"
Then all 20 reservations change to CHECKED_IN within 60 seconds
And a summary report shows 20 successes (and any failures)
And individual registration cards are queued for printing
Scenario: Partial failure handling
Given 20 reservations in batch and room "505" is DIRTY
When batch check-in runs
Then 19 reservations succeed
And reservation for room "505" is flagged with reason "Room not clean"
And the manager can resolve the single failure manually
US-005A-02: Kiosk Self-Check-In
As a Guest, I want to check myself in at a kiosk in the hotel lobby without waiting in the front desk queue, So that I can get to my room immediately upon arrival.
Priority: P2 | Points: 13 | Sprint: 5 | Status: Built (dashboard kiosk page)
Implementation Notes
- 5-step wizard in
02-hmp-web-dashboard/app/kiosk/checkin/(Phase 6.1 deliverable) - Step 1: Find booking (confirmation number or last name + arrival date)
- Step 2: Verify identity (ID scan or manual Aadhaar/passport entry)
- Step 3: Select/confirm room
- Step 4: Key card encoding (hardware mock via
KeyCardSimulator) - Step 5: Welcome screen with room number, WiFi, checkout time
POST /checkinsame endpoint as standard check-in; kiosk flag setssource: KIOSK
Acceptance Criteria
Scenario: Guest self-check-in at kiosk
Given a confirmed reservation for tomorrow
When the guest enters their confirmation number at the kiosk
And scans their Aadhaar at the ID scanner
Then the system shows their assigned room
And after confirmation encodes a keycard
And displays welcome screen with floor map highlight
And sends confirmation SMS/email within 30 seconds
Scenario: ID mismatch
Given a reservation for "Rohan Verma"
When ID scan returns "Rahul Verma"
Then kiosk shows "Identity verification failed — please visit front desk"
And no keycard is issued
US-005A-03: Express Check-Out (Auto-Settle)
As a Front Desk Manager, I want to configure express check-out so that guests with zero-balance folios are automatically checked out at their departure date, So that night audit and morning operations are not blocked by lingering in-house records.
Priority: P2 | Points: 5 | Sprint: 5 | Status: Not Started
Implementation Notes
- Night audit (
POST /audit/run) should callcheckoutExpressEligible()on all departures with zero balance - Criteria: departure date = audit date, folio balance = 0, guest has email on file
- Send folio copy via email; update room to DIRTY; publish
guest.checked_out
Acceptance Criteria
Scenario: Automatic express check-out during night audit
Given 5 departures scheduled for today with zero balances and emails on file
When night audit runs at 02:00 IST
Then all 5 reservations are checked out automatically
And folio PDFs are emailed to each guest
And rooms change to DIRTY
And night audit report lists "5 express check-outs"
8. Dependencies
| Dependency | Type | Epic / Service | Status |
|---|---|---|---|
| Reservation data (booking, guest info) | Upstream | EP-003 / reservation | Available |
| Guest profile (preferences, loyalty) | Upstream | EP-004 / guest | Available |
| Property / room inventory | Upstream | EP-002 / property | Available |
| Auth / RBAC (front desk roles) | Upstream | EP-001 / auth | Available |
| Housekeeping room status | Peer | EP-006 / housekeeping | Available |
| Folio & invoice (EP-005B) | Sibling | EP-005B / frontdesk | Available |
| Night audit trigger (EP-005C) | Sibling | EP-005C / frontdesk | Available |
| Booking engine (express pre-arrival) | Peer | EP-011 / booking-engine | Partial |
| Keycard hardware (BLE/RFID) | Infra | libs/integrations | Mock only |
| ID scanner hardware | Infra | libs/integrations | Built |
| Kafka event bus | Infra | Docker / Kafka | Available |
| Redis (room status cache) | Infra | Docker / Redis | Available |
9. Acceptance Criteria (Sub-Epic Level)
- AC-EP-005A-01: A standard check-in for a pre-booked guest (ID scan → room assign → keycard) completes in under 3 minutes.
- AC-EP-005A-02: A standard check-out (folio review → payment if needed → invoice) completes in under 2 minutes.
- AC-EP-005A-03: Kiosk self-check-in handles 100% of cases where the guest identity matches the booking; ID mismatches gracefully route to front desk.
- AC-EP-005A-04: Batch check-in for a 20-room group completes within 60 seconds with a per-room success/failure summary.
- AC-EP-005A-05: Room grid view updates within 2 seconds of a room status change via Kafka event.
- AC-EP-005A-06: Registration cards comply with Indian hotel registration requirements; C-Forms generated for all foreign national check-ins.
- AC-EP-005A-07: All check-in and check-out events publish Kafka events consumed by notification service (EP-014).
10. Technical Notes
- Controller file:
01-hmp-backend/apps/frontdesk-service/src/checkin/checkin.controller.ts - Service file:
01-hmp-backend/apps/frontdesk-service/src/checkin/checkin.service.ts - Keycard adapter:
01-hmp-backend/libs/integrations/src/lib/hardware/keycard/ - ID scanner:
01-hmp-backend/apps/frontdesk-service/src/id-scan/ - C-Form:
01-hmp-backend/apps/frontdesk-service/src/cform/ - Kiosk page:
02-hmp-web-dashboard/app/kiosk/checkin/page.tsx - Room state machine:
01-hmp-backend/libs/common/src/lib/room-status/(9 valid transitions, throwsBadRequestExceptionon invalid) - The
EInvoiceModulerequiresEINVOICE_MOCK=truein Docker env; real NIC credentials needed for production IRN generation. - Smart lock uses
@Integration(ServiceMode.MOCK)decorator vialibs/integrations; swap toLIVErequires real BLE hardware driver.