03 — User Journey (Biometric Module)

• 1. Device Setup (Ops Manager) — (planned)
• 2. Enrollment (Clerk) — (planned)
• 3. Daily Gate Flow (real ingest + planned pipeline)
• 4. Verify a Disputed Check-in (Clerk) — (planned)
• 5. Sync Failure / Offline Device (IT Admin) — (planned)
• 6. Retention / Purge (Platform Admin)
• Journey → screen map

Journeys trace the module's life cycle: device setup → sync → punch ingestion → attendance derivation → dispute. Real steps are quoted with sources; everything after ingestion is (planned) per the blueprint. Journeys for the admin console (Flutter, forward-looking) and the server pipeline are both captured.

1. Device Setup (Ops Manager) — (planned)

1. Admin opens Biometric → Devices (GET /biometric/devices, blueprint Biometric.md:25).
2. Taps Register device → form (POST /biometric/devices, blueprint :26): name, deviceId, model, location, status.
3. Server enforces unique (tenantId, deviceId) (biometric-device.schema.ts:36).
4. Device appears active (DeviceStatus.ACTIVE default, biometric-device.schema.ts:24-25).
5. Admin tests one punch → finds it in logs next sync.

Today: no device API exists; the schema + repo are ready (biometric-device.schema.ts, repositories/biometric-device.repository.ts). UI must not ship until the endpoints do.

2. Enrollment (Clerk) — (planned)

1. Clerk opens Devices → [device] → Enroll.
2. Selects student (search by name/roll).
3. Device captures template → clerk confirms (≤ 3 taps — persona Arjun).
4. Server stores template + employeeCode mapping (blueprint COLLECTIONS.md:1878-1879).
5. Success screen: student name + "enrolled" chip.

Today: no template storage, no enrollment endpoint (OQ-3 in 01). Blocked on vendor SDK + storage-format decision. Also blocked on acceptance criterion "biometric capture maps to a verified student record" (ACCEPTANCE_CRITERIA.md:39).

3. Daily Gate Flow (real ingest + planned pipeline)

07:50  student scans at gate device
   ↓
device records punch (employeeCode, direction, rawPayload)   [blueprint COLLECTIONS.md:1872-1892]
   ↓
punch polled by biometric-sync job (queue BIOMETRIC_SYNC, */15 * * * *)
   ↓   (queue.constants.ts:7, scheduler.service.ts:70-76 — worker missing today)
POST /api/v1/biometric/ingest  {studentId, deviceId, timestamp, mode?}
   ↓   (biometric.controller.ts:14-18 — REAL today)
persisted as immutable biometric_logs row
   ↓   (biometric.service.ts:14-16 → biometric-log.schema.ts:7-27)
BiometricImported event → attendance-process queue   (planned, EVENTS.md:18)
   ↓
attendance.mark(source: BIOMETRIC) → AttendanceSource.BIOMETRIC   (planned; enum exists, attendance.schema.ts:18)
   ↓
parent/teacher sees check-in in attendance views

Today's actual flow stops after the ingest row is persisted — no event, no derivation, no parent visibility. The ingest endpoint is real; everything below the fold is not.

4. Verify a Disputed Check-in (Clerk) — (planned)

1. Parent questions "absent" → clerk opens Biometric → Logs.
2. Filters by student + date (GET /biometric/logs, blueprint Biometric.md:30).
3. Opens punch → sees timestamp, deviceId, mode, raw payload (biometric-log.schema.ts:12-22).
4. Confirms the punch exists → edits attendance via PATCH /attendance/:id (attendance.controller.ts:54-59) with source preserved; or finds no punch → evidence stands.

Immutability is the trust mechanism: logs "never update" (blueprint COLLECTIONS.md:1866, Biometric.md:55) — the dispute path reads, never mutates.

5. Sync Failure / Offline Device (IT Admin) — (planned)

1. Device status flips offline (enum biometric-device.schema.ts:7-11; health-check planned, blueprint Biometric.md:19).
2. Sync job retry: 4, exponential 2000 ms (blueprint RETRIES.md:38); exhausted → DLQ (blueprint Biometric.md:58).
3. Admin sees failed job in Bull-Board; resolves network; taps Sync now (POST /biometric/devices/:id/sync, blueprint Biometric.md:28).
4. Caught-up punches land as logs with their original timestamp — derivation stays correct (COLLECTIONS.md:1883).

6. Retention / Purge (Platform Admin)

biometric_logs aged > 1 year → TTL + archive (blueprint DATA_RETENTION.md:25); tenant purge reuses the existing TENANT_PURGE queue (queue.constants.ts:12).

Journey → screen map