Access Control Mobile App Guide

Scenario matrix

This is the live-event playbook. Expected is what the current Home laser path (processBadgeScan) does, unless a row says otherwise.

Camera scan (SCANQR/useBadgeScanner) and unused DashBoardScreen do not always match. Those mismatches are called out. Do not tell a lead “the app always does X” if they scanned with the camera.

Base URL: selected at launch from src/config/clients.ts
ADNEC https://registration.xporience.com/v2/scan/api · DMG https://dmg-reg.xporience.com/v2/scan/api · Xporience https://reg.xporience.com/v2/scan/api · Terrapinn https://terrapinn.xporience.com/v2/scan/api
Every call is POST to that URL with { operation, EPTOKEN }.

Client selection

Scenario	Expected	Mobile action	Expected status	Failure handling	Owner
First launch / upgrade with no stored client and no session	Picker, no API	Gate in `Routes` after persist rehydrate	—	Must pick ADNEC, DMG, Xporience, or Terrapinn	Mobile
Upgrade while already logged in, no stored client	Treat as DMG (old hardcoded URL), persist it	Infer `LEGACY_CLIENT_ID`	—	Avoid interrupting a live gate	Mobile
Client already stored	Skip picker	Read `appStateInfo.selectedClientId`	—	Login / app as today	Mobile
Login while ADNEC selected	Requests hit registration host	`getBaseUrl()` at request time	Same as login rows	Wrong client looks like a login failure	Mobile host; backend auth
Login while DMG selected	Requests hit dmg-reg host	Same	Same as login rows	Same	Mobile host; backend auth
Login while Xporience selected	Requests hit reg.xporience host; JWT signed with Xporience secret	Same	Same as login rows	HTML 403 = WAF/UA; JSON 401 Invalid Data = credentials/payload	Mobile host + secret; backend auth
Login while Terrapinn selected	Requests hit terrapinn host	Same	Same as login rows	Same	Mobile host; backend auth
Change client while logged out, no unsynced for current client	New host used after pick	Login “Change”	—	Synced history kept, filtered by `client_id` (clients never share counts/queues)	Mobile
Change client while current client has unsynced rows	Block	Alert	—	Cancel (log in and sync) or wipe those unsynced rows	Mobile
Legacy scan row with no `client_id`	Treated as DMG	`resolveBadgeClientId`	—	Shown only on DMG	Mobile

Login — `operation: userLogin`

Scenario	Expected	Mobile action	Expected status	Failure handling	Owner
Valid credentials	Session created, go to space selection	POST login JWT (username, password, device_id)	HTTP 200 and body `code` 200 with `data`	Store user in Redux (`storeUserDetails`). Clear `userToken` AsyncStorage key. Do not store a bearer token.	Mobile: request + persist user. Backend: authenticate.
Blank username/password	Error, no request	UI validation	—	“Credentials can not be left blank.”	Mobile
Username contains space	Error, no request	UI validation	—	“Username cannot contain spaces.”	Mobile
No internet	Offline message, no request	`isInternetConnected()`	—	“You’re offline…”	Mobile (device network)
Wrong credentials / bad request	Error, stay on login	POST	400	Show backend `message`	Backend message; mobile display
Unauthorized / invalid login data	Error, stay on login	POST	401	Show backend `message` (e.g. “Invalid Data”)	Backend auth; mobile display
Device already logged in elsewhere	Error	POST	409	Show message, remove `userToken`	Backend session rule
Server error	Error, no session	POST	500	Sanitized message (no AWS/S3 text) via `loginErrorUtils`	Backend availability
Timeout / DNS / network	Error, no session	POST	Axios `ECONNABORTED` / `ERR_NETWORK`	Connection/timeout copy	Infrastructure or device
200 but missing `data`	Error, no session	POST	200 with empty payload	“Invalid login response”	Contract
Login QR invalid	Error	Camera parse JSON or `user:pass`	—	“Invalid login QR”	Mobile

Space list — `operation: getSpaceList`

Scenario	Expected	Mobile action	Expected status	Failure handling	Owner
Spaces returned	List shown	POST JWT (event_id, device_id)	200 with `data` array	Cache in component ref, not Redux	Backend data; mobile render
Empty list	Info	POST	200 empty	“No spaces available”	Backend assignment
Invalid space objects	Error	POST	200 but missing `space_name`	Filter invalid rows; error if none valid	Contract
API failure after login	Fallback to current space if already selected, else empty	POST	Non-200 / throw	Error toast; may keep previous space	Mixed
User taps a space with unsynced scans for current space	Block until those scans sync	`generateLead` per offline row	See sync rows	“Please sync all offline badges before changing space”	Mobile queue + backend accept
User taps a space, current space queue empty	Space written to Redux user	No extra API	—	`storeUserDetails` with space_id, space_name, type, assigned_badges	Mobile session

Space list is not persisted as its own store. After kill, space comes back from persisted userDetails.

Badge scan flow (Home laser)

Floor source of truth: processBadgeScan (Zebra DataWedge / Home laser). Camera path can differ — see the matrix below.

Loading diagram…

Tree form (same path):

