# Attendance and automatic zone matching — v3

## Confirmed flow
Teacher attends the student's home. Parent confirms presence and provides a system-generated attendance OTP to the tutor. Tutor submits it; the same verified session event updates BOTH student and tutor attendance. If the parent cannot verify, the tutor requests the zone admin responsible for that tuition location to review and issue an OTP. Simply requesting, generating or approving a code does not mark attendance.

## Student location meaning
Current student location must come from the student device, or a parent device explicitly confirmed to be with the student. A parent's remote location is NEVER treated as student presence. If the student has no phone/location proof, show unavailable and require documented zone-admin presence verification. Do not manufacture a GPS match. The attendance design uses permission-based, session-scoped location collection; no always-on child tracking.

## Zone and presence checks
Resolve the session's authorised tuition address to an admin-configured service-zone polygon. Independently resolve tutor and student current positions and compare with the assigned zone and tuition location. Same zone alone does not prove attendance. Check proximity to the address (configurable site geofence), accuracy, freshness, session assignment and allowed time window. Discovery radius 5/10/15 km is NOT the attendance geofence. Missing/overlapping polygons, poor accuracy, denied permissions, stale GPS, mismatched location or missing student device enter exception review. Boundary cases require authorised resolution; never silently choose a nearby admin by phone distance. Route to assigned zone admin with an escalation queue if no admin is available.

## Proposed parameters (not final BF policy)
Demo OTP: 6 digits, expires after 120 seconds, max 5 failed attempts, single use. Production TTL, rate limits, attendance geofence and class time window must be approved/configured by BF. Attendance verifies presence at check-in. Full class duration/completion and any compensation eligibility require separate policy and records; no automatic class completion or payout from this OTP alone.

## Parent path
Tutor opens assigned class → shares location → request sent to authorised guardian → guardian reviews map and confirms student/tutor present → server issues session-bound code → parent shares code with tutor → tutor submits → server verifies code AND all required current checks → atomic paired attendance → notifications/record in both accounts.

## Zone admin fallback
Tutor supplies reason → assigned zone admin sees session, address, tutor fix/accuracy/time, student fix if available and exceptions → admin records how presence was independently verified → approve and issue session-specific OTP OR reject → admin gives OTP to tutor → tutor submits → authorised, time-bound exception/valid checks plus OTP are verified → atomic paired record, source=zone_admin. An approval must not bypass unrelated assignment/time/authorisation checks. Notify guardian of admin-verified attendance and provide a dispute route.

## Required backend design
- Session belongs to an assigned student+tutor and authorised zone. Validate all role/record ownership on the server.
- Challenge: session_id, issuer_source, issuer_id, subject IDs, zone ID, expiry, attempts, used_at, hashed code. Regeneration invalidates earlier code. No raw OTP in logs, analytics or tutor pre-verification payloads.
- A unique verified attendance event per session/check-in. Consume challenge and update student+tutor projections in ONE transaction with an idempotency key / unique constraint. Concurrent submissions must not create duplicates or partial attendance.
- Record time, GPS source, accuracy, fix freshness, applicable geofence policy, reviewer exception and reason. Retain location only as long as needed under the agency's defined retention policy and restrict visibility to involved roles.
- Audit parent/admin issuer, fallback reason, reviewer, outcome, corrections and notification delivery without exposing raw code.
- Parent code endpoints must never be available to tutor. Zone approvals require the relevant zone permission. Tutors cannot self-mark attendance or access student package tier/duration/fees through attendance APIs.
- Support corrections by audited admin amendment, not destructive history rewrite. Rejection/missing evidence remains pending/unverified; do not automatically mark absence without a defined attendance policy.

## Prototype versus production
Demo uses browser localStorage and fixed sample codes: parent 482619, admin 730284. They work only after the corresponding issuance action. The browser checks expiry, attempts and reuse to illustrate the flow, not secure it. A user can inspect/edit this demo; no authentication, real GPS, real codes, zone polygon engine, messaging or payments exist. Map, distances and timestamps labelled sample are fixtures. Multi-device or real account syncing requires a backend.