Visitor Approval — Guest Arrives at the Gate

The marquee user journey. A guest walks up to a society’s gate. The guard logs them. The flat’s residents get a WhatsApp message. One taps approve. The guard sees green. The guest walks in. Median end-to-end time: under 30 seconds.

Note

This narrates the guest flow specifically — the canonical 2-button approval. It’s one of five visitor types, each with different mechanics (delivery is FYI-only, household staff is silently logged, etc.). See the Visitor Types overview for how they diverge, and the Resident WhatsApp Flows for the resident’s-eye screens.

Use Next / Back below (or the arrow keys) to walk through the flow. Active nodes light up; the edge being traversed at each step is highlighted in indigo with an animated dash.

What could go wrong

All residents deny

Visitor record stays in denied state; Guard PWA shows red. Guard sends the guest away.

Nobody responds within the timeout window

IVR Fallback kicks in: backend places a PSTN call to the head of household via MSG91. DTMF input on the call becomes the approval.

Two residents tap Approve simultaneously

Atomic UPDATE with status guard means only one wins. The other receives an idempotent "already approved by X" notification — no double-approve, no race.

Resident is a member of multiple flats

The template includes the flat reference. Reply attribution uses the WhatsApp context.id to pick the right pending visitor; no cross-flat leakage.

Pre-approved visitor with a code

Guard uses Code Lookup instead. The visitor row is already in the approved state; no notification fan-out needed. Skips steps 4-10 entirely.

Visit window passes without approval

Visitor Expiry Worker (scheduled) marks the row expired. Removed from the Guard PWA's active list; never reachable for approval after.

Where this is implemented

Open the Backend layer and the WhatsApp layer to see the components in their normal architectural context — including the ones not shown above (rate-limit counter, message_log audit table, head-of- family role lookup).