Zebra / tap scan (DataWedge or Camera)
  └─ Same badge < 1.2s ago? ──yes──► Ignore (hardware dedupe)
  └─ no ──► Badge format OK? ──no──► Invalid Badge (error sound)
  └─ yes ──► Space selected? ──no──► “Please select a space first”
  └─ yes ──► Visitor + already scanned today (same space)?
                └─ yes ──► “Successful Re-checkin” (no second save)
                └─ no ──► Online? ──no──► Success toast + save offline (synced=false)
                           └─ yes ──► generateLead (JWT)
                                        ├─ 200/201 + sync_status=1 ──► Success + save online (synced=true)
                                        ├─ 200/201 + sync_status ≠ 1 / missing ──► Restricted (no save)
                                        ├─ 801 ──► “Select another Space” (no save)
                                        ├─ 403 ──► Restricted (no save)
                                        ├─ 404 ──► Invalid badge (no save)
                                        ├─ 409 ──► Logout
                                        └─ 400/401/408/5xx/timeout/network ──► Success toast + save offline

Badge scan — `operation: generateLead` (Home laser = source of truth for “what we claim”)

JWT payload: badge_number, event_id, badge_type (Visitor if type === '1' else Conference), visited_date (event timezone), sync_date (device ISO), user_id, space_id, device_id.

Scenario	Expected (Home laser)	Camera path (`useBadgeScanner`)	Owner
Empty / too short / URL / non-alphanumeric	“Invalid Badge”, no save	Same idea, slightly different charset (`@` allowed on Home, not camera)	Mobile validation
No space selected (`user.data.type` missing)	“Please select a space first”	Different role gate (“Something Went Wrong with this User”)	Mobile
Same badge, same day, same space, Visitor (`type === '1'`)	“Successful Re-checkin”, no second save	Duplicate check runs after the API call (order differs)	Mobile local rule
Conference (`type !== '1'`) same badge again	Allowed as a new scan	Allowed	Product rule — confirm with backend if this is intended
Same badge within 1.2s	Ignored (dedupe)	`processingRef` lock	Mobile hardware debounce
Device offline / NetInfo says offline	Success + save offline	Success + save offline	Mobile fallback
HTTP 200/201 and `data.sync_status === 1`	Success + save online (`synched: true`, Valid)	Similar	Backend validity; mobile persist
HTTP 200/201 and `sync_status` missing or not 1	“Restricted Badge”, no save	Treat as restricted / no save (verify on camera — trail partly duplicated)	Backend validity
HTTP 801	“Select another Space” (or backend message), no save	Camera/Dashboard look for 503, not 801	Contract mismatch — see risks
HTTP 403	“Restricted Badge”, no save	Restricted, no save	Backend
HTTP 404	“Invalid badge number”, no save	Invalid, no save	Backend
HTTP 409	Logout, clear `userToken`	Logout	Backend session
HTTP 408 / timeout / network error	Success + save offline	Camera: timeout → offline. Dashboard laser: 408 does not save	Mixed — do not claim one behavior
HTTP 400 / 401 / 405 / 407 / other 4xx except no-save list	Error toast + save offline	Similar but not identical lists	Mixed
HTTP 5xx (not treated as 801)	Error + “Saving offline”	503 on camera = no save; other 5xx offline	Mixed
Ambiguous / missing status	Success + save offline (conservative)	Varies	Mobile

Operator-facing copy “Successfully Checked in” is used for both online-valid and offline-queued scans on the Home path. That is why “the phone said success” is not proof the server stored the lead.

Sync unsynced (header refresh / space switch)

Scenario	Expected	Mobile action	Owner
Offline	Block	NetInfo	Mobile
No unsynced rows for current space	“No badge data to refresh” (header) or allow space change	Filter by space + user	Mobile
Row syncs with 200 + `sync_status === 1`	Move to online array, drop from offline	`generateLead`	Backend accept; mobile arrays
503 during bulk sync	Keep in offline queue	Header/space sync look for 503, not 801	Contract mismatch
403 / 404 / 408 during bulk sync	Mark processed with Restricted / Invalid / Timeout, `synched: true`	Removed from retry queue	Intent unconfirmed — treated as final, not retry
409 mid-bulk	Save already-synced rows, then logout	Header path	Backend session
5xx / 401	Keep in offline queue	Retry later	Backend / infra

Bulk sync is not a single transaction. Kill mid-loop can leave a mix of synced and unsynced rows. There is no rollback.

Export Excel / send report

Scenario	Expected	API	Owner
No scans for current space	Error, no file	None	Mobile
Password wrong (`excel_security_password` from login)	“Incorrect password”	None	Mobile vs password issued by backend at login
Password QR for excel/send/logout/space	Same as typing the password	None	Mobile
Export	XLSX written to app Documents dir	None	Mobile filesystem
Send report	Device mail composer with attachment	None — `react-native-mail`	Mobile + device Gmail. Recipients from login `email_id_for_checkin_data`

There is no “upload report to server” API in this app.

Logout

Scenario	Expected	Owner
Offline	Blocked: connect and sync first	Mobile `logoutGuard`
Unsynced leads for current space	Blocked with count	Mobile
Allowed	`logoutUser()` clears Redux user/token; badge arrays stay. Auth stack shows because `user` is null	Mobile. Product choice: scans survive logout

How to fill a hole in this matrix

If a status appears that is not in the table:

Capture HTTP status, body code, body message, sync_status.
Do not guess. Add a row here after the incident.
Note which scan path produced it (Home laser vs camera